Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 10

Modules et services tiers

Deux mécanismes d'extension, aux noms proches et aux buts différents : les modules ajoutent du code, des routes et des pages ; les services injectent des tags tiers (analytics, cartes, polices, pixels) configurables depuis le backend sans toucher au code.

1. Modules : le code de projet hors de hook.php

Chaque dossier dans /modules est chargé automatiquement. La structure type :

modules/<nom>/
├── common.php               fonctions du module (chargées par le CMS)
├── autoload.php             autoloader propre (optionnel)
├── events.php               accroche aux événements du cycle de page (optionnel)
├── conf/
│   ├── routing_table.xml    routes du module   → chargées automatiquement
│   └── mod_restricted.xml   entrées du backend
├── models/                  classes du module
├── contents/                pages du module
├── library/
│   ├── job/<nom>.php        fonctions job_<nom>()      (check_function("job_..."))
│   └── system/<nom>.php     fonctions system_<nom>()   (check_function("system_..."))
└── themes/                  CSS/JS/templates du module

Les modules présents dans le dépôt :

ModuleContenu
authconnexion, inscription, récupération, activation, social (08)
restrictedle backend : ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1
cms-commonle module de projet : la règle /srv/(.*) → /applets/services/$1 et models/Sitemap.php
securitycontenus du module de sécurité
package-managergestion des modules et extensions (.zip) : envoi façon WordPress, auto-migration BD et assistant

Où mettre le code d'un nouveau projet : dans un module, pas dans hook.php. hook.php est du code de la plateforme (~1 900 lignes de helpers legacy) et la mise à jour le remplace : une ligne du projet écrite là disparaît à la version suivante. Un module a son propre autoload, se charge tout seul, et se déplace vers un autre projet en copiant un dossier. modules/cms-common est le bon endroit pour ce qui est commun, un module dédié pour ce qui appartient au produit. Pour quelques lignes (un écouteur de Auth::addEvent(), un helper), il y a hook.local.php, à côté de hook.php : hook.php l'inclut à la fin, il n'est pas dans le paquet et la mise à jour n'y touche pas. Une valeur à changer (domaine, AREA_*, MAX_UPLOAD) va plutôt dans le config.

⚠️ Le conf/schema.php d'un module n'est pas lu. Seuls library/gallery/settings.php (core) et themes/<thème>/settings.php (projet) sont chargés. modules/cms-common/conf/schema.php existe et c'est du code mort : les déclarations de $schema["request"] et $schema["page"] vont dans le thème (voir 01 §5).

Package Manager : installation de modules ZIP et auto-migration BD

Le module package-manager (/admin/pacchetti) fournit à l'administration de JoeCMS un espace pour téléverser des archives ZIP contenant des modules et extensions, gérant l'ensemble de leur cycle de vie :

  1. Validation de sécurité : vérification de l'archive ZIP avec blocage des chemins dangereux (path traversal ../ ou absolus).
  2. Lecture du descripteur manifest.json : métadonnées du module, version minimale de JoeCMS requise, dépendances.
  3. Extraction sélective : décompresse les composants dans leurs dossiers respectifs (modules/<id>/, contents/, themes/).
  4. Mise à jour automatique de la base de données : si le manifest spécifie database.schema, exécute automatiquement la DDL SQL via la connexion active.
  5. Assistant de configuration post-installation : redirige facultativement vers l'assistant de configuration des chemins et des paramètres du module.

Autoload par convention

check_function() dans library/gallery/common.php charge le bon fichier d'après le nom de la fonction :

PréfixeFichier recherché
job_<x>modules/<mod>/library/job/<x>.php, puis library/gallery/job/<x>.php
system_<x>modules/<mod>/library/system/<x>.php, puis library/gallery/system/<x>.php
mod_<mod>_<x>modules/<mod>/events.php

C'est pourquoi on trouve partout dans le code if (check_function("system_quelquechose")) { … } : le fichier n'est inclus que s'il sert.

2. Les modules fonctionnels du CMS

conf/gallery/modules/ contient des sous-systèmes complets, chacun avec configuration et gestion dans le backend :

ModuleCe qu'il fait
formconstructeur de formulaires : définition des champs depuis le backend, sélections, tarifs, envoi d'emails avec template, révisions, archive des réponses (manage/, detail.php)
searchrecherche dans les contenus, avec configuration, groupes, extras et aperçu
newsletterabonnements et envois
calendarévénements de calendrier
mapscartes
sharepartage social
tagcloudnuage de tags
videobar, fbalbum, swfmédias et galeries (composants datés)
registerinscription
shippingpricefrais de port (e-commerce)

Le module form est celui qui fait le plus souvent gagner du travail : un formulaire de contact, une demande de devis, un questionnaire se configurent depuis le backend — champs, validations, email de notification, liste des réponses — sans écrire une page.

