Complément doc segments mailsubscribers

-  Les éléments ci-dessous complètent la documentation existante des segments avec des précisions techniques.
-  Ticket associé : https://git.spip.net/spip-contrib-extensions/mailsubscribers/-/work_items/55 , incluant un sondage sur le devenir de cette doc

Définition des segments

Il n’y a pas de table SQL dédiée aux segments. Tous les segments d’une liste sont stockés dans le champ segments de la table spip_mailsubscribinglists, sous la forme d’un tableau PHP sérialisé, indexé par id_segment.

Chaque segment est un tableau contenant id, titre, auto_update et des clés filtre_<attribut> :

[
    1 => [
        'id'          => 1,
        'titre'       => 'Francophones',
        'auto_update' => 'on',
        'filtre_lang' => 'fr',
    ],
    2 => [
        'id'                  => 2,
        'titre'               => 'Intéressés Doc ou Traduction',
        'auto_update'         => 'on',
        'filtre_groupemots_5' => '42,57',
    ],
]

La numérotation des id_segment est locale à chaque liste : le segment 1 de la liste A n’a aucun rapport avec le segment 1 de la liste B. La valeur 0 désigne l’inscription à la liste entière, indépendamment des segments définis ou non.

Précision sur les mots-clés dans les filtres

Un filtre de mots-clés porte sur un groupe de mots-clés, pas sur un mot-clé individuel. L’attribut filtrable est nommé groupemots_<id_groupe>.

• Seuls les groupes qui sont déclarés comme associés à mailsubscribers peuvent être utilisés comme attribut filtrable.
• La valeur est un ou plusieurs id_mot de ce groupe, séparés par des virgules lorsqu’il y en plusieurs.
• Lorsqu’il y a plusieurs valeurs, le filtre vérifie l’intersection entre les mots-clés associés à l’abonné dans ce groupe et ceux listés dans le filtre : pour être dans le segment, l’abonné doit donc porter au moins l’un des mots-clés demandés.

Enregistrement des appartenances aux segments

L’appartenance d’un abonné à un segment est inscrite dans la table spip_mailsubscriptions, dont la clé primaire est (id_mailsubscriber, id_mailsubscribinglist, id_segment) :

• une ligne avec id_segment = 0 = inscription à la liste entière ;
• une ligne ou plusieurs lignes avec id_segment = n(m...) = appartenance au(x) segment(s) n (et m...) dans la liste.

Le test d’appartenance est effectué par la fonction mailsubscribers_teste_segment() dans inc/mailsubscribinglists.php. Les clés filtre_<attribut> sont comparées par égalité (==, in_array ou array_intersect) aux valeurs des attributs de l’abonné. Ce ne sont pas des appels de fonction PHP, mais une comparaison de données.

Possibilités pour les attributs testés

Les attributs disponibles sont fournis par mailsubscriber_recuperer_informations_liees(). Les valeurs testées sont lues dans la table spip_mailsubscribers (pour la langue et les champs extras) et dans les tables de mots-clés (pour les groupes de mots). Cf inc/mailsubscribers.php.

Les filtres possibles sont :
-  la langue de l’abonné (lang) ;
-  les champs extras (plugin cextras) de la table spip_mailsubscribers (un attribut par champ) ;
-  un attribut par groupe de mots-clés lié aux abonnés (voir §1.2) ;
-  tout attribut ajouté via le pipeline mailsubscriber_informations_liees ([inc/mailsubscribers.php](https://git.spip.net/spip-contrib-extensions/mailsubscribers/src/branch/master/inc/mailsubscribers.php)).

Déclenchement du recalcul

L’appartenance aux segments n’est pas recalculée en temps réel. Le recalcul est déclenché uniquement dans ces situations :

• Inscription ou désinscription d’un abonné à une liste : le code de subscribe.php et unsubscribe.php appelle mailsubscribers_actualise_segments().
• Création ou modification d’un segment : les inscriptions de la liste sont marquées actualise_segments = 1 dans spip_mailsubscriptions, puis traitées par le cron genie_mailsubscribers_update_segments.
• Bouton « Actualiser les segments » sur la fiche d’un abonné dans l’espace privé : recalcul immédiat pour cet abonné via action/actualiser_segments_mailsubscriber.php.

Attention : modifier la langue, un champ extra ou un mot-clé d’un abonné directement dans l’espace privé ne déclenche pas le recalcul des segments. Le pipeline post_edition de mailsubscribers ne traite que les changements de statut. Pour que le changement soit pris en compte dans les segments, il faut déclencher l’un des trois événements ci-dessus.

Rôle de auto_update

L’option auto_update ne signifie pas « surveiller les changements et recalculer automatiquement ». Elle signifie : « quand une actualisation des segments de l’abonné est déclenchée (par une inscription, une désinscription ou par le cron), inclure ce segment dans le recalcul ».

Sans auto_update, un segment n’est recalculé que lors de sa propre (re)définition ou via le bouton manuel « Actualiser les segments » sur la fiche de l’abonné (qui appelle la fonction avec force = true, paramètre de mailsubscribers_actualise_segments).

Avancement du recalcul

Dans l’onglet segments d’une liste, un indicateur de progression (pourcentage) apparaît à côté de chaque segment en cours de recalcul. Il est fourni par mailsubscribers_is_updating_segment() dans mailsubscribers_fonctions.php, qui calcule (total inscriptions - restant à traiter) / total en comptant les lignes actualise_segments = 1 restantes pour cette liste. Quand le pourcentage atteint 100 % ou que l’indicateur disparaît, le segment est prêt.

Cibler les segments destinataires

Dans le menu déroulant, la valeur de chaque option est identifiant+N, avec l’identifiant de la liste et le numéro du segment pour cette liste. On peut combiner plusieurs cibles en union (OU), y compris 2 segments d’une même liste :

nouvelles+1               -> le segment 1 de la liste « nouvelles »
nouvelles+1, breves+2     -> (segment 1 de nouvelles) OU (segment 2 de breves)
nouvelles+1, nouvelles+3  -> (segment 1) OU (segment 3) de la même liste

Les doublons (un abonné présent dans les deux segments) sont éliminés par la requête (regroupement par id_mailsubscriber).

Ce qu’on ne peut pas faire avec les segments

Les segments filtrent les inscrits d’une liste selon leurs attributs et se combinent à l’envoi, mais :

• Pas de soustraction A − B : impossible d’exprimer « la liste A sauf les destinataires de B » ou « sauf ceux qui ont déjà reçu telle campagne ». La combinaison est toujours une union.
• On peut tester l’égalité, l’appartenance à un ensemble ou l’intersection d’un ensemble de valeurs, mais pas « n’appartient pas à », et pas de comparaison > ou < par exemple.
• On ne peut pas exprimer un OU entre deux groupes de mots-clés différents au sein d’un même segment, et évidemment, on ne peut pas construire un segment à cheval sur différentes listes.