Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 01

Ciclo de una petición y enrutamiento

Qué ocurre entre la URL y el archivo PHP que responde. Es el capítulo que hay que leer primero: casi todas las sorpresas del stack nacen aquí.

1. La cadena de arranque

petición HTTP
  └─ .htaccess            ruta inexistente en el filesystem → reescribe a /index.php
       ▼
  index.php
    ├─ config.php ────────► GUARDA DE PRIMERA INSTALACIÓN (host no ".local" y falta
    │                        themes/site/conf/config.remote.php → incluye install/index.php, sale)
    ├─ themes/site/conf/config.{local|remote}.php   constantes de entorno
    ├─ conf/gallery/config.php                      config framework + vgallery
    ├─ vendor/autoload.php                          composer
    ├─ hook.php                                     helpers de la plataforma (~1.900 líneas);
    │    └─ hook.local.php                          al final, si existe: el código del sitio
    └─ Cms::getInstance("kernel")->run()            router → controller → ffPage → salida

No todos los puntos de entrada pasan por index.php. Tienen su propio bootstrap:

Punto de entradaSirve para
router.phpdispatch alternativo
cm/showfiles.phpservir y redimensionar imágenes (ver 11 — Medios y archivos)
cm/static.phprecursos estáticos (/themes, /uploads, /asset)
api/1.0/index.phpAPI pública, carpeta física (ver 04 — API pública)
install/index.phpasistente de primera instalación

Regla práctica: cualquier cosa que deba valer "siempre" (gestión de errores, constantes, correlation id) hay que engancharla a un arranque común, no a index.php.

2. El enrutamiento tiene tres niveles, más el kernel

Las reglas se recogen de varias fuentes y se ordenan por prioridad (TOP, VERY_HIGH, HIGH, NORMAL, LOW, VERY_LOW, BOTTOM):

