Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 10

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óduloContenido
authlogin, registro, recuperación, activación, social (08)
restrictedel backend: ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1
cms-commonel módulo de proyecto: la regla /srv/(.*) → /applets/services/$1 y models/Sitemap.php
securitycontenidos del módulo de seguridad
package-managergestió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.php es 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-common es 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 de Auth::addEvent(), un helper) está hook.local.php, junto a hook.php: hook.php lo 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:

  1. Validación de seguridad: comprobación del archivo ZIP con bloqueo de rutas peligrosas (path traversal ../ o absolutas).
  2. Lectura del descriptor manifest.json: metadatos del módulo, versión mínima de JoeCMS requerida, dependencias.
  3. Extracción selectiva: descomprime los componentes en sus respectivas carpetas (modules/<id>/, contents/, themes/).
  4. 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.
  5. 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:

PrefijoArchivo 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óduloQué hace
formconstructor 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)
searchbúsqueda en los contenidos, con configuración, grupos, extras y vista previa
newslettersuscripciones y envíos
calendareventos de calendario
mapsmapas
sharecompartir en redes sociales
tagcloudnube de etiquetas
videobar, fbalbum, swfmedios y galerías (componentes antiguos)
registerregistro
shippingpricegastos 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 a verify(), 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 (publicable pk_…), api_key (secreta sk_…), 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 constantes STRIPE_PUBLIC, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET, STRIPE_CURRENCY.
  • El entorno lo dice la clave: solo sk_live_ / rk_live_ cobran dinero real (ambiente() responde live, test o ignoto). Si se olvida cambiar la clave, se sigue en pruebas.
  • Las fechas pasan por la zona horaria del sitio: Payment::fuso() usa TIMEZONE (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íaServicios
Analyticsanalytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google
Marketinglinkedin.pixel, mailchimp, share.addthis, notification.optinmonster
Mapas y datosgoogle.maps, google.docs.auth, directory, place
Fuentes e iconosfont.google, font.google2, font.typekit, fontawesome
Meta y PWAmeta.favicon, meta.themecolor, meta.viewport
Notificacionesnotification.onesignal, sms.joesmtp, sms.twilio (06)
Pagospayment.stripe (§2, solo credenciales: no inyecta nada)
Rendimientolazyload, modernizr, debounce
Contenidos/herramientasadmin.tools, company.data, courtesy.page, img.aviary, facebook
Privacidadcookie.consent

Añadir un servicio

  1. conf/gallery/services/<nombre>/config/index.php con los campos;
  2. conf/gallery/services/<nombre>/index.php con la inyección;
  3. la plantilla del tag en themes/<tema>/services/<nombre>.html;
  4. 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íaUso
phpmailerenvío SMTP: PHPMailer 7.1.1, con los adaptadores de la 5.2 (06 §2)
sentryseguimiento de errores (13)
html2pdf, PHPexcelgeneración de PDF y Excel
mobiledetect, browserdetección de dispositivo
minify, gminify, cssmin, jsminpipeline de recursos
imap, vcardcorreo entrante, contactos
BunnyCDNCDN
algoliasearch-clientbúsqueda externa
SEOstatsmétricas SEO (antigua)
rabbitMQbroker de colas, no conectado (05 §4)
facebook-php-sdk, mailchimp, PayPal, OAuth2integraciones

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.md cuenta también los daños que un viejo sed masivo había dejado en PHPExcel, TCPDF y SEOstats.