Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 01

Ciclo di una richiesta e routing

Cosa succede fra l'URL e il file PHP che risponde. È il capitolo da leggere per primo: quasi tutte le sorprese dello stack nascono qui.

1. La catena di avvio

richiesta HTTP
  └─ .htaccess            path non esistente sul filesystem → riscrive su /index.php
       ▼
  index.php
    ├─ config.php ────────► GUARD PRIMA INSTALLAZIONE (host non ".local" e manca
    │                        themes/site/conf/config.remote.php → include install/index.php, esce)
    ├─ themes/site/conf/config.{local|remote}.php   costanti d'ambiente
    ├─ conf/gallery/config.php                      config framework + vgallery
    ├─ vendor/autoload.php                          composer
    ├─ hook.php                                     helper della piattaforma (~1.900 righe);
    │    └─ hook.local.php                          in fondo, se c'è: il codice del sito
    └─ Cms::getInstance("kernel")->run()            router → controller → ffPage → output

Non tutti gli entry point passano da index.php. Hanno un bootstrap proprio:

Entry pointServe a
router.phpdispatch alternativo
cm/showfiles.phpserving e ridimensionamento delle immagini (vedi 11 — Media e file)
cm/static.phpasset statici (/themes, /uploads, /asset)
api/1.0/index.phpAPI pubblica, cartella fisica (vedi 04 — API pubblica)
install/index.phpwizard di prima installazione

Regola pratica: qualunque cosa debba valere "sempre" (error handling, costanti, correlation id) va agganciata a un boot comune, non a index.php.

2. Il routing è su tre livelli, più il kernel

Le regole vengono raccolte da più sorgenti e ordinate per priorità (TOP, VERY_HIGH, HIGH, NORMAL, LOW, VERY_LOW, BOTTOM):

