Skip to content
JoeCMS Download 3.1.5
Manual · 10

Modules and third-party services

Two extension mechanisms, with similar names and different purposes: modules add code, routes and pages; services inject third-party tags (analytics, maps, fonts, pixels) configurable from the backend without touching code.

1. Modules: project code outside hook.php

Every folder inside /modules is loaded automatically. The typical structure:

modules/<name>/
├── common.php               module functions (loaded by the CMS)
├── autoload.php             own autoloader (optional)
├── events.php               hooks into page-cycle events (optional)
├── conf/
│   ├── routing_table.xml    module routes   → loaded automatically
│   └── mod_restricted.xml   backend entries
├── models/                  module classes
├── contents/                module pages
├── library/
│   ├── job/<name>.php       job_<name>() functions      (check_function("job_..."))
│   └── system/<name>.php    system_<name>() functions   (check_function("system_..."))
└── themes/                  module CSS/JS/templates

Modules in the repo:

ModuleContents
authlogin, registration, recovery, activation, social (08)
restrictedthe backend: ^/restricted(.*) → /layout$0, ^/admin/settings(.*) → /settings$1
cms-commonthe project module: the /srv/(.*) → /applets/services/$1 rule and models/Sitemap.php
securitysecurity module content
package-managermodule and extension management (.zip): WordPress-style upload, auto DB migration and wizard

Where to put a new project's code: in a module, not in hook.php. hook.php is platform code (~1,900 lines of legacy helpers) and updates replace it: a project line written there disappears with the next version. A module has its own autoload, loads itself, and can be moved to another project by copying a folder. modules/cms-common is the right place for what's common, a dedicated module for what belongs to the product. For a few lines (an Auth::addEvent() listener, a helper) there is hook.local.php, next to hook.php: hook.php includes it at the end, it is not in the package and updates never touch it. A value to change (domain, AREA_*, MAX_UPLOAD) goes in the config instead.

⚠️ A module's conf/schema.php isn't read. Only library/gallery/settings.php (core) and themes/<theme>/settings.php (project) are loaded. modules/cms-common/conf/schema.php exists and is dead code: $schema["request"] and $schema["page"] declarations go in the theme (see 01 §5).

Package Manager: ZIP module installation and DB auto-migration

The package-manager module (/admin/pacchetti) provides the JoeCMS backend with an area to upload ZIP archives containing modules and extensions, managing their full lifecycle:

  1. Security validation: verifies the ZIP file and blocks unsafe paths (path traversal ../ or absolute paths).
  2. Reading the manifest.json descriptor: module metadata, minimum required JoeCMS version, dependencies.
  3. Selective extraction: extracts components into their respective folders (modules/<id>/, contents/, themes/).
  4. Automatic database update: if the manifest specifies database.schema, automatically runs the DDL SQL using the active connection.
  5. Post-installation Setup Wizard: optionally redirects to the configuration wizard for paths and module parameters.

Autoload by convention

check_function() in library/gallery/common.php loads the right file from the function name:

PrefixFile searched
job_<x>modules/<mod>/library/job/<x>.php, then library/gallery/job/<x>.php
system_<x>modules/<mod>/library/system/<x>.php, then library/gallery/system/<x>.php
mod_<mod>_<x>modules/<mod>/events.php

That's why the code is full of if (check_function("system_something")) { … }: the file is included only when needed.

2. The CMS's functional modules

conf/gallery/modules/ contains complete subsystems, each with configuration and management in the backend:

ModuleWhat it does
formform builder: field definitions from the backend, selections, price lists, email sending with templates, revisions, archive of submissions (manage/, detail.php)
searchcontent search, with configuration, groups, extras and preview
newslettersubscriptions and sends
calendarcalendar events
mapsmaps
sharesocial sharing
tagcloudtag cloud
videobar, fbalbum, swfmedia and galleries (dated components)
registerregistration
shippingpriceshipping costs (e-commerce)

The form module is the one that most often saves work: a contact form, a quote request, a questionnaire are configured from the backend — fields, validation, notification emails, list of responses — without writing a page.

E-commerce

There's scaffolding: routes /user/cart, /user/wishlist, /user/manage, /user/mpay, library/gallery/ecommerce/product_process.php, conf/gallery/manage/ with operations and payments, the reset_carts job, library/PayPal/, and the related tables in the seed.

⚠️ It's upstream code not tested in this prototype. Treat it as a starting point to verify, not as a ready feature.

Payments: the Payment hub

Independent of the scaffolding above: it's where a project takes payments without writing its own integration. library/payment/Payment.php declares what taking a payment means, gateways are drivers in library/payment/services/<name>.php (class payment<Name>), and the hub loads them by itself: the autoloaders have a single case, Payment, both the root autoload.php (included by the API) and vendor/wolfgan/autoload.php, the one index.php loads via Composer. Up to 1.6.2 the second one didn't have it, and from the site checkout, webhooks and payment cron jobs died with "Class Payment not found".

$esito = Payment::gateway()->checkout(array(
    "riferimento"  => "acquisto:1234",   // your own ID, not the gateway's
    "descrizione"  => "10-lesson pack",
    "importo_cent" => 18000,             // always integer cents, never floats
    "email"        => "anna@example.com",
    "ritorno_ok"   => "https://site/area/purchase?esito=ok",
    "ritorno_ko"   => "https://site/area/purchase?esito=annullato",
));
// array(ok, id, url, error): send the person to url