NivelArchivoQué contiene
kernelvendor/wolfgan/cms/services/kernel.php (array interno)recursos estáticos y las rutas reservadas que responden 404
coreconf/routing_table.xmlsitemap, feed, error, install, updater, /md, /frame, /api, /srv, /notify, /search, /user/*
CMcm/conf/routing_table.xmlal final, la regla que hace existir las páginas: (.*) → /contents$0, prioridad BOTTOM
módulosmodules/<nombre>/conf/routing_table.xmlcargados automáticamente para cada carpeta en /modules

Anatomía de una regla (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> es una regexp, no un glob, y se compara en cualquier punto de la ruta: sin ^ una regla escrita /srv(.*) captura también /blog/srvizio. Las reglas de carpeta empiezan con ^ y terminan con (/.*)?$; el grupo dentro de (?!…) cuenta en la numeración (aquí la destination usa $2);
  • <reverse> es el prefijo usado para reconstruir la URL pública;
  • <accept_path_info/> autoriza el residuo de ruta (sin él, un residuo hace fallar la regla);
  • <blocking>true</blocking> detiene la evaluación de las reglas siguientes.

⚠️ CM_ENABLE_MEM_CACHING es false en conf/gallery/config.php: el router relee los XML en cada petición. Cómodo (los cambios al enrutamiento son inmediatos), pero es también el archivo que más a menudo se olvida subir en un despliegue manual. Se puede activar desde la config de entorno, pero solo sirve con un adaptador redis o memcached (12 §3).

Cuando una regla apunta a un archivo que no existe

cmsRouter::run() (vendor/wolfgan/cms/services/router.php) sustituye los grupos de la regexp ($1, $2…) en la destination también cuando la destination es un archivo — no solo en los redirects. Después Cms::execute() (vendor/wolfgan/cms/Cms.php) comprueba, antes de incluirlo, que el archivo exista de verdad y esté dentro de la document root.

Las dos situaciones en las que se nota:

  • una regla que pide un grupo que la ruta no ha producido — la destination llega con el $1 literal dentro;
  • una destination mal escrita (por ejemplo la regexp del <source> copiada también en el <url>).

En ambos casos la respuesta es 404, con una línea en log_error. Antes eran un fatal error require(): Failed opening required — un 500 en todo el sitio, señalado como caída en lugar de como página inexistente, y así es como aparecen en Sentry los escaneos automáticos que llaman a rutas como /install/make-config.php o /…/sources/nginx.conf.

Un detalle de _getDiskPath() que explica las rutas raras en los logs: una destination sin extensión arrastra /index.php al final (/conf/gallery/install → /conf/gallery/install/index.php).

Tres particularidades de cmsRouter::regexp(), que valen para las rutas del kernel y del esquema de página (no para los routing_table.xml, que son regexp verdaderas leídas por otro router):

  • el match no distingue mayúsculas (#…#i): /INSTALL.md engancha ^/install(.*) como lo haría /install/. Así es como un archivo de documentación probado por un crawler acabó dentro de la ruta del instalador;
  • el match no está anclado al final: ^/conf(.*) captura todo lo que empieza por conf, no solo la carpeta. Para una carpeta de sistema la forma es ^/nombre(/|$): la carpeta y lo que está debajo, nada más. Con '^/conf*' una página /confronto respondía 404 con el cuerpo vacío, antes incluso de resolverse, y /errore acababa en la página de error del CMS.
  • * se expande a (.*) solo cuando es un comodín de verdad, es decir fuera de un grupo ya escrito a mano; dentro de un grupo se queda como está ((*) es la única excepción, y vale como grupo-comodín). Antes de esta corrección la expansión era ciega: ^/install(.*) se convertía en ^/install(.(.*)), que exige al menos un carácter después de /install. El kernel reconocía la página (lee la regex sin tocarla) pero su ruta no se disparaba con la URL "corta", y la petición acababa en el caso actex de system_init_on_before_routing(): un E_USER_ERROR, es decir un 500, en cada GET /install. Si una regla parece no dispararse con la URL corta, la sospecha sigue siendo esta.

La ruta declarada por el esquema de página

En themes/site/settings.php una página puede declarar su propia ruta:

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

En esta forma la ruta identifica la página, no enruta: sirve al kernel para entender qué entrada de $schema["page"] corresponde a la URL pedida (get_page_properties() en vendor/wolfgan/cms/services/kernel.php, y library/gallery/system/cache.php para la clave de caché). Quien la ejecuta de verdad es library/gallery/system/init.php, con addRule(), y solo para los grupos service y updater — así es como /install llega a conf/gallery/install/index.php, sin pasar por el control de conf/gallery/config.php (ver la nota sobre el instalador legacy más abajo, en el mapa de rutas). Si esa ruta no cierra la petición (source que no coincide, destination inexistente) la petición sigue y la toma el router del Content Manager; antes de esta corrección el caso service/updater caía en cambio en el caso actex de system_init_on_before_routing(), que lanza un E_USER_ERROR (500).

⚠️ La tabla del kernel es en cambio un mapa regexp => destino. Fusionar la forma de arriba con array_replace() metía dos rutas llamadas source y destination: dos regexp literales y no ancladas, que coinciden con cualquier URL que contenga esas palabras, con la propia regexp como destino. /esperto-risponde/sources/nginx.conf coincidía con #source#i y acababa en un require() de la ruta ^/esperto-risponde(.*) — fatal error en pantalla, no 404. Ahora mergePageRouter() fusiona solo la forma de mapa, y la forma {source, destination} sigue siendo un dato de la página. Para añadir rutas de verdad desde el esquema de página se usa por tanto el mapa: "router" => array('^/mi-ruta(/|$)' => '/cm/main.php'). También aquí vale la convención de las reglas de carpeta — ^/nombre(/|$), nunca '^/nombre*', que se lleva toda URL que empiece así.

Las XHR en una página pública

Una petición con X-Requested-With: XMLHttpRequest en una página pública no llega necesariamente al módulo de su URL. library/gallery/system/init.php (grupos public, user y predeterminado) intenta primero generar las secciones de la página del Referer con system_layer_gallery(): si sale algo, lo guarda en caché, lo imprime y cierra la petición. Es la recarga ajax de los bloques de la página actual. Quedan fuera /user, /services, las áreas de VG_SITE_USER, VG_SITE_CART y VG_SITE_NOTIFY, las llamadas con XHR_DIALOG_ID o XHR_COMPONENT (los formularios de ff.ajax) y, desde la 3.1.3, todo POST.

Antes de la 3.1.3 un POST XHR enviado desde una página con secciones propias, como la página de inicio, recibía esas secciones en lugar de la respuesta del módulo. El caso encontrado fue el formulario de registro de joecms.it, que respondía con el HTML de la página de inicio. Desde la página /registrazione funcionaba, porque allí las secciones están vacías y la petición sigue. Un endpoint llamado por ajax en GET desde otra página sigue expuesto: hay que llamarlo con XHR_COMPONENT, o ponerlo bajo /srv.

3. Las rutas reservadas por el kernel

vendor/wolfgan/cms/services/kernel.php decide antes de las reglas XML:

PatrónResultado
^/applets(/|$), ^/cache(/|$), ^/cm(/|$), ^/conf(/|$), ^/contents(/|$), ^/ff(/|$), ^/installer(/|$), ^/library(/|$), ^/modules(/|$), ^/vendor(/|$)404
^/themes(/|$), ^/uploads(/|$), ^/asset(/|$)servidos por cm/static.php
/restricted(/|$)área reservada: /cm/main.php
^/static/*, ^/media/*, ^/showfiles/*archivos: cm/static.php / cm/showfiles.php (el asterisco va después de la barra: la carpeta y lo que está debajo)
^/api/1.0/API pública, carpeta física (/cm/main.php si Apache no la sirve)
^/api(?=/|$)…enrutado a la REST interna del framework (Api::request)
^/srv(/|$)dejado a las reglas XML
wp-login*401 (ruido de escaneo)

El 404 del kernel vale para las peticiones que llegan a index.php. Un archivo que existe en disco Apache lo serviría por su cuenta, PHP incluido: los PHP y los datos de las carpetas internas los cierra el .htaccess (14 §3).

Después del enrutamiento, justo después de Auth::check(), el kernel resuelve también el idioma preferido (language_pref_resolve()). Puede responder con un 302 hacia la URL con prefijo antes de cualquier salida: ver 12 — Caché, §Multilingüe.

Consecuencias operativas:

  • una página pública no puede llamarse /conf, /cache, /library…: la carpeta está reservada, con o sin barra final;
  • un nombre que empieza como una carpeta de sistema, en cambio, está libre — /conferma, /errore, /cms, /assetto, /ffmpeg se resuelven como páginas normales. No era así: con la forma '^/conf*' bastaba el prefijo, y /confronto respondía 404 sin que nada lo dijera;
  • /app sigue libre: ^/applets(/|$) no lo intercepta;
  • /api está reservado: una API pública debe servirse desde una carpeta física, ver 04 — API pública. Está reservado solo como primer segmento: /jd/api/me de un módulo, /apicoltura, /en/api/… llegan a las reglas normales. Hasta la 3.1.0 las dos reglas /api del kernel y la regla api de conf/routing_table.xml no estaban ancladas: cualquier ruta que contuviera /api acababa en Api::request() y respondía 404 con el cuerpo vacío, antes de la página o del módulo. Lo mismo para /srv en la regla services (/blog/srvizio).

4. La resolución del archivo va hacia atrás (y por eso nunca ves un 404)

cm/cm.php (en torno a las líneas 920-1000) prueba, para /a/b/c:

  1. contents/a/b/c.php
  2. contents/a/b/c/index.php
  3. sube con dirname(): contents/a/b.php, pasando /c en $cm->real_path_info
  4. …hasta contents/index.php, que siempre existe

El residuo no consumido acaba en real_path_info y la respuesta es 200.

Es el mecanismo que hace funcionar las páginas con un parámetro en la ruta — /md/<permalink> es el ejemplo en el repo. Pero en un sitio hecho de páginas significa que /pagina-inventada muestra la home con status 200: para un buscador, N direcciones distintas con el mismo contenido.

La protección, si el proyecto es "de páginas", es una sola guarda al principio del renderizador de página:

// si sobra ruta, la página pedida no existe
if (class_exists("cm", false)) {                       // el false evita instanciar el CMS desde CLI
    $residuo = trim((string)cm::getInstance()->real_path_info, "/");
    if ($residuo !== "") { /* renderiza el 404 y sale */ }
}