LivelloFileCosa contiene
kernelvendor/wolfgan/cms/services/kernel.php (array interno)asset statici e i path riservati che rispondono 404
coreconf/routing_table.xmlsitemap, feed, error, install, updater, /md, /frame, /api, /srv, /notify, /search, /user/*
CMcm/conf/routing_table.xmlin coda la regola che fa esistere le pagine: (.*) → /contents$0, priorità BOTTOM
modulimodules/<nome>/conf/routing_table.xmlcaricati automaticamente per ogni cartella in /modules

Anatomia di una regola (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> è una regexp, non un glob, e si confronta ovunque nel percorso: senza ^ una regola scritta /srv(.*) prende anche /blog/srvizio. Le regole di cartella cominciano con ^ e finiscono con (/.*)?$; il gruppo dentro (?!…) conta nella numerazione (qui la destinazione usa $2);
  • <reverse> è il prefisso usato per ricostruire l'URL pubblico;
  • <accept_path_info/> autorizza il residuo di percorso (senza, un residuo fa fallire la regola);
  • <blocking>true</blocking> ferma la valutazione delle regole successive.

⚠️ CM_ENABLE_MEM_CACHING è false in conf/gallery/config.php: il router rilegge gli XML a ogni richiesta. Comodo (le modifiche al routing sono immediate), ma è anche il file che ci si dimentica più spesso di caricare in un deploy manuale. Si può accendere dal config d'ambiente, ma serve solo con un adapter redis o memcached (12 §3).

Quando una regola punta a un file che non c'è

cmsRouter::run() (vendor/wolfgan/cms/services/router.php) sostituisce i gruppi della regexp ($1, $2…) nella destination anche quando la destination è un file — non solo nei redirect. Poi Cms::execute() (vendor/wolfgan/cms/Cms.php) controlla, prima di includerlo, che il file esista davvero e stia dentro la document root.

Le due situazioni in cui questo si vede:

  • una regola che chiede un gruppo che il path non ha prodotto — la destination arriva con dentro il $1 letterale;
  • una destination scritta male (per esempio la regexp del <source> copiata anche nell'<url>).

In entrambi i casi la risposta è 404, con una riga in log_error. Prima erano un fatal error require(): Failed opening required — un 500 su tutto il sito, segnalato come crash invece che come pagina inesistente, ed è così che si presentano in Sentry le scansioni automatiche che chiamano percorsi come /install/make-config.php o /…/sources/nginx.conf.

Un dettaglio di _getDiskPath() che spiega i percorsi strani nei log: una destination senza estensione si porta dietro /index.php in coda (/conf/gallery/install → /conf/gallery/install/index.php).

Tre particolari di cmsRouter::regexp(), che valgono per le rotte del kernel e dello schema di pagina (non per i routing_table.xml, che sono regexp vere lette da un altro router):

  • il match è case-insensitive (#…#i): /INSTALL.md aggancia ^/install(.*) come farebbe /install/. È così che un file di documentazione provato da un crawler è finito dentro la rotta dell'installer;
  • il match non è ancorato in coda: ^/conf(.*) cattura tutto ciò che comincia per conf, non solo la cartella. Per una cartella di sistema la forma è ^/nome(/|$): la cartella e ciò che sta sotto, nient'altro. Con '^/conf*' una pagina /confronto rispondeva 404 con corpo vuoto, prima ancora di essere risolta, e /errore finiva sulla pagina d'errore del CMS.
  • * viene espanso in (.*) solo quando è un jolly vero e proprio, cioè fuori da un gruppo già scritto a mano; dentro un gruppo resta com'è ((*) è l'unica eccezione, e vale come gruppo-jolly). Prima di questa correzione l'espansione era cieca: ^/install(.*) diventava ^/install(.(.*)), che pretende almeno un carattere dopo /install. La pagina veniva riconosciuta dal kernel (che legge la regex senza toccarla) ma la sua rotta non scattava sull'URL "corto", e la richiesta finiva nel caso actex di system_init_on_before_routing(): un E_USER_ERROR, cioè un 500, su ogni GET /install. Se una regola sembra non scattare sull'URL corto, il sospetto resta questo.

La rotta dichiarata dallo schema di pagina

In themes/site/settings.php una pagina può dichiarare una propria rotta:

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

In questa forma la rotta identifica la pagina, non instrada: serve al kernel per capire quale voce di $schema["page"] corrisponde all'URL richiesto (get_page_properties() in vendor/wolfgan/cms/services/kernel.php, e library/gallery/system/cache.php per la chiave di cache). A eseguirla davvero è library/gallery/system/init.php, con addRule(), e solo per i gruppi service e updater — è così che /install arriva a conf/gallery/install/index.php, senza passare dal controllo di conf/gallery/config.php (vedi la nota sull'installer legacy più sotto, nella mappa delle rotte). Se quella rotta non chiude la richiesta (source che non matcha, destination inesistente) la richiesta prosegue e la prende il router del Content Manager; prima di questa correzione il caso service/updater ricadeva invece nel caso actex di system_init_on_before_routing(), che alza un E_USER_ERROR (500).

⚠️ La tabella del kernel è invece una mappa regexp => destinazione. Fondere la forma qui sopra con array_replace() ci infilava due rotte chiamate source e destination: due regexp letterali e non ancorate, che matchano qualunque URL contenga quelle parole, con per destinazione la regexp stessa. /esperto-risponde/sources/nginx.conf matchava #source#i e finiva in un require() del percorso ^/esperto-risponde(.*) — fatal error a video, non 404. Ora mergePageRouter() fonde solo la forma a mappa, e la forma {source, destination} resta un dato della pagina. Per aggiungere rotte vere dallo schema di pagina si usa quindi la mappa: "router" => array('^/mio-path(/|$)' => '/cm/main.php'). Vale anche qui la convenzione delle regole di cartella — ^/nome(/|$), mai '^/nome*', che si prende ogni URL che comincia così.

Le XHR su una pagina pubblica

Una richiesta con X-Requested-With: XMLHttpRequest su una pagina pubblica non arriva per forza al modulo dell'URL. library/gallery/system/init.php (gruppi public, user e predefinito) prova prima a rendere le sezioni della pagina del Referer con system_layer_gallery(): se ne esce qualcosa lo salva in cache, lo stampa e chiude la richiesta. È la ricarica ajax dei blocchi della pagina corrente. Restano fuori /user, /services, le aree di VG_SITE_USER, VG_SITE_CART e VG_SITE_NOTIFY, le chiamate con XHR_DIALOG_ID o XHR_COMPONENT (i form di ff.ajax) e, dalla 3.1.3, ogni POST.

Prima della 3.1.3 una POST XHR mandata da una pagina con sezioni proprie, come la home, riceveva quelle sezioni al posto della risposta del modulo. Il caso trovato è stato il form di registrazione su joecms.it, che rispondeva con l'HTML della home. Dalla pagina /registrazione funzionava, perché lì le sezioni sono vuote e la richiesta prosegue. Un endpoint chiamato via ajax in GET da un'altra pagina è ancora esposto: va chiamato con XHR_COMPONENT, oppure messo sotto /srv.

3. I path riservati dal kernel

vendor/wolfgan/cms/services/kernel.php decide prima delle regole XML:

PatternEsito
^/applets(/|$), ^/cache(/|$), ^/cm(/|$), ^/conf(/|$), ^/contents(/|$), ^/ff(/|$), ^/installer(/|$), ^/library(/|$), ^/modules(/|$), ^/vendor(/|$)404
^/themes(/|$), ^/uploads(/|$), ^/asset(/|$)serviti da cm/static.php
/restricted(/|$)area riservata: /cm/main.php
^/static/*, ^/media/*, ^/showfiles/*file: cm/static.php / cm/showfiles.php (l'asterisco sta dopo la barra: cartella e sotto)
^/api/1.0/API pubblica, cartella fisica (/cm/main.php se Apache non la serve)
^/api(?=/|$)…instradato alla REST interna del framework (Api::request)
^/srv(/|$)lasciato alle regole XML
wp-login*401 (rumore di scansione)

Il 404 del kernel vale per le richieste che arrivano a index.php. Un file che esiste su disco Apache lo servirebbe da sé, PHP compreso: i PHP e i dati delle cartelle interne li chiude il .htaccess (14 §3).

Dopo il routing, subito dopo Auth::check(), il kernel risolve anche la lingua preferita (language_pref_resolve()). Può rispondere con un 302 verso l'URL prefissato prima di qualunque output: vedi 12 — Cache, §Multilingua.

Conseguenze operative:

  • una pagina pubblica non può chiamarsi /conf, /cache, /library…: la cartella è riservata, con o senza barra finale;
  • un nome che comincia come una cartella di sistema è invece libero — /conferma, /errore, /cms, /assetto, /ffmpeg si risolvono come pagine normali. Non era così: con la forma '^/conf*' bastava il prefisso, e /confronto rispondeva 404 senza che nulla lo dicesse;
  • /app resta libero: ^/applets(/|$) non lo intercetta;
  • /api è riservato: un'API pubblica va servita da una cartella fisica, vedi 04 — API pubblica. È riservato solo come primo segmento: /jd/api/me di un modulo, /apicoltura, /en/api/… arrivano alle regole normali. Fino alla 3.1.0 le due regole /api del kernel e la regola api di conf/routing_table.xml non erano ancorate: qualunque percorso che contenesse /api finiva in Api::request() e rispondeva 404 con corpo vuoto, prima della pagina o del modulo. Lo stesso per /srv nella regola services (/blog/srvizio).

4. La risoluzione del file procede a ritroso (e per questo non vedi mai un 404)

cm/cm.php (intorno alle righe 920-1000) prova, per /a/b/c:

  1. contents/a/b/c.php
  2. contents/a/b/c/index.php
  3. risale con dirname(): contents/a/b.php, passando /c in $cm->real_path_info
  4. …fino a contents/index.php, che c'è sempre

Il residuo non consumato finisce in real_path_info e la risposta è 200.

È il meccanismo che fa funzionare le pagine con un parametro nel percorso — /md/<permalink> ne è l'esempio nel repo. Ma su un sito fatto di pagine significa che /pagina-inventata mostra la home con status 200: per un motore di ricerca, N indirizzi diversi con lo stesso contenuto.

Il presidio, se il progetto è "a pagine", è una guardia sola in cima al renderer di pagina:

// se avanza percorso, la pagina chiesta non esiste
if (class_exists("cm", false)) {                       // il false evita di istanziare il CMS da CLI
    $residuo = trim((string)cm::getInstance()->real_path_info, "/");
    if ($residuo !== "") { /* rendi il 404 ed esci */ }
}

