Módulos y servicios de terceros
Dos mecanismos de extensión, con nombres que se parecen y objetivos distintos: los módulos añaden código, rutas y páginas; los servicios inyectan tags de terceros (analytics, mapas, fuentes, píxeles) configurables desde el backend sin tocar el código.
1. Módulos: código de proyecto fuera de hook.php
Cada carpeta dentro de /modules se carga automáticamente. La estructura típica:
modules/<nombre>/
├── common.php funciones del módulo (cargadas por el CMS)
├── autoload.php autoloader propio (opcional)
├── events.php enganche a los eventos del ciclo de página (opcional)
├── conf/
│ ├── routing_table.xml rutas del módulo → cargadas automáticamente
│ └── mod_restricted.xml entradas del backend
├── models/ clases del módulo
├── contents/ páginas del módulo
├── library/
│ ├── job/<nombre>.php funciones job_<nombre>() (check_function("job_..."))
│ └── system/<nombre>.php funciones system_<nombre>() (check_function("system_..."))
└── themes/ CSS/JS/plantillas del módulo
Los módulos presentes en el repo:
| Módulo | Contenido |
|---|---|
auth | login, registro, recuperación, activación, social (08) |
restricted | el backend: ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1 |
cms-common | el módulo de proyecto: la regla /srv/(.*) → /applets/services/$1 y models/Sitemap.php |
security | contenidos del módulo de seguridad |
package-manager | gestión de módulos y extensiones (.zip): subida al estilo WordPress, auto-migración de BD y asistente |
Dónde poner el código de un proyecto nuevo: en un módulo, no en
hook.php.hook.phpes código de la plataforma (~1.900 líneas de helpers legacy) y la actualización lo sustituye: una línea del proyecto escrita allí desaparece con la versión siguiente. Un módulo tiene autoload propio, se carga solo, y se puede llevar a otro proyecto copiando una carpeta.modules/cms-commones el sitio adecuado para lo que es común, un módulo dedicado para lo que es del producto. Para pocas líneas (un listener deAuth::addEvent(), un helper) estáhook.local.php, junto ahook.php:hook.phplo incluye al final, no está en el paquete y la actualización no lo toca. Un valor que cambiar (dominio,AREA_*,MAX_UPLOAD) va en cambio en el config.
⚠️ El conf/schema.php dentro de un módulo no se lee. Solo se cargan library/gallery/settings.php (core) y themes/<tema>/settings.php (proyecto). modules/cms-common/conf/schema.php existe y es código muerto: las declaraciones de $schema["request"] y $schema["page"] van en el tema (ver 01 §5).
Package Manager: instalación de módulos ZIP y auto-migración de BD
El módulo package-manager (/admin/pacchetti) proporciona al backend de JoeCMS un área para subir archivos ZIP que contengan módulos y extensiones, gestionando todo su ciclo de vida:
- Validación de seguridad: comprobación del archivo ZIP con bloqueo de rutas peligrosas (path traversal
../o absolutas). - Lectura del descriptor
manifest.json: metadatos del módulo, versión mínima de JoeCMS requerida, dependencias. - Extracción selectiva: descomprime los componentes en sus respectivas carpetas (
modules/<id>/,contents/,themes/). - Actualización automática de base de datos: si el manifest especifica
database.schema, ejecuta automáticamente la DDL SQL a través de la conexión activa. - Asistente de configuración post-instalación: redirige opcionalmente al asistente de configuración para rutas y parámetros del módulo.
Autoload por convención
check_function() en library/gallery/common.php carga el archivo correcto a partir del nombre de la función:
| Prefijo | Archivo buscado |
|---|---|
job_<x> | modules/<mod>/library/job/<x>.php, luego library/gallery/job/<x>.php |
system_<x> | modules/<mod>/library/system/<x>.php, luego library/gallery/system/<x>.php |
mod_<mod>_<x> | modules/<mod>/events.php |
Es el motivo por el que en todo el código se encuentra if (check_function("system_algo")) { … }: el archivo se incluye solo si hace falta.
2. Los módulos funcionales del CMS
conf/gallery/modules/ contiene subsistemas completos, cada uno con configuración y gestión en el backend:
| Módulo | Qué hace |
|---|---|
form | constructor de formularios: definición de campos desde el backend, selecciones, tarifas, envío de email con plantilla, revisiones, archivo de las respuestas (manage/, detail.php) |
search | búsqueda en los contenidos, con configuración, grupos, extras y vista previa |
newsletter | suscripciones y envíos |
calendar | eventos de calendario |
maps | mapas |
share | compartir en redes sociales |
tagcloud | nube de etiquetas |
videobar, fbalbum, swf | medios y galerías (componentes antiguos) |
register | registro |
shippingprice | gastos de envío (e-commerce) |
El módulo form es el que más a menudo ahorra trabajo: un formulario de contacto, una solicitud de presupuesto, un cuestionario se configuran desde el backend — campos, validaciones, email de notificación, lista de respuestas — sin escribir una página.
E-commerce
Hay un andamiaje: rutas /user/cart, /user/wishlist, /user/manage, /user/mpay, library/gallery/ecommerce/product_process.php, conf/gallery/manage/ con operaciones y pagos, el job reset_carts, library/PayPal/, y las tablas relacionadas en el seed.
⚠️ Es código upstream no probado en este prototipo. Tratarlo como punto de partida por verificar, no como funcionalidad lista.
Pagos: el hub Payment
Independiente del andamiaje anterior: es el lugar donde un proyecto cobra sin escribir su propia integración. library/payment/Payment.php declara qué significa cobrar, las pasarelas son drivers en library/payment/services/<nombre>.php (clase payment<Nombre>), y el hub las carga por sí solo: en los autoloaders hay un único caso, Payment, tanto en el autoload.php raíz (lo incluye la API) como en vendor/wolfgan/autoload.php, el que index.php carga vía Composer. Hasta la 1.6.2 el segundo no lo tenía, y desde el sitio el checkout, los webhooks y los cron de pagos morían con "Class Payment not found".
$esito = Payment::gateway()->checkout(array(
"riferimento" => "acquisto:1234", // tu propio ID, no el de la pasarela
"descrizione" => "Bono de 10 clases",
"importo_cent" => 18000, // siempre enteros en céntimos, nunca float
"email" => "anna@ejemplo.es",
"ritorno_ok" => "https://sitio/area/compra?esito=ok",
"ritorno_ko" => "https://sitio/area/compra?esito=annullato",
));
// array(ok, id, url, error): se envía a la persona a url
Cada driver expone checkout() (pago único), subscribe() (recurrente), verify() y subscriptionVerify() (estado real), subscriptionCancel(), refund(), webhookVerify(). verify() responde siempre con la misma forma, con un estado normalizado: pagato, in_attesa, fallito, rimborsato, annullato (constantes Payment::PAGATO y siguientes). La pasarela se elige con Payment::gateway('<nombre>'), o con la constante PAYMENT_GATEWAY; el valor inicial es stripe.
- El webhook dispara, la verdad se va a leer. Del cuerpo de un webhook no se aplica nada: se verifica la firma (
webhookVerify()), se registra el ID del evento para no procesarlo dos veces y se responde 200. Quien procesa llama averify(), que relee el estado de la pasarela. Los eventos llegan desordenados, y si el webhook no llega basta una pasada de conciliación que relea los cobros pendientes para que las cuentas cuadren. La recepción sigue el patrón de 03 §2. - Las claves están en el área Servicios, servicio
payment.stripe(conf/gallery/services/payment.stripe/):code(publicablepk_…),api_key(secretask_…),webhook_secret(whsec_…),currency(vacío =eur). El servicio no inyecta nada en la página. Fuera del CMS (cron desde la línea de comandos) o con el servicio apagado, el driver recurre a las constantesSTRIPE_PUBLIC,STRIPE_SECRET,STRIPE_WEBHOOK_SECRET,STRIPE_CURRENCY. - El entorno lo dice la clave: solo
sk_live_/rk_live_cobran dinero real (ambiente()respondelive,testoignoto). Si se olvida cambiar la clave, se sigue en pruebas. - Las fechas pasan por la zona horaria del sitio:
Payment::fuso()usaTIMEZONE(la escribe el instalador en el config), si no la zona horaria de PHP, y ante un valor no válido recurre a UTC en lugar de detener el cobro. Un driver nuevo convierte las fechas desde ahí, no desde una constante propia. - Productos, créditos, recibos y el registro de cobros no están en el hub: son del módulo del sitio.
⚠️ El driver de Stripe viene de GDay, donde está en producción; en el repositorio base no hay ningún proyecto que lo use.
3. Servicios de terceros
Un "servicio" es un tag de terceros configurable desde el backend. Estructura:
conf/gallery/services/<nombre>/
├── config/index.php define los campos configurables (enable, code, …)
└── index.php inyecta el tag en tiempo de ejecución
config/index.php declara los tipos de los campos y delega en system_services_modify(), que construye la pantalla de configuración:
$type_field["enable"] = "Boolean";
$type_field["code"] = "String";
system_services_modify(basename(ffCommon_dirname(ffCommon_dirname(__FILE__))), $type_field);
index.php lee los valores ($actual_srv) e inyecta:
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);
}
Los valores viven en cm_mod_security_domains_fields — (field, group, value) con group = nombre del servicio — y escriben allí tanto el área Servicios del backend como el asistente de instalación. Los cargan get_webservices() / process_webservices() (library/gallery/common/get_webservices.php).
Los servicios disponibles
| Categoría | Servicios |
|---|---|
| Analytics | analytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google |
| Marketing | linkedin.pixel, mailchimp, share.addthis, notification.optinmonster |
| Mapas y datos | google.maps, google.docs.auth, directory, place |
| Fuentes e iconos | font.google, font.google2, font.typekit, fontawesome |
| Meta y PWA | meta.favicon, meta.themecolor, meta.viewport |
| Notificaciones | notification.onesignal, sms.joesmtp, sms.twilio (06) |
| Pagos | payment.stripe (§2, solo credenciales: no inyecta nada) |
| Rendimiento | lazyload, modernizr, debounce |
| Contenidos/herramientas | admin.tools, company.data, courtesy.page, img.aviary, facebook |
| Privacidad | cookie.consent |
Añadir un servicio
conf/gallery/services/<nombre>/config/index.phpcon los campos;conf/gallery/services/<nombre>/index.phpcon la inyección;- la plantilla del tag en
themes/<tema>/services/<nombre>.html; - si es un tracker: declarar la categoría de consentimiento (§4).
4. Consentimiento de cookies: bloqueo real, en el servidor
El banner es el servicio cookie.consent (cookie jc_consent). La parte que cuenta es, sin embargo, del lado del servidor: antes de inyectar un servicio, process_webservices() llama a jc_consent_blocks($service_name) (en hook.php) y bloquea la categoría no consentida.
jc_consent_category($service_name) // a qué categoría pertenece el servicio
jc_consent_active() // ¿el banner está activo?
jc_consent_granted($categoria) // ¿el usuario ha dado su consentimiento?
jc_consent_blocks($service_name) // → true: el tag NO se inyecta
Dos propiedades buscadas:
- Es un bloqueo real: el tag no llega a la página, no se oculta en el cliente.
- Es opt-in: si el banner no está activo, no se bloquea nada. Los sitios existentes no cambian de comportamiento cuando se actualiza el CMS.
El banner es themes/gallery/contents/services/cookie.consent.html, generado por conf/gallery/services/cookie.consent/index.php. Sus textos son códigos del diccionario (svc_cookie_*, en los cuatro idiomas); el enlace a la política de privacidad, si en las opciones del servicio no se ha puesto uno, es /privacy en el idioma de la página (content_i18n_url()). Hasta la 3.0.3 estaban fijos en italiano, y el CSS en línea perdía tres reglas: {margin-left:auto}, {flex:1} y {text-decoration:underline} son llaves con un único par parola:parola, que el motor de plantillas toma por variables y borra. Las reglas siguientes se fundían con el selector que se quedaba sin bloque, y el panel «Personalizza» (Personalizar) quedaba siempre abierto. En el CSS de una plantilla cada regla cierra su última declaración con ;.
5. Otras librerías disponibles
library/ contiene dependencias listas para usar, de calidad y actualidad muy distintas. Las útiles:
| Librería | Uso |
|---|---|
phpmailer | envío SMTP: PHPMailer 7.1.1, con los adaptadores de la 5.2 (06 §2) |
sentry | seguimiento de errores (13) |
html2pdf, PHPexcel | generación de PDF y Excel |
mobiledetect, browser | detección de dispositivo |
minify, gminify, cssmin, jsmin | pipeline de recursos |
imap, vcard | correo entrante, contactos |
BunnyCDN | CDN |
algoliasearch-client | búsqueda externa |
SEOstats | métricas SEO (antigua) |
rabbitMQ | broker de colas, no conectado (05 §4) |
facebook-php-sdk, mailchimp, PayPal, OAuth2 | integraciones |
Y en 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.
⚠️ Muchas de estas librerías están paradas en versiones viejas y se vieron afectadas por la migración a PHP 8. Antes de usar una en una ruta crítica, verificarla:
MIGRAZIONE_PHP7_PHP8.mdcuenta también los daños que un viejosedmasivo había dejado enPHPExcel,TCPDFySEOstats.