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

Cycle d'une requête et routage

Ce qui se passe entre l'URL et le fichier PHP qui répond. C'est le chapitre à lire en premier : presque toutes les surprises de la stack naissent ici.

1. La chaîne de démarrage

requête HTTP
  └─ .htaccess            chemin inexistant sur le filesystem → réécrit vers /index.php
       ▼
  index.php
    ├─ config.php ────────► GARDE DE PREMIÈRE INSTALLATION (hôte non ".local" et
    │                        themes/site/conf/config.remote.php absent → inclut install/index.php, sort)
    ├─ themes/site/conf/config.{local|remote}.php   constantes d'environnement
    ├─ conf/gallery/config.php                      config framework + vgallery
    ├─ vendor/autoload.php                          composer
    ├─ hook.php                                     helpers de la plateforme (~1 900 lignes) ;
    │    └─ hook.local.php                          à la fin, s'il existe : le code du site
    └─ Cms::getInstance("kernel")->run()            router → controller → ffPage → sortie

Tous les points d'entrée ne passent pas par index.php. Ils ont leur propre bootstrap :

Point d'entréeSert à
router.phpdispatch alternatif
cm/showfiles.phpservice et redimensionnement des images (voir 11 — Médias et fichiers)
cm/static.phpressources statiques (/themes, /uploads, /asset)
api/1.0/index.phpAPI publique, dossier physique (voir 04 — API publique)
install/index.phpassistant de première installation

Règle pratique : tout ce qui doit valoir « toujours » (gestion des erreurs, constantes, correlation id) doit s'accrocher à un démarrage commun, pas à index.php.

2. Le routage a trois niveaux, plus le kernel

Les règles sont collectées depuis plusieurs sources et triées par priorité (TOP, VERY_HIGH, HIGH, NORMAL, LOW, VERY_LOW, BOTTOM) :

