Extender for Back In Stock Notifier

Extension maison de Back In Stock Notifier for WooCommerce | WooCommerce Waitlist Pro (ProPluginsLab). Elle ne remplace pas le plugin hôte : elle s'y accroche, et ne fonctionne pas sans lui.

• Version : 0.6.2
• Prérequis : WordPress 6.8+, PHP 7.4+, WooCommerce 9.9+ (testé jusqu'à 11.0), Back In Stock Notifier 7.0+ (relu sur 7.4.2)
• Préfixe : ebisn_ (options, hooks) / EBISN\ (namespace PHP)
• Text domain : extender-for-back-in-stock-notifier (doit rester identique au slug du dossier)
• Licence : GPL-3.0-or-later — alignée sur celle du plugin hôte, pour qu'adapter un de ses gabarits reste possible sans problème de compatibilité

Arborescence

extender-for-back-in-stock-notifier/
├── extender-for-back-in-stock-notifier.php  Fichier principal : en-tête, constantes, hooks d'amorçage
├── readme.txt                               Métadonnées au format WordPress.org (lues pour la fiche de mise à jour)
├── uninstall.php                            Purge des données ebisn_* à la suppression (sur opt-in)
├── .gitattributes                           export-ignore : fichiers exclus des archives
├── .github/workflows/release.yml            Construit et publie l'archive sur push d'un tag v*
├── bin/build-plugin-zip.sh                  Construction reproductible de l'archive d'installation
├── lib/plugin-update-checker/               Bibliothèque tierce embarquée (Plugin Update Checker 5.7)
├── composer.json                            Autoload PSR-4 + outillage de dev (PHPCS, PHPStan)
├── phpcs.xml.dist                           Règles WordPress Coding Standards
├── phpstan.neon.dist                        Analyse statique avec stubs WordPress/WooCommerce
├── assets/
│   ├── css/admin.css
│   └── js/admin.js
├── languages/                               Fichiers .pot / .po / .mo
└── src/
    ├── Autoloader.php                       Autoload PSR-4 sans Composer
    ├── functions.php                        Helpers globaux : ebisn(), ebisn_log()
    ├── Plugin.php                           Conteneur : amorçage + registre des modules
    ├── Updater.php                          Mises à jour depuis les releases GitHub
    ├── Requirements.php                     Vérification WooCommerce + plugin hôte
    ├── Installer.php                        Activation / désactivation / migrations
    ├── Integration/
    │   ├── BackInStockNotifier.php          Tout ce qu'on sait du plugin hôte
    │   └── Brevo.php                        Tout ce qu'on sait des extensions Brevo
    ├── Admin/
    │   ├── Admin.php                        Hooks admin, assets, lien « Réglages »
    │   ├── SettingsPage.php                 Écran de réglages, sous le menu de l'hôte
    │   ├── SettingsFields.php               Sections et champs de réglages
    │   ├── StatsBanner.php                  Bandeau d'indicateurs sur la liste des inscrits
    │   ├── SizeMatrixPage.php               Écran « Demandes par taille »
    │   ├── SizeMatrixTable.php              WP_List_Table à colonnes dynamiques
    │   └── BrevoBackfillPage.php            Lancement et suivi du rattrapage Brevo
    ├── Conversion/                          Détection d'achat et statut « Purchased »
    │   ├── ConversionService.php            SEUL point d'écriture d'un statut d'inscription
    │   ├── OrderMatcher.php                 Règles d'appariement, sans accès base
    │   ├── SubscriptionRepository.php       Lectures d'inscriptions en SQL préparé
    │   ├── OrderLookup.php                  Recherche de commandes (HPOS et stockage historique)
    │   ├── RealtimeListener.php             Conversion au fil de l'eau et retours en arrière
    │   ├── Backfill.php                     Rattrapage automatique sur l'historique
    │   ├── NotificationSuppressor.php       Bloque l'alerte pour qui a déjà acheté
    │   ├── Stats.php                        Calcul des indicateurs, mis en cache
    │   └── MetaKeys.php                     Clés de métadonnées, actuelles et héritées
    ├── Brevo/                               Synchronisation vers Brevo
    │   ├── Client.php                       Transport HTTP
    │   ├── Response.php                     Verdicts : succès, réessayable, définitif, authentification
    │   ├── Contacts.php                     Contacts, imports, listes, attributs
    │   ├── Lists.php                        Listes du compte, mises en cache
    │   ├── ContactState.php                 Table de suivi, idempotence par empreinte
    │   ├── PayloadBuilder.php               Attributs agrégés sur toutes les attentes d'une adresse
    │   ├── AttributeInstaller.php           Déclaration des attributs chez Brevo
    │   ├── SyncService.php                  Synchro au fil de l'eau, avec report exponentiel
    │   ├── Backfill.php                     Rattrapage en masse, suivi des imports
    │   └── Consent.php                      Case de consentement et preuve horodatée
    ├── Matrix/                              Croisement des demandes par déclinaison
    │   ├── DemandMatrix.php                 Collecte agrégée, mise en cache
    │   ├── AttributeResolver.php            Choix de l'attribut d'axe et ordre des colonnes
    │   └── MatrixExporter.php               Export CSV, formules neutralisées
    ├── Unsubscribe/                         Désabonnement d'une alerte
    │   ├── UnsubscribeService.php           Délègue l'écriture à l'API de l'hôte
    │   ├── StatusRecorder.php               Mémorise le statut quitté, quel qu'en soit l'auteur
    │   ├── SubscriberLocator.php            Reconnaît le visiteur et ses inscriptions
    │   ├── VisitorCookie.php                Jeton opaque de navigateur
    │   ├── ProductForm.php                  Encart sur la fiche produit, point d'entrée AJAX
    │   └── EmailLink.php                    Lien signé des e-mails
    ├── Renotify/                            Renotification à chaque nouvelle rupture
    │   ├── RenotifyService.php              Remise en attente via l'API de l'hôte, comptage des cycles
    │   ├── SubscriptionQuery.php            Inscriptions notifiées, par produit ou par curseur
    │   ├── StockWatcher.php                 Écoute les ruptures, diffère le traitement
    │   └── Backfill.php                     Rattrapage des inscriptions déjà bloquées
    ├── Migration/
    │   └── LegacyConversionMeta.php         Reprise des métadonnées des snippets WPCode
    ├── Modules/
    │   ├── ModuleInterface.php              Contrat d'un module
    │   ├── AbstractModule.php               Base : activation pilotée par option
    │   ├── PurchaseConversion.php           Module « Purchased »
    │   ├── ConversionStats.php              Module « indicateurs »
    │   ├── Renotify.php                     Module « Renotification » (désactivé par défaut)
    │   ├── SizeMatrix.php                   Module « Demandes par taille »
    │   ├── Unsubscribe.php                  Module « Désabonnement »
    │   ├── HideAddToCart.php                Module « Masquer l'ajout au panier »
    │   └── BrevoSync.php                    Module « Brevo » (désactivé par défaut)
    └── Support/
        ├── Settings.php                     Lecture/écriture des options ebisn_*
        ├── Logger.php                       Journaux WooCommerce (source extender-bisn)
        ├── Scheduler.php                    Unique point de contact avec Action Scheduler
        ├── Lock.php                         Verrou atomique entre processus
        ├── JobState.php                     État persistant d'un traitement par lots
        ├── BatchJob.php                     Contrat d'un traitement par lots
        ├── BatchRunner.php                  Moteur par lots : budget, curseur, chaînage
        └── SnippetGuard.php                 Met un module en veille si son snippet tourne encore

Modules

Dépendance optionnelle à Brevo

Brevo n'est pas déclarée dans l'en-tête Requires Plugins : cela rendrait l'extension entière inactivable sans elle alors qu'un seul module la concerne. La détection se fait à l'exécution, avec trois sources de clé d'API dans cet ordre : l'option de l'extension Brevo, son nom en dur, puis une clé saisie dans les réglages.

Attention : seule l'extension Brevo (slug mailin) détient une clé d'API v3. Le connecteur « Brevo for WooCommerce » n'en stocke plus depuis sa version 4 — un site n'ayant que celui-ci doit saisir sa clé manuellement.

Reprise depuis les snippets WPCode

Le plugin remplace six snippets. La bascule est conçue pour être transparente :

• Mise en veille automatique. Tant qu'un snippet remplacé est encore chargé, le module correspondant ne s'accroche à rien et le signale dans le panneau Diagnostic. Sans cela, les deux traiteraient les mêmes données en parallèle.
• Migration des métadonnées. Les clés mh_bisn_order_id et mh_bisn_converted_on sont reprises sous le préfixe _ebisn_, par lots, puis supprimées. Ces conversions héritées sont marquées comme telles : les snippets n'enregistraient pas le statut d'origine, elles ne peuvent donc pas être annulées.
• Marqueur de commande. _mh_bisn_converted n'est plus lu ni écrit — l'idempotence vient désormais d'une mise à jour conditionnelle du statut. Il est laissé en place, inerte : le purger sur l'ensemble des commandes coûterait davantage que le bénéfice, et sous HPOS il vit dans wc_orders_meta.
• Rattrapage Brevo. Si l'option mh_brevo_backfill_job du snippet est trouvée en base avec au moins un lot traité, le rattrapage est marqué comme déjà effectué et rien n'est renvoyé.
• Demandes par taille. Les constantes MH_BISN_MX_STATUS, MH_BISN_MX_SIZE_ATTR et MH_BISN_MX_CACHE_TTL sont reprises comme valeurs initiales des réglages si elles sont définies au moment de la migration. L'ancienne adresse page=mh-bisn-matrice redirige vers la nouvelle page, et le cache du snippet est purgé.

Traitements de fond

Tous passent par Action Scheduler, sous le groupe ebisn, visibles dans WooCommerce → État → Actions programmées.

Les arguments passés sont toujours scalaires : wp-cron.php transmet les arguments d'un événement sans les réindexer, et une clé de chaîne devient un argument nommé en PHP 8 — donc une erreur fatale qui interrompt l'intégralité du run cron.

## La règle qui structure tout : `Integration\BackInStockNotifier`

Ce plugin s'accroche à du code qu'il ne maîtrise pas. **Aucune classe, hors
`src/Integration/BackInStockNotifier.php`, ne doit écrire en dur `cwginstock`,
`CWGINSTOCK_*` ou `CWG_Instock_Notifier`.** Slugs, constantes, types de contenu, noms
d'options : tout passe par cette classe. Le jour où l'hôte renomme quelque chose, un seul
fichier bouge — et le diagnostic prévient quand il change de version majeure.

## Ajouter un module

1. Créer `src/Modules/MonModule.php` :

```php
<?php

namespace EBISN\Modules;

defined( 'ABSPATH' ) || exit;

final class MonModule extends AbstractModule {

    protected $id    = 'mon_module';
    protected $title = 'Mon module';

    public function register(): void {
        add_action( 'cwginstock_after_insert_subscriber', array( $this, 'on_subscribe' ), 10, 2 );
    }

    public function on_subscribe( $subscriber_id, $data ): void {
        // …
    }
}

2. Le référencer dans Plugin::get_module_classes().
3. Il apparaît alors dans WooCommerce → Réglages → Extender BIS → Modules, avec sa propre case d'activation (ebisn_module_mon_module_enabled).

Surface d'extension du plugin hôte

Relevé sur l'archive 7.4.2 (cwginstocknotifier.php, dossier back-in-stock-notifier-for-woocommerce/). À revérifier à chaque changement de version majeure de l'hôte — c'est précisément ce que signale le panneau Diagnostic.