Cuatro detalles que parecen minucias y no lo son:

  • el residuo de solo barras no cuenta: /precios/ tiene real_path_info = "/" y es la misma página que /precios;
  • la guarda va en el renderizador común, no en las páginas individuales: así una página nueva la hereda, y las rutas que usan de verdad el residuo (/md, los endpoints /srv) no pasan por ella;
  • $cm no es una variable global: cm/main.php se ejecuta dentro de Cms::execute() (vendor/wolfgan/cms/Cms.php), un require en un método estático, así que su $cm es local. En los scripts de contents/ existe porque callScript() la define antes del require; en una función o en un método de clase llamado desde ahí, no. $GLOBALS["cm"] está vacío, el residuo sale vacío y la guarda no salta nunca, sin un error: en joecms.it cada capítulo de la Guía mostraba el índice. Se usa cm::getInstance(), como get_pathinfo() en library/gallery/common.php;
  • el residuo llega en minúsculas: cm/cm.php pasa la ruta por ffCommon_url_normalize() (ff/common.php), que termina con mb_strtolower(). Un residuo que se compara con nombres que tienen mayúsculas (00-INDICE.md) debe compararse sin distinguir mayúsculas.

5. El esquema de las requests: la whitelist de parámetros

El kernel filtra la query string contra $schema["request"] (vendor/wolfgan/cms/services/kernel.php, línea ~116). Si una GET no XHR lleva parámetros no declarados, el kernel no los ignora: los clasifica como unknown y redirige a la misma ruta reconstruyendo la query solo con los parámetros válidos (líneas ~127-134).

