Étendre PrimoCRM

Tout ce qui est extensible dans PrimoCRM est collecté via un filtre WordPress, permettant ainsi à votre module complémentaire de s’enregistrer sans aucune modification du cœur. Ce sont les mêmes schémas que ceux utilisés par les fonctionnalités Pro officielles. Retrouvez la liste complète dans les Actions et filtres.

Réagir à un événement

L’extension la plus simple consiste à réagir à un événement survenu. Utilisez les crochets d’action.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Synchroniser la modification du tag avec un système externe.
}, 10, 2 );

Enregistrer un type de champ de formulaire personnalisé

Ajoutez une classe qui implémente l’interface de champ, puis enregistrez-la sur primocrm_form_field_types.

add_filter( 'primocrm_form_field_types', function ( $fields ) {
    $fields['signature'] = MySignatureField::class;
    return $fields;
} );

Votre classe implémente la même interface que les types de champs du cœur (une méthode type() ainsi que la logique de rendu et d’assainissement). Utilisez les champs intégrés situés dans includes/modules/forms/Fields/Types comme référence. Le nouveau type apparaîtra alors dans la palette du constructeur de formulaires. Consultez les Types de champs.

Enregistrer une source de migration

Une source de migration lit un système externe et le normalise pour l’intégrer dans les contacts, listes, tags et champs personnalisés de PrimoCRM. Implémentez le contrat de la source et enregistrez-le sur primocrm_migration_sources.

add_filter( 'primocrm_migration_sources', function ( $sources ) {
    $sources['mailpoet'] = new MailPoetSource();
    return $sources;
} );

Le gestionnaire d’enregistrement élimine par sécurité tout ce qui n’implémente pas l’interface de source, empêchant ainsi un module défectueux de faire planter l’importateur. Le plugin Gratuit intègre les sources CSV et FluentCRM comme références. Consultez la section Depuis un autre CRM.

Fournir un expéditeur d’e-mails

L’envoi est acheminé via le filtre primocrm_smtp_send. Renvoyez un résultat évalué à vrai pour indiquer que vous avez géré l’envoi, un WP_Error en cas d’échec, ou la valeur initiale pour transmettre l’envoi au gestionnaire suivant. C’est exactement de cette façon que les fournisseurs ESP Pro s’intègrent.

add_filter( 'primocrm_smtp_send', function ( $result, $provider, $atts, $settings ) {
    if ( $provider !== 'myesp' ) {
        return $result; // pas le nôtre ; laisser le gestionnaire suivant décider
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Échec de l\'envoi' );
}, 10, 4 );

Lorsqu’aucun gestionnaire ne prend en charge l’envoi, PrimoCRM se replie sur le système de messagerie WordPress par défaut, garantissant qu’un site mal configuré ou dont l’abonnement a expiré continue d’effectuer ses envois. Consultez Envoi et délivrabilité.

Ajouter des champs et des opérateurs pour le constructeur de conditions

Étendez le constructeur de conditions d’automatisation en filtrant primocrm_condition_options. La valeur contient un tableau fields et un tableau operators.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'Valeur à vie',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Supérieur à' ];
    return $opts;
} );

C’est ainsi que la version Pro ajoute ses champs e-commerce. Consultez Conditions et branchements.

Enregistrer un déclencheur d’automatisation

Les déclencheurs sont collectés via primocrm_automation_triggers et apparaissent dans le sélecteur d’automatisation. La méthode recommandée consiste à étendre BaseTrigger, qui s’enregistre automatiquement auprès de ce filtre. C’est exactement de cette manière que fonctionnent les intégrations natives Contact Form 7, WPForms et Fluent Forms.

Étendez BaseTrigger, définissez un triggerName unique, décrivez le déclencheur dans getTrigger() et accrochez votre propre événement. Lorsque l’événement se déclenche, récupérez le contact et injectez-le dans n’importe quelle automatisation utilisant votre déclencheur.

use PrimoCRM\modules\automations\Triggers\BaseTrigger;
use PrimoCRM\modules\automations\Triggers\Forms\ResolvesContactFromForm;
use PrimoCRM\modules\automations\AutomationProcessor;

class SuperFormsSubmittedTrigger extends BaseTrigger
{
    use ResolvesContactFromForm; // rechercher ou créer un contact par e-mail

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // s'enregistre automatiquement dans primocrm_automation_triggers