NiveauFichierContenu
kernelvendor/wolfgan/cms/services/kernel.php (tableau interne)ressources statiques et les chemins réservés qui répondent 404
coreconf/routing_table.xmlsitemap, feed, error, install, updater, /md, /frame, /api, /srv, /notify, /search, /user/*
CMcm/conf/routing_table.xmlen fin de liste, la règle qui fait exister les pages : (.*) → /contents$0, priorité BOTTOM
modulesmodules/<nom>/conf/routing_table.xmlchargés automatiquement pour chaque dossier de /modules

Anatomie d'une règle (conf/routing_table.xml) :

<rule id="services">
    <priority>NORMAL</priority>
    <source>^(?!/updater/check/file(.*))/srv(/.*)?$</source>
    <reverse>/srv</reverse>
    <destination><url>/conf/gallery/sys/services$2</url></destination>
    <accept_path_info/>
</rule>
  • <source> est une regexp, pas un glob, et se compare n'importe où dans le chemin : sans ^, une règle écrite /srv(.*) prend aussi /blog/srvizio. Les règles de dossier commencent par ^ et finissent par (/.*)?$ ; le groupe à l'intérieur de (?!…) compte dans la numérotation (ici la destination utilise $2) ;
  • <reverse> est le préfixe utilisé pour reconstruire l'URL publique ;
  • <accept_path_info/> autorise le reste de chemin (sans lui, un reste fait échouer la règle) ;
  • <blocking>true</blocking> arrête l'évaluation des règles suivantes.

⚠️ CM_ENABLE_MEM_CACHING vaut false dans conf/gallery/config.php : le routeur relit les XML à chaque requête. Pratique (les modifications du routage sont immédiates), mais c'est aussi le fichier qu'on oublie le plus souvent d'envoyer lors d'un déploiement manuel. On peut l'activer depuis la config d'environnement, mais elle ne sert qu'avec un adaptateur redis ou memcached (12 §3).

Quand une règle pointe vers un fichier qui n'existe pas

cmsRouter::run() (vendor/wolfgan/cms/services/router.php) substitue les groupes de la regexp ($1, $2…) dans la destination même quand la destination est un fichier — pas seulement dans les redirections. Ensuite Cms::execute() (vendor/wolfgan/cms/Cms.php) vérifie, avant de l'inclure, que le fichier existe vraiment et se trouve dans la document root.

Les deux situations où on le voit :

  • une règle qui demande un groupe que le chemin n'a pas produit — la destination arrive avec le $1 littéral dedans ;
  • une destination mal écrite (par exemple la regexp du <source> copiée aussi dans l'<url>).

Dans les deux cas la réponse est 404, avec une ligne dans log_error. Avant c'était un fatal error require(): Failed opening required — un 500 sur tout le site, signalé comme un crash au lieu d'une page inexistante, et c'est ainsi que les scans automatiques appelant des chemins comme /install/make-config.php ou /…/sources/nginx.conf apparaissent dans Sentry.

Un détail de _getDiskPath() qui explique les chemins étranges dans les logs : une destination sans extension traîne /index.php à la fin (/conf/gallery/install → /conf/gallery/install/index.php).

Trois particularités de cmsRouter::regexp(), qui valent pour les routes du kernel et du schéma de page (pas pour les routing_table.xml, qui sont de vraies regexp lues par un autre routeur) :

  • le match ignore la casse (#…#i) : /INSTALL.md accroche ^/install(.*) comme le ferait /install/. C'est ainsi qu'un fichier de documentation essayé par un crawler a fini dans la route de l'installeur ;
  • la correspondance n'est pas ancrée en fin : ^/conf(.*) attrape tout ce qui commence par conf, pas seulement le dossier. Pour un dossier système la forme est ^/nom(/|$) : le dossier et ce qui se trouve dessous, rien de plus. Avec '^/conf*' une page /confronto répondait 404 avec un corps vide, avant même d'être résolue, et /errore finissait sur la page d'erreur du CMS.
  • * est développé en (.*) seulement quand c'est un vrai joker, c'est-à-dire hors d'un groupe déjà écrit à la main ; à l'intérieur d'un groupe il reste tel quel ((*) est la seule exception, et vaut groupe-joker). Avant cette correction le développement était aveugle : ^/install(.*) devenait ^/install(.(.*)), qui exige au moins un caractère après /install. Le kernel reconnaissait la page (il lit la regex sans la toucher) mais sa route ne se déclenchait pas sur l'URL « courte », et la requête finissait dans le cas actex de system_init_on_before_routing() : un E_USER_ERROR, c'est-à-dire un 500, à chaque GET /install. Si une règle semble ne pas se déclencher sur l'URL courte, c'est toujours le premier suspect.

La route déclarée par le schéma de page

Dans themes/site/settings.php une page peut déclarer sa propre route :

$schema["page"]["/scheda-dettaglio"] = array(
      /* ... */
    , "router" => array(
          "source"      => "^/scheda(.*)"
        , "destination" => "/scheda$0"
    )
);

Sous cette forme la route identifie la page, elle ne route pas : elle sert au kernel pour comprendre quelle entrée de $schema["page"] correspond à l'URL demandée (get_page_properties() dans vendor/wolfgan/cms/services/kernel.php, et library/gallery/system/cache.php pour la clé de cache). Celui qui l'exécute vraiment est library/gallery/system/init.php, avec addRule(), et seulement pour les groupes service et updater — c'est ainsi que /install arrive à conf/gallery/install/index.php, sans passer par le contrôle de conf/gallery/config.php (voir la note sur l'installeur legacy plus bas, dans la carte des routes). Si cette route ne clôt pas la requête (source qui ne correspond pas, destination inexistante), la requête continue et le routeur du Content Manager la prend ; avant cette correction le cas service/updater retombait au contraire dans le cas actex de system_init_on_before_routing(), qui lève un E_USER_ERROR (500).

⚠️ La table du kernel est en revanche une table regexp => destination. Fusionner la forme ci-dessus avec array_replace() y glissait deux routes appelées source et destination : deux regexp littérales et non ancrées, qui correspondent à toute URL contenant ces mots, avec la regexp elle-même pour destination. /esperto-risponde/sources/nginx.conf correspondait à #source#i et finissait dans un require() du chemin ^/esperto-risponde(.*) — fatal error à l'écran, pas 404. Désormais mergePageRouter() ne fusionne que la forme de table, et la forme {source, destination} reste une donnée de la page. Pour ajouter de vraies routes depuis le schéma de page on utilise donc la table : "router" => array('^/mon-chemin(/|$)' => '/cm/main.php'). La convention des règles de dossier vaut ici aussi — ^/nom(/|$), jamais '^/nom*', qui prend toute URL commençant ainsi.