Quattro dettagli che sembrano cavilli e non lo sono:

  • il residuo di sole barre non conta: /prezzi/ ha real_path_info = "/" ed è la stessa pagina di /prezzi;
  • la guardia va nel renderer comune, non nelle singole pagine: così una pagina nuova la eredita, e i percorsi che il residuo lo usano davvero (/md, gli endpoint /srv) non ci passano;
  • $cm non è una variabile globale: cm/main.php gira dentro Cms::execute() (vendor/wolfgan/cms/Cms.php), un require in un metodo statico, quindi il suo $cm è locale. Negli script di contents/ c'è perché callScript() lo definisce prima del require; in una funzione o in un metodo di classe chiamato da lì no. $GLOBALS["cm"] è vuoto, il residuo esce vuoto e la guardia non scatta mai, senza un errore: su joecms.it ogni capitolo della Guida mostrava l'indice. Si usa cm::getInstance(), come get_pathinfo() in library/gallery/common.php;
  • il residuo arriva in minuscolo: cm/cm.php passa il percorso da ffCommon_url_normalize() (ff/common.php), che finisce con mb_strtolower(). Un residuo da confrontare con nomi che hanno maiuscole (00-INDICE.md) va confrontato senza distinzione di maiuscole.

5. Lo schema delle request: la whitelist dei parametri

Il kernel filtra la query string contro $schema["request"] (vendor/wolfgan/cms/services/kernel.php, riga ~116). Se una GET non-XHR porta parametri non dichiarati, il kernel non li ignora: li classifica unknown e redirige sullo stesso path ricostruendo la query con i soli parametri validi (righe ~127-134).