        // Accrocher l'action de soumission de votre propre plugin de formulaire :
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Métadonnées qui listent le déclencheur dans le sélecteur d'automatisation.
    public function getTrigger()
    {
        return [
            'category'    => 'Formulaires',
            'label'       => 'Formulaire SuperForms soumis',
            'description' => 'Se déclenche lorsqu\'un formulaire SuperForms est soumis',
            'icon'        => 'document-text',
        ];
    }

    public function onSubmit( $submission )
    {
        $email = $submission['email'] ?? '';
        $first = $submission['first_name'] ?? '';
        $last  = $submission['last_name'] ?? '';

        // Récupérer ou créer le contact (déclenche primocrm_contact_created lors de la création).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Intégrer le contact dans chaque automatisation active utilisant ce déclencheur.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

    public function handle( ...$args ) {}
}

// Instancier une seule fois, après le chargement de votre plugin de formulaire, pour qu'il s'auto-enregistre.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

Votre déclencheur apparaît désormais dans le constructeur d’automations, et toute soumission crée ou met à jour le contact PrimoCRM tout en exécutant les automations correspondantes.

Lorsque le plugin hôte n’est pas installé

Il n’y a rien à déverrouiller : un déclencheur enregistré est un déclencheur fonctionnel. Ce que vous devez gérer, c’est l’absence potentielle de votre propre plugin hôte. Enregistrez tout de même le déclencheur en lui fournissant une chaîne requires_plugin ; PrimoCRM l’affichera alors comme indisponible en indiquant ce qui est requis, plutôt que de laisser un vide silencieux dans le sélecteur :

add_filter( 'primocrm_automation_triggers', function ( $triggers ) {
    if ( isset( $triggers['superforms_submitted'] ) || defined( 'SUPERFORMS_VERSION' ) ) {
        return $triggers;
    }
    $triggers['superforms_submitted'] = array(
        'label'           => 'Formulaires Super Forms soumis',
        'category'        => 'Formulaires',
        'description'     => 'Se déclenche lorsqu\'un formulaire Super Forms est soumis',
        'requires_plugin' => 'Super Forms',
    );
    return $triggers;
}, 99 );

Exécutez cette action avec une priorité tardive afin que le véritable déclencheur, enregistré à 10, l’emporte toujours.

Enregistrement d’une action

Les actions personnalisées suivent le même principe avec primocrm_automation_actions (étendez la classe d’action de base, décrivez-la et implémentez son étape). Utilisez les actions du cœur situées dans includes/modules/automations/Actions comme références fonctionnelles. La même règle requires_plugin s’applique lorsque votre action requiert un plugin hôte.

Intégration depuis un système externe

Si le système d’intégration ne s’exécute pas sur le même site WordPress, utilisez l’API REST au lieu d’une classe de déclenchement. Créez ou mettez à jour un contact via une requête authentifiée POST /wp-json/primocrm/v1/contacts. Ne modifiez pas directement les tables de la base de données de PrimoCRM ; l’endpoint REST et les classes de déclenchement constituent les interfaces prises en charge et garantissent le bon fonctionnement de votre intégration lors des mises à jour.

Injecter une interface d’administration

L’application d’administration est une application monopage (SPA) React, et les filtres wp.hooks vous permettent d’y intégrer vos propres écrans. Il existe des points d’ancrage pour les onglets de réglages, les onglets de rapports, les actions sur les lignes de campagnes, les étapes de l’assistant de campagne, les panneaux de détails de campagne et les éditeurs d’e-mails, tous répertoriés dans les Actions et filtres.

Chacun d’eux renvoie des descripteurs dotés de rappels de montage plutôt que des éléments React bruts, ce qui permet à votre interface de s’afficher dans sa propre racine sans que votre version de React doive correspondre à celle de PrimoCRM. N’ajoutez pas de page d’administration autonome ; utilisez les points d’ancrage pour placer votre fonctionnalité là où l’utilisateur travaille déjà.

Astuce

Lorsque votre extension effectue des tâches lourdes, telles que l’appel d’une API externe ou le traitement d’un grand nombre de lignes, adoptez le modèle de tâche en arrière-plan de PrimoCRM plutôt de bloquer la requête. Consultez la Vue d’ensemble pour les développeurs.