Les XHR sur une page publique

Une requête avec X-Requested-With: XMLHttpRequest sur une page publique n'arrive pas forcément au module de son URL. library/gallery/system/init.php (groupes public, user et par défaut) essaie d'abord de rendre les sections de la page du Referer avec system_layer_gallery() : si quelque chose en sort, il l'enregistre en cache, l'affiche et termine la requête. C'est le rechargement ajax des blocs de la page courante. Restent exclus /user, /services, les espaces de VG_SITE_USER, VG_SITE_CART et VG_SITE_NOTIFY, les appels avec XHR_DIALOG_ID ou XHR_COMPONENT (les formulaires de ff.ajax) et, depuis la 3.1.3, tout POST.

Avant la 3.1.3 un POST XHR envoyé depuis une page qui a ses propres sections, comme la page d'accueil, recevait ces sections au lieu de la réponse du module. Le cas trouvé était le formulaire d'inscription de joecms.it, qui répondait avec le HTML de la page d'accueil. Depuis la page /registrazione cela fonctionnait, car là les sections sont vides et la requête continue. Un endpoint appelé en ajax en GET depuis une autre page reste exposé : il faut l'appeler avec XHR_COMPONENT, ou le placer sous /srv.

3. Les chemins réservés par le kernel

vendor/wolfgan/cms/services/kernel.php décide avant les règles XML :

MotifRésultat
^/applets(/|$), ^/cache(/|$), ^/cm(/|$), ^/conf(/|$), ^/contents(/|$), ^/ff(/|$), ^/installer(/|$), ^/library(/|$), ^/modules(/|$), ^/vendor(/|$)404
^/themes(/|$), ^/uploads(/|$), ^/asset(/|$)servis par cm/static.php
/restricted(/|$)espace réservé : /cm/main.php
^/static/*, ^/media/*, ^/showfiles/*fichiers : cm/static.php / cm/showfiles.php (l'astérisque vient après la barre : le dossier et ce qui est dessous)
^/api/1.0/API publique, dossier physique (/cm/main.php si Apache ne le sert pas)
^/api(?=/|$)…routé vers la REST interne du framework (Api::request)
^/srv(/|$)laissé aux règles XML
wp-login*401 (bruit de scan)

Le 404 du kernel vaut pour les requêtes qui arrivent à index.php. Un fichier qui existe sur le disque, Apache le servirait de lui-même, PHP compris : les PHP et les données des dossiers internes sont fermés par le .htaccess (14 §3).

Après le routage, juste après Auth::check(), le kernel résout aussi la langue préférée (language_pref_resolve()). Il peut répondre par un 302 vers l'URL préfixée avant toute sortie : voir 12 — Cache, §Multilingue.

Conséquences pratiques :

  • une page publique ne peut pas s'appeler /conf, /cache, /library… : le dossier est réservé, avec ou sans barre finale ;
  • un nom qui commence comme un dossier système est en revanche libre — /conferma, /errore, /cms, /assetto, /ffmpeg se résolvent comme des pages normales. Ce n'était pas le cas : avec la forme '^/conf*' le préfixe suffisait, et /confronto répondait 404 sans que rien ne le dise ;
  • /app reste libre : ^/applets(/|$) ne l'intercepte pas ;
  • /api est réservé : une API publique doit être servie depuis un dossier physique, voir 04 — API publique. Il n'est réservé que comme premier segment : /jd/api/me d'un module, /apicoltura, /en/api/… arrivent aux règles normales. Jusqu'à la 3.1.0, les deux règles /api du kernel et la règle api de conf/routing_table.xml n'étaient pas ancrées : tout chemin contenant /api finissait dans Api::request() et répondait 404 avec un corps vide, avant la page ou le module. De même pour /srv dans la règle services (/blog/srvizio).

4. La résolution du fichier remonte (et c'est pourquoi vous ne voyez jamais de 404)

cm/cm.php (autour des lignes 920-1000) essaie, pour /a/b/c :

  1. contents/a/b/c.php
  2. contents/a/b/c/index.php
  3. remonte avec dirname() : contents/a/b.php, en passant /c dans $cm->real_path_info
  4. …jusqu'à contents/index.php, qui existe toujours

Le reste non consommé finit dans real_path_info et la réponse est 200.

C'est le mécanisme qui fait fonctionner les pages avec un paramètre dans le chemin — /md/<permalink> en est l'exemple dans le dépôt. Mais sur un site fait de pages, cela signifie que /page-inventee affiche l'accueil avec un statut 200 : pour un moteur de recherche, N adresses différentes avec le même contenu.

La protection, si le projet est « à pages », est une seule garde en tête du moteur de rendu de page :

// s'il reste du chemin, la page demandée n'existe pas
if (class_exists("cm", false)) {                       // le false évite d'instancier le CMS en CLI
    $residuo = trim((string)cm::getInstance()->real_path_info, "/");
    if ($residuo !== "") { /* affiche le 404 et sort */ }
}

