[SPE-105] feat(analytics): add Segment PHP client bootstrap

[dylanDenizonPresta]

Summary

• Add segmentio/analytics-php and bootstrap Segment::init() from Analytics::bootstrap() when the module is enabled.
• Hook actionAdminControllerSetMedia on module configuration BO context only.
• Document Segment setup in docs/SEGMENT.md and link from README.

Notes

• Write key is currently defined in Analytics::SEGMENT_CLIENT_KEY_PHP (empty by default until set).
• Event tracking (track / flush) is planned for follow-up work.

Test plan

• composer install at module root
• ./scripts/run-tests.sh unit

[ThbPS]

On pourrait ajouter une méthode générique pour initialiser & tracker les événements
Tu n'aurais plu besoin de la logique dans hookActionAdminControllerSetMedia
L’initialisation de Segment ne devrait pas dépendre d'un hook.

Exemple:

private const EVENT_GUEST_INIT_SUCCEEDED = 'opc_guest_init_succeeded';

 public static function bootstrap(): void
 {
        if (self::$clientInitialized === true) {
            return;
        }

        $writeKey = trim((string) self::SEGMENT_CLIENT_KEY_PHP);
        if ($writeKey === '') {
            return;
        }

        Segment::init($writeKey);
        self::$clientInitialized = true;
}

/**
 * @param array<string, mixed> $properties
 * @param array<string, mixed> $context
 */
private static function track(
    string $event,
    array $properties = [],
    array $context = []
): void {
    try {
        self::bootstrap();

        if (self::$clientInitialized === false) {
            return;
        }

        Segment::track([
            'event' => $event,
            'properties' => $properties,
            'context' => $context,
        ]);
    } catch (Throwable $exception) {
        PrestaShopLogger::addLog(
            sprintf('ps_onepagecheckout analytics track failed for "%s": %s', $event, $exception->getMessage()),
            2
        );
    }
}

public static function trackGuestInitSucceeded(array $properties = []): void
{
    self::track(EVENT_GUEST_INIT_SUCCEEDED, $properties);
}

[ThbPS]

@dylanDenizonPresta ce commentaire est bloquant et doit être résolu afin d'avoir un tracking robuste, réutilisable et centralisé

[ThbPS]

Comment nous allons gérer les clés de préprod et prod ?
Les tests en locale ou en préprod ne doivent pas envoyer des événements en prod

[dylanDenizonPresta]

Merci ! Pour éviter d'envoyer des events vers la prod en local/préprod, je propose de ne pas embarquer de write key en dur: on la lit depuis une variable d'environnement (ou un secret CI/serveur), avec une clé différente par environnement. Dans le module, on bootstrape Segment uniquement si la clé est non vide. Je peux pousser un fix qui remplace la constante par une lecture env (ex: PS_OPC_SEGMENT_WRITE_KEY) + doc.

[dylanDenizonPresta]

J’ai poussé un fix: la write key n’est plus en dur, elle est lue depuis la variable d’environnement (doc + tests mis à jour). Du coup chaque environnement (local/préprod/prod) peut avoir sa clé propre, et sans clé on n’initialise pas Segment.

[dylanDenizonPresta]

Correctif: la write key est lue depuis la variable d’environnement PS_OPC_SEGMENT_WRITE_KEY (plus de clé en dur). Doc + tests mis à jour. Sans clé, Segment n’est pas initialisé.