Every driver exposes checkout() (one-off), subscribe() (recurring), verify() and subscriptionVerify() (actual status), subscriptionCancel(), refund(), webhookVerify(). verify() always answers in the same shape, with a normalized status: pagato, in_attesa, fallito, rimborsato, annullato (constants Payment::PAGATO and following). The gateway is chosen with Payment::gateway('<name>'), or with the PAYMENT_GATEWAY constant; the default is stripe.

  • The webhook triggers, the truth is read back. Nothing in a webhook's body is applied: the signature is verified (webhookVerify()), the event ID is recorded so it isn't processed twice, and the reply is 200. Whoever processes it calls verify(), which reads the status back from the gateway. Events arrive out of order, and if the webhook never arrives, a reconciliation pass that rereads pending payments is enough to balance the books. Receiving follows the pattern in 03 §2.
  • Keys live in the Services area, service payment.stripe (conf/gallery/services/payment.stripe/): code (publishable pk_…), api_key (secret sk_…), webhook_secret (whsec_…), currency (empty = eur). The service injects nothing into the page. Outside the CMS (command-line cron) or with the service off, the driver falls back to the constants STRIPE_PUBLIC, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET, STRIPE_CURRENCY.
  • The key tells the environment: only sk_live_ / rk_live_ take real money (ambiente() answers live, test or ignoto). If you forget to change the key, you stay in test mode.
  • Dates go through the site's time zone: Payment::fuso() uses TIMEZONE (written into the config by the installer), otherwise PHP's time zone, and on an invalid value falls back to UTC instead of stopping the payment. A new driver converts dates from there, not from a constant of its own.
  • Products, credits, receipts and the payments ledger are not in the hub: they belong to the site's module.

⚠️ The Stripe driver comes from GDay, where it is in production; the base repository has no project that uses it.

3. Third-party services

A "service" is a third-party tag configurable from the backend. Structure:

conf/gallery/services/<name>/
├── config/index.php     defines the configurable fields  (enable, code, …)
└── index.php            injects the tag at runtime

config/index.php declares the field types and delegates to system_services_modify(), which builds the configuration screen:

$type_field["enable"] = "Boolean";
$type_field["code"]   = "String";
system_services_modify(basename(ffCommon_dirname(ffCommon_dirname(__FILE__))), $type_field);

index.php reads the values ($actual_srv) and injects:

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);
}

The values live in cm_mod_security_domains_fields — (field, group, value) with group = service name — and both the backend's Services area and the installation wizard write there. They're loaded by get_webservices() / process_webservices() (library/gallery/common/get_webservices.php).

Available services

CategoryServices
Analyticsanalytics.google, google.tagmanager, analytics.clarity, analytics.contentsquare, webmaster.google
Marketinglinkedin.pixel, mailchimp, share.addthis, notification.optinmonster
Maps and datagoogle.maps, google.docs.auth, directory, place
Fonts and iconsfont.google, font.google2, font.typekit, fontawesome
Meta and PWAmeta.favicon, meta.themecolor, meta.viewport
Notificationsnotification.onesignal, sms.joesmtp, sms.twilio (06)
Paymentspayment.stripe (§2, credentials only: injects nothing)
Performancelazyload, modernizr, debounce
Content/toolsadmin.tools, company.data, courtesy.page, img.aviary, facebook
Privacycookie.consent

Adding a service

  1. conf/gallery/services/<name>/config/index.php with the fields;
  2. conf/gallery/services/<name>/index.php with the injection;
  3. the tag template in themes/<theme>/services/<name>.html;
  4. if it's a tracker: declare the consent category (§4).

The banner is the cookie.consent service (cookie jc_consent). But the part that counts is server-side: before injecting a service, process_webservices() calls jc_consent_blocks($service_name) (in hook.php) and blocks the category not consented to.

jc_consent_category($service_name)   // which category the service belongs to
jc_consent_active()                  // is the banner active?
jc_consent_granted($categoria)       // did the user consent?
jc_consent_blocks($service_name)     // → true: the tag is NOT injected

Two intended properties:

  • It's a real block: the tag doesn't reach the page at all, it isn't hidden client-side.
  • It's opt-in: if the banner isn't active, nothing is blocked. Existing sites don't change behaviour when the CMS is updated.

The banner is themes/gallery/contents/services/cookie.consent.html, rendered by conf/gallery/services/cookie.consent/index.php. Its texts are dictionary codes (svc_cookie_*, in the four languages); the privacy policy link, if none was set in the service options, is /privacy in the page's language (content_i18n_url()). Up to 3.0.3 they were hard-coded in Italian, and the inline CSS lost three rules: {margin-left:auto}, {flex:1} and {text-decoration:underline} are braces holding a single parola:parola pair, which the template engine takes for variables and deletes. The rules that followed merged with the selector left without a block, and the "Personalizza" (Customize) panel stayed always open. In a template's CSS every rule ends its last declaration with ;.

5. Other available libraries

library/ contains ready-to-use dependencies, of very different quality and freshness. The useful ones:

LibraryUse
phpmailerSMTP sending: PHPMailer 7.1.1, with the 5.2 adapters (06 §2)
sentryerror tracking (13)
html2pdf, PHPexcelPDF and Excel generation
mobiledetect, browserdevice detection
minify, gminify, cssmin, jsminasset pipeline
imap, vcardincoming mail, contacts
BunnyCDNCDN
algoliasearch-clientexternal search
SEOstatsSEO metrics (dated)
rabbitMQqueue broker, not wired (05 §4)
facebook-php-sdk, mailchimp, PayPal, OAuth2integrations

And in 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.

⚠️ Many of these libraries are stuck at old versions and were touched by the migration to PHP 8. Before using one on a critical path, verify it: MIGRAZIONE_PHP7_PHP8.md also recounts the damage an old mass sed had left in PHPExcel, TCPDF and SEOstats.