Quatre détails qui ont l'air de pinailler et ne le sont pas :

  • un reste fait seulement de barres ne compte pas : /prix/ a real_path_info = "/" et c'est la même page que /prix ;
  • la garde va dans le moteur de rendu commun, pas dans les pages individuelles : ainsi une nouvelle page en hérite, et les chemins qui utilisent vraiment le reste (/md, les endpoints /srv) n'y passent pas ;
  • $cm n'est pas une variable globale : cm/main.php s'exécute dans Cms::execute() (vendor/wolfgan/cms/Cms.php), un require dans une méthode statique, donc son $cm est local. Dans les scripts de contents/ il existe parce que callScript() le définit avant le require ; dans une fonction ou une méthode de classe appelée depuis là, non. $GLOBALS["cm"] est vide, le reste sort vide et la garde ne se déclenche jamais, sans erreur : sur joecms.it chaque chapitre du Guide affichait l'index. On utilise cm::getInstance(), comme get_pathinfo() dans library/gallery/common.php ;
  • le reste arrive en minuscules : cm/cm.php fait passer le chemin par ffCommon_url_normalize() (ff/common.php), qui se termine par mb_strtolower(). Un reste à comparer avec des noms qui ont des majuscules (00-INDICE.md) doit être comparé sans tenir compte de la casse.

5. Le schéma des requêtes : la whitelist des paramètres

Le kernel filtre la query string contre $schema["request"] (vendor/wolfgan/cms/services/kernel.php, ligne ~116). Si un GET non XHR porte des paramètres non déclarés, le kernel ne les ignore pas : il les classe unknown et redirige vers le même chemin en reconstruisant la query avec les seuls paramètres valides (lignes ~127-134).

Autrement dit : un callback OAuth, un lien UTM, un ?token= de confirmation perdent leurs paramètres et échouent sans aucune erreur visible, s'ils ne sont pas déclarés.

On les déclare dans themes/site/settings.php :

$schema["request"]["/"] = array(
    "get" => array("utm_source", "utm_medium", "utm_campaign", "optin")
);
$schema["request"]["/area-utente"] = array(
    "get"  => array("force_id"),
    "post" => array("name")
);

Deux faits utiles :

  • les règles se résolvent en cascade le long du chemin (dirname() en boucle) : l'entrée /app couvre aussi /app/cerca, /app/coda, … ;
  • le conf/schema.php des modules n'est PAS lu. library/gallery/system/cache.php (lignes ~91-94) ne charge que library/gallery/settings.php (core) et themes/<thème>/settings.php (projet). Un schema.php dans un module est du code mort : toutes les déclarations vont dans le thème.

Dans la même entrée on peut désactiver le cache pour ce chemin :

$schema["request"]["/OneSignalIdentity"] = array("get" => true, "nocache" => true);
$schema["request"]["/cerca"]             = array("get" => array("q"), "nocache" => array("q"));