Tradotto: un callback OAuth, un link UTM, un ?token= di conferma perdono i parametri e falliscono senza alcun errore visibile, se non sono dichiarati.

Si dichiarano in 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")
);

Due fatti utili:

  • le regole si risolvono a cascata sul path (dirname() in ciclo): la voce /app copre anche /app/cerca, /app/coda, …;
  • conf/schema.php dei moduli NON viene letto. library/gallery/system/cache.php (righe ~91-94) carica solo library/gallery/settings.php (core) e themes/<tema>/settings.php (progetto). Un schema.php dentro un modulo è codice morto: tutte le dichiarazioni vanno nel tema.

Nella stessa voce si può spegnere la cache per quel percorso:

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

"nocache" => true definisce DISABLE_CACHE per la richiesta; con un array lo fa solo se in query c'è uno di quei parametri. Serve alle risposte che dipendono dall'utente e non devono finire in una cache condivisa (vedi 12).

Nello stesso file si dichiara anche la cache di pagina:

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

Vedi 12 — Cache e prestazioni.

6. Mappa delle rotte del core

Da conf/routing_table.xml (stato del repo):

URLDestinazioneNote
/install(.*)conf/gallery/installinstaller legacy; la dir fisica install/ esiste solo nel repo — a fine installazione install/cleanup.php la cancella, quindi sul sito /install arriva al kernel. Su un sito installato risponde 404 (dalla 3.1.5): conf/gallery/install/index.php si apre solo da un URL sotto /admin/ (Configurazione → Base, /admin/configuration/install, dietro login), perché il form si precompila con la config del sito, password comprese
/updater/check(.*)conf/gallery/updater/checkupdater upstream, di fatto dismesso
/error/(.*)conf/gallery/errorpagine di errore del CMS
(.*)/sitemap(.*), (.*)/feedconf/gallery/sitemapmotore legacy; JoeCMS usa modules/cms-common/models/Sitemap.php (vedi GUIDA_SITEMAP.md). Cattura qualunque percorso che contiene /sitemap, backoffice compreso: una pagina /admin/…/sitemap non si raggiunge mai (la voce di menu Utility → Sitemap per questo apre /sitemap.xml)
/manifest.(.*)manifest PWA
/md(/.*)?contents/md/index.phpversione Markdown dei contenuti (GUIDA_INDICIZZAZIONE_AI.md)
/frame(.*)conf/gallery/sys/frame.phprendering in cornice
^/api/<ver>(.*)conf/gallery/api/...REST interna del framework; solo come primo segmento
^/srv(/.*)?$conf/gallery/sys/servicesservizi di sistema; riscritto dal modulo cms-common (vedi sotto); solo come primo segmento
/notify(.*)conf/gallery/modulesnotifiche
/search(.*)conf/gallery/modules/searchricerca
/user/vgallery, /user/resources, /user/draft, /user/menu, /user/managearee di gestione contenuti
/user/wishlist, /user/cart, /user/mpaye-commercevedi 10 — Moduli
/ext/modules(.*)risorse dei moduli

Dai moduli:

ModuloRegola
restricted^/restricted(.*) → /layout$0; ^/admin/settings(.*) → /settings$1
cms-common/srv/(.*) → /applets/services/$1 — è la regola che rende i servizi di progetto raggiungibili; ^/srv/email-preview ha una regola dedicata
auth^/oauth2/(.+), ^/apiserver/(.*), ^/services/oauth2/(.+) — ⚠️ le cartelle di destinazione non esistono in questo repo: regole ereditate dall'upstream, oggi inerti

7. Checklist quando un URL "non risponde come dovrebbe"

  1. Il path inizia con un prefisso riservato dal kernel? → 404 deciso prima delle regole XML.
  2. La regola esiste ma il residuo di percorso la fa fallire? → manca <accept_path_info/>.
  3. La pagina mostra un altro contenuto con 200? → il router è risalito (§4). Se è una pagina che il residuo lo usa (/guida/<capitolo>) e mostra sempre la pagina base, il residuo è letto da $GLOBALS["cm"], che è vuoto: va letto da cm::getInstance() (§4).
  4. Un parametro in query sparisce e c'è un redirect? → non è in $schema["request"] (§5).
  5. La pagina dichiara "router" nello schema ma nessuna rotta scatta? → in forma {source, destination} identifica la pagina e non instrada (§2).
  6. Hai modificato un XML e non cambia niente? → è un file modificato e non nuovo: in un deploy manuale è il primo che si dimentica.
  7. Risposta vecchia? → cache di pagina, vedi 12.