Traducido: un callback OAuth, un enlace UTM, un ?token= de confirmación pierden los parámetros y fallan sin ningún error visible, si no están declarados.

Se declaran en 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")
);

Dos hechos útiles:

  • las reglas se resuelven en cascada sobre la ruta (dirname() en bucle): la entrada /app cubre también /app/cerca, /app/coda, …;
  • el conf/schema.php de los módulos NO se lee. library/gallery/system/cache.php (líneas ~91-94) carga solo library/gallery/settings.php (core) y themes/<tema>/settings.php (proyecto). Un schema.php dentro de un módulo es código muerto: todas las declaraciones van en el tema.

En la misma entrada se puede apagar la caché para esa ruta:

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

"nocache" => true define DISABLE_CACHE para la petición; con un array lo hace solo si en la query hay uno de esos parámetros. Sirve para las respuestas que dependen del usuario y no deben acabar en una caché compartida (ver 12).

En el mismo archivo se declara también la caché de página:

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

Ver 12 — Caché y rendimiento.

6. Mapa de las rutas del core

De conf/routing_table.xml (estado del repo):

URLDestinoNotas
/install(.*)conf/gallery/installinstalador legacy; el directorio físico install/ existe solo en el repo — al final de la instalación install/cleanup.php lo borra, así que en el sitio /install llega al kernel. En un sitio instalado responde 404 (desde la 3.1.5): conf/gallery/install/index.php solo se abre desde una URL bajo /admin/ (Configuración → Básica, /admin/configuration/install, tras el login), porque el formulario se rellena con la configuración del sitio, contraseñas incluidas
/updater/check(.*)conf/gallery/updater/checkupdater upstream, en la práctica retirado
/error/(.*)conf/gallery/errorpáginas de error del CMS
(.*)/sitemap(.*), (.*)/feedconf/gallery/sitemapmotor legacy; JoeCMS usa modules/cms-common/models/Sitemap.php (ver GUIDA_SITEMAP.md). Captura cualquier ruta que contenga /sitemap, backend incluido: una página /admin/…/sitemap no se alcanza nunca (por eso la entrada de menú Utility → Sitemap abre /sitemap.xml)
/manifest.(.*)manifest PWA
/md(/.*)?contents/md/index.phpversión Markdown de los contenidos (GUIDA_INDICIZZAZIONE_AI.md)
/frame(.*)conf/gallery/sys/frame.phprenderizado en marco
^/api/<ver>(.*)conf/gallery/api/...REST interna del framework; solo como primer segmento
^/srv(/.*)?$conf/gallery/sys/servicesservicios de sistema; reescrito por el módulo cms-common (ver abajo); solo como primer segmento
/notify(.*)conf/gallery/modulesnotificaciones
/search(.*)conf/gallery/modules/searchbúsqueda
/user/vgallery, /user/resources, /user/draft, /user/menu, /user/manageáreas de gestión de contenidos
/user/wishlist, /user/cart, /user/mpaye-commercever 10 — Módulos
/ext/modules(.*)recursos de los módulos

De los módulos:

MóduloRegla
restricted^/restricted(.*) → /layout$0; ^/admin/settings(.*) → /settings$1
cms-common/srv/(.*) → /applets/services/$1 — es la regla que hace alcanzables los servicios de proyecto; ^/srv/email-preview tiene una regla dedicada
auth^/oauth2/(.+), ^/apiserver/(.*), ^/services/oauth2/(.+) — ⚠️ las carpetas de destino no existen en este repo: reglas heredadas del upstream, hoy inertes

7. Checklist cuando una URL "no responde como debería"

  1. ¿La ruta empieza por un prefijo reservado por el kernel? → 404 decidido antes de las reglas XML.
  2. ¿La regla existe pero el residuo de ruta la hace fallar? → falta <accept_path_info/>.
  3. ¿La página muestra otro contenido con 200? → el router ha subido (§4). Si es una página que usa el residuo (/guida/<capítulo>) y muestra siempre la página base, el residuo se lee de $GLOBALS["cm"], que está vacío: hay que leerlo de cm::getInstance() (§4).
  4. ¿Un parámetro en la query desaparece y hay un redirect? → no está en $schema["request"] (§5).
  5. ¿La página declara "router" en el esquema pero no se dispara ninguna ruta? → en la forma {source, destination} identifica la página y no enruta (§2).
  6. ¿Has modificado un XML y no cambia nada? → es un archivo modificado y no nuevo: en un despliegue manual es el primero que se olvida.
  7. ¿Respuesta vieja? → caché de página, ver 12.