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 :
| Module | Contenu |
|---|---|
auth | connexion, inscription, récupération, activation, social (08) |
restricted | le backend : ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1 |
cms-common | le module de projet : la règle /srv/(.*) → /applets/services/$1 et models/Sitemap.php |
security | contenus du module de sécurité |
package-manager | gestion 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.phpest 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-commonest le bon endroit pour ce qui est commun, un module dédié pour ce qui appartient au produit. Pour quelques lignes (un écouteur deAuth::addEvent(), un helper), il y ahook.local.php, à côté dehook.php:hook.phpl'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 :
- Validation de sécurité : vérification de l'archive ZIP avec blocage des chemins dangereux (path traversal
../ou absolus). - Lecture du descripteur
manifest.json: métadonnées du module, version minimale de JoeCMS requise, dépendances. - Extraction sélective : décompresse les composants dans leurs dossiers respectifs (
modules/<id>/,contents/,themes/). - 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. - 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éfixe | Fichier 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 :
| Module | Ce qu'il fait |
|---|---|
form | constructeur 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) |
search | recherche dans les contenus, avec configuration, groupes, extras et aperçu |
newsletter | abonnements et envois |
calendar | événements de calendrier |
maps | cartes |
share | partage social |
tagcloud | nuage de tags |
videobar, fbalbum, swf | médias et galeries (composants datés) |
register | inscription |
shippingprice | frais 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 appelleverify(), 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(publiablepk_…),api_key(secrètesk_…),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 constantesSTRIPE_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épondlive,testouignoto). Si l'on oublie de changer de clé, on reste en test. - Les dates passent par le fuseau du site :
Payment::fuso()utiliseTIMEZONE(é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égorie | Services |
|---|---|
| Analytics | analytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google |
| Marketing | linkedin.pixel, mailchimp, share.addthis, notification.optinmonster |
| Cartes et données | google.maps, google.docs.auth, directory, place |
| Polices et icônes | font.google, font.google2, font.typekit, fontawesome |
| Meta et PWA | meta.favicon, meta.themecolor, meta.viewport |
| Notifications | notification.onesignal, sms.joesmtp, sms.twilio (06) |
| Paiements | payment.stripe (§2, identifiants uniquement : n'injecte rien) |
| Performances | lazyload, modernizr, debounce |
| Contenus/outils | admin.tools, company.data, courtesy.page, img.aviary, facebook |
| Confidentialité | cookie.consent |
Ajouter un service
conf/gallery/services/<nom>/config/index.phpavec les champs ;conf/gallery/services/<nom>/index.phpavec l'injection ;- le template du tag dans
themes/<thème>/services/<nom>.html; - 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èque | Usage |
|---|---|
phpmailer | envoi SMTP : PHPMailer 7.1.1, avec les adaptateurs de la 5.2 (06 §2) |
sentry | suivi des erreurs (13) |
html2pdf, PHPexcel | génération de PDF et d'Excel |
mobiledetect, browser | détection de l'appareil |
minify, gminify, cssmin, jsmin | pipeline des ressources |
imap, vcard | courrier entrant, contacts |
BunnyCDN | CDN |
algoliasearch-client | recherche externe |
SEOstats | métriques SEO (datée) |
rabbitMQ | broker de files, non câblé (05 §4) |
facebook-php-sdk, mailchimp, PayPal, OAuth2 | inté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.mdraconte aussi les dégâts qu'un vieuxsedde masse avait laissés dansPHPExcel,TCPDFetSEOstats.