"nocache" => true définit DISABLE_CACHE pour la requête ; avec un tableau il le fait seulement si l'un de ces paramètres est dans la query. C'est pour les réponses qui dépendent de l'utilisateur et ne doivent pas finir dans un cache partagé (voir 12).

Dans le même fichier on déclare aussi le cache de page :

$schema["page"]["/"] = array("name" => "public", "cache" => "guest");

Voir 12 — Cache et performances.

6. Carte des routes du core

D'après conf/routing_table.xml (état du dépôt) :

URLDestinationNotes
/install(.*)conf/gallery/installinstalleur legacy ; le dossier physique install/ n'existe que dans le dépôt — à la fin de l'installation install/cleanup.php le supprime, donc sur le site /install arrive au kernel. Sur un site installé il répond 404 (depuis la 3.1.5) : conf/gallery/install/index.php ne s'ouvre que depuis une URL sous /admin/ (Configuration → Base, /admin/configuration/install, derrière la connexion), parce que le formulaire est prérempli avec la configuration du site, mots de passe compris
/updater/check(.*)conf/gallery/updater/checkupdater upstream, de fait abandonné
/error/(.*)conf/gallery/errorpages d'erreur du CMS
(.*)/sitemap(.*), (.*)/feedconf/gallery/sitemapmoteur legacy ; JoeCMS utilise modules/cms-common/models/Sitemap.php (voir GUIDA_SITEMAP.md). Capture n'importe quel chemin contenant /sitemap, backend compris : une page /admin/…/sitemap n'est jamais atteinte (c'est pourquoi l'entrée de menu Utility → Sitemap ouvre /sitemap.xml)
/manifest.(.*)manifest PWA
/md(/.*)?contents/md/index.phpversion Markdown des contenus (GUIDA_INDICIZZAZIONE_AI.md)
/frame(.*)conf/gallery/sys/frame.phprendu en cadre
^/api/<ver>(.*)conf/gallery/api/...REST interne du framework ; seulement comme premier segment
^/srv(/.*)?$conf/gallery/sys/servicesservices système ; réécrit par le module cms-common (voir ci-dessous) ; seulement comme premier segment
/notify(.*)conf/gallery/modulesnotifications
/search(.*)conf/gallery/modules/searchrecherche
/user/vgallery, /user/resources, /user/draft, /user/menu, /user/manageespaces de gestion des contenus
/user/wishlist, /user/cart, /user/mpaye-commercevoir 10 — Modules
/ext/modules(.*)ressources des modules

Depuis les modules :

ModuleRègle
restricted^/restricted(.*) → /layout$0 ; ^/admin/settings(.*) → /settings$1
cms-common/srv/(.*) → /applets/services/$1 — c'est la règle qui rend les services de projet accessibles ; ^/srv/email-preview a une règle dédiée
auth^/oauth2/(.+), ^/apiserver/(.*), ^/services/oauth2/(.+) — ⚠️ les dossiers de destination n'existent pas dans ce dépôt : règles héritées de l'upstream, inertes aujourd'hui

7. Checklist quand une URL « ne répond pas comme elle devrait »

  1. Le chemin commence-t-il par un préfixe réservé par le kernel ? → 404 décidé avant les règles XML.
  2. La règle existe-t-elle mais le reste de chemin la fait échouer ? → il manque <accept_path_info/>.
  3. La page affiche-t-elle un autre contenu avec 200 ? → le routeur est remonté (§4). Si c'est une page qui utilise le reste (/guida/<chapitre>) et qu'elle affiche toujours la page de base, le reste est lu depuis $GLOBALS["cm"], qui est vide : il faut le lire depuis cm::getInstance() (§4).
  4. Un paramètre de query disparaît-il avec une redirection ? → il n'est pas dans $schema["request"] (§5).
  5. La page déclare-t-elle "router" dans le schéma sans qu'aucune route ne se déclenche ? → sous la forme {source, destination} elle identifie la page et ne route pas (§2).
  6. Vous avez modifié un XML et rien ne change ? → c'est un fichier modifié et non nouveau : dans un déploiement manuel c'est le premier qu'on oublie.
  7. Réponse périmée ? → cache de page, voir 12.