E-commerce

Il existe un échafaudage : routes /user/cart, /user/wishlist, /user/manage, /user/mpay, library/gallery/ecommerce/product_process.php, conf/gallery/manage/ avec opérations et paiements, le job reset_carts, library/PayPal/, et les tables correspondantes dans le seed.

⚠️ C'est du code upstream non testé dans ce prototype. Le traiter comme un point de départ à vérifier, pas comme une fonctionnalité prête.

Paiements : le hub Payment

Indépendant de l'échafaudage ci-dessus : c'est l'endroit où un projet encaisse sans écrire sa propre intégration. library/payment/Payment.php déclare ce que signifie encaisser, les passerelles sont des drivers dans library/payment/services/<nom>.php (classe payment<Nom>), et le hub les charge tout seul : dans les autoloaders il n'y a qu'un cas, Payment, aussi bien dans l'autoload.php racine (inclus par l'API) que dans vendor/wolfgan/autoload.php, celui que index.php charge via Composer. Jusqu'à la 1.6.2 le second ne l'avait pas, et depuis le site le checkout, les webhooks et les cron des paiements mouraient avec « Class Payment not found ».

$esito = Payment::gateway()->checkout(array(
    "riferimento"  => "acquisto:1234",   // votre propre ID, pas celui de la passerelle
    "descrizione"  => "Forfait 10 cours",
    "importo_cent" => 18000,             // toujours des entiers en centimes, jamais de float
    "email"        => "anna@exemple.fr",
    "ritorno_ok"   => "https://site/espace/achat?esito=ok",
    "ritorno_ko"   => "https://site/espace/achat?esito=annullato",
));
// array(ok, id, url, error) : on envoie la personne vers url

Chaque driver expose checkout() (paiement unique), subscribe() (récurrent), verify() et subscriptionVerify() (état réel), subscriptionCancel(), refund(), webhookVerify(). verify() répond toujours sous la même forme, avec un état normalisé : pagato, in_attesa, fallito, rimborsato, annullato (constantes Payment::PAGATO et suivantes). La passerelle se choisit avec Payment::gateway('<nom>'), ou avec la constante PAYMENT_GATEWAY ; la valeur de départ est stripe.

  • Le webhook déclenche, la vérité se relit. Rien du corps d'un webhook n'est appliqué : on vérifie la signature (webhookVerify()), on enregistre l'ID de l'événement pour ne pas le traiter deux fois, on répond 200. Celui qui traite appelle verify(), qui relit l'état auprès de la passerelle. Les événements arrivent dans le désordre, et si le webhook n'arrive pas, un passage de rapprochement qui relit les encaissements en attente suffit à retomber sur ses comptes. La réception suit le modèle de 03 §2.
  • Les clés sont dans l'espace Services, service payment.stripe (conf/gallery/services/payment.stripe/) : code (publiable pk_…), api_key (secrète sk_…), webhook_secret (whsec_…), currency (vide = eur). Le service n'injecte rien dans la page. Hors du CMS (cron en ligne de commande) ou avec le service désactivé, le driver se rabat sur les constantes STRIPE_PUBLIC, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET, STRIPE_CURRENCY.
  • C'est la clé qui dit l'environnement : seules sk_live_ / rk_live_ encaissent de l'argent réel (ambiente() répond live, test ou ignoto). Si l'on oublie de changer de clé, on reste en test.
  • Les dates passent par le fuseau du site : Payment::fuso() utilise TIMEZONE (écrite dans le config par l'installeur), sinon le fuseau de PHP, et sur une valeur invalide se rabat sur UTC au lieu de bloquer l'encaissement. Un nouveau driver convertit les dates à partir de là, pas d'une constante à lui.
  • Produits, crédits, reçus et le registre des encaissements ne sont pas dans le hub : ils appartiennent au module du site.

⚠️ Le driver Stripe vient de GDay, où il est en production ; dans le dépôt de base, aucun projet ne l'utilise.

3. Services tiers

Un « service » est un tag tiers configurable depuis le backend. Structure :

conf/gallery/services/<nom>/
├── config/index.php     définit les champs configurables  (enable, code, …)
└── index.php            injecte le tag à l'exécution

config/index.php déclare les types des champs et délègue à system_services_modify(), qui construit l'écran de configuration :

$type_field["enable"] = "Boolean";
$type_field["code"]   = "String";
system_services_modify(basename(ffCommon_dirname(ffCommon_dirname(__FILE__))), $type_field);

index.php lit les valeurs ($actual_srv) et injecte :

if ($actual_srv["enable"] && strlen($actual_srv["code"])) {
    $tpl = ffTemplate::factory(get_template_cascading("/", "google.analytics.html", "/services"));
    $tpl->load_file("google.analytics.html", "main");
    $tpl->set_var("code", $actual_srv["code"]);
    $globals->fixed_post["body"][] = $tpl->rpparse("main", false);
}

Les valeurs vivent dans cm_mod_security_domains_fields — (field, group, value) avec group = nom du service — et y écrivent aussi bien l'espace Services du backend que l'assistant d'installation. Elles sont chargées par get_webservices() / process_webservices() (library/gallery/common/get_webservices.php).

Les services disponibles

CatégorieServices
Analyticsanalytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google
Marketinglinkedin.pixel, mailchimp, share.addthis, notification.optinmonster
Cartes et donnéesgoogle.maps, google.docs.auth, directory, place
Polices et icônesfont.google, font.google2, font.typekit, fontawesome
Meta et PWAmeta.favicon, meta.themecolor, meta.viewport
Notificationsnotification.onesignal, sms.joesmtp, sms.twilio (06)
Paiementspayment.stripe (§2, identifiants uniquement : n'injecte rien)
Performanceslazyload, modernizr, debounce
Contenus/outilsadmin.tools, company.data, courtesy.page, img.aviary, facebook
Confidentialitécookie.consent

Ajouter un service

  1. conf/gallery/services/<nom>/config/index.php avec les champs ;
  2. conf/gallery/services/<nom>/index.php avec l'injection ;
  3. le template du tag dans themes/<thème>/services/<nom>.html ;
  4. si c'est un traceur : déclarer la catégorie de consentement (§4).

4. Consentement aux cookies : un vrai blocage, côté serveur

Le bandeau est le service cookie.consent (cookie jc_consent). Mais la partie qui compte est côté serveur : avant d'injecter un service, process_webservices() appelle jc_consent_blocks($service_name) (dans hook.php) et bloque la catégorie non consentie.

jc_consent_category($service_name)   // à quelle catégorie appartient le service
jc_consent_active()                  // le bandeau est-il actif ?
jc_consent_granted($categoria)       // l'utilisateur a-t-il consenti ?
jc_consent_blocks($service_name)     // → true : le tag N'est PAS injecté

Deux propriétés voulues :

  • C'est un vrai blocage : le tag n'arrive pas du tout sur la page, il n'est pas masqué côté client.
  • C'est opt-in : si le bandeau n'est pas actif, rien n'est bloqué. Les sites existants ne changent pas de comportement quand on met à jour le CMS.

Le bandeau est themes/gallery/contents/services/cookie.consent.html, rendu par conf/gallery/services/cookie.consent/index.php. Ses textes sont des codes du dictionnaire (svc_cookie_*, dans les quatre langues) ; le lien vers la politique de confidentialité, si aucun n'a été mis dans les options du service, est /privacy dans la langue de la page (content_i18n_url()). Jusqu'à la 3.0.3 ils étaient figés en italien, et le CSS en ligne perdait trois règles : {margin-left:auto}, {flex:1} et {text-decoration:underline} sont des accolades avec une seule paire parola:parola, que le moteur de templates prend pour des variables et efface. Les règles suivantes se fondaient avec le sélecteur resté sans bloc, et le panneau « Personalizza » (Personnaliser) restait toujours ouvert. Dans le CSS d'un template, chaque règle termine sa dernière déclaration par ;.

5. Autres bibliothèques disponibles

library/ contient des dépendances prêtes à l'emploi, de qualité et de fraîcheur très diverses. Les utiles :

BibliothèqueUsage
phpmailerenvoi SMTP : PHPMailer 7.1.1, avec les adaptateurs de la 5.2 (06 §2)
sentrysuivi des erreurs (13)
html2pdf, PHPexcelgénération de PDF et d'Excel
mobiledetect, browserdétection de l'appareil
minify, gminify, cssmin, jsminpipeline des ressources
imap, vcardcourrier entrant, contacts
BunnyCDNCDN
algoliasearch-clientrecherche externe
SEOstatsmétriques SEO (datée)
rabbitMQbroker de files, non câblé (05 §4)
facebook-php-sdk, mailchimp, PayPal, OAuth2intégrations

Et dans vendor/ : phpformsframework, wolfgan (Cms, auth, mailer, storage, cache, filemanager), hcore (anagraph, api, notifier, stats, jobs, logs, util), smarty, ckeditor, google-api-php-client, twilio, mongodb, symfony.

⚠️ Beaucoup de ces bibliothèques sont bloquées à de vieilles versions et ont été touchées par la migration vers PHP 8. Avant d'en utiliser une sur un chemin critique, la vérifier : MIGRAZIONE_PHP7_PHP8.md raconte aussi les dégâts qu'un vieux sed de masse avait laissés dans PHPExcel, TCPDF et SEOstats.