Index and capability map
This manual documents the system's capabilities: not the project's history (that's in
PANORAMICA_JOECMS.md) nor individual fixes (FIX_FUNZIONAMENTO.md), but what can be built on top of this CMS and how it's done.Part of the knowledge collected here comes from sister projects built on the same stack (JoeSING, JoeQUIZ, JoeSMTP): general mechanisms the CMS offers that until now were documented only in the project that used them first.
The chapters
| # | Document | Content |
|---|---|---|
| 01 | Request lifecycle and routing | bootstrap, three-level routing, reserved paths, router walk-up, $schema["request"] |
| 02 | Pages, templates and applets | contents/, ffTemplate and block markers, applets, layout, CSS/JS |
| 03 | HTTP services and webhooks | /srv, JSON contract, service bus, Jobs, receiving webhooks |
| 04 | Internal and public API | internal REST, api/1.0 with Bearer, contract conventions, pitfalls |
| 05 | Cron, jobs and workers | HTTP cron, job queue, CLI worker, maintenance |
| 06 | Email, notifications, SMS and push | process_mail, Mailer, Notifier, OneSignal, JoeSMTP, Twilio |
| 07 | Data, database and content | ffDB_Sql and its four pitfalls, Storage, vgallery model, migrations |
| 08 | Authentication, users and permissions | auth module, session, profiles, ACL, cookies |
| 09 | Backend and sections | ffGrid/ffRecord, adding a section, popups and toolbar |
| 10 | Modules and third-party services | structure of a module, functional modules, third-party tags, cookie consent |
| 11 | Media, images and files | showfiles, image modes, uploads, file manager |
| 12 | Cache and performance | the four caches, levels, invalidation, what to watch |
| 13 | Observability, diagnostics and CLI | error handling, ?__debug__, logs, Sentry, command-line execution |
| 14 | Environments, installation and deploy | environment config, wizard, deploying the active branch with bin/deploy.sh, package (with the manual as a snapshot), checklist, automatic manual updates |
Capability map
Legend: ✅ in production · 🟡 present, to configure or test · ⚪ upstream scaffolding, verify before relying on it.
| Capability | Status | Where |
|---|---|---|
| Dynamic pages without registration (file → URL) | ✅ | 02 |
| Token and block templates, multilingual from dictionary | ✅ | 02 |
| Declarative XML routing + modules | ✅ | 01 |
| Node-based content model with dynamic fields | ✅ | 07 |
| Backend with grids and forms generated from the DB | ✅ | 09 |
| Accounts: login, registration, recovery, activation | ✅ | 08 |
| Groups, profiles, per-node permissions with inheritance | ✅ | 08 |
Project JSON endpoints (/srv) | ✅ | 03 |
| Public API with client credentials → Bearer | ✅ (auth only) | 04 |
| Transactional email with templates and attachments | ✅ | 06 |
| Preferred language on the profile: pages, emails and notifications in the user's language, even from cron | ✅ | 12, 06 §2 |
| On-the-fly image resizing with cache | ✅ | 11 |
| Page cache per user/group/anonymous and per language | ✅ | 12 |
| Configurable third-party services + server-side cookie consent | ✅ | 10 |
Sitemap (one entry per language, with hreflang) and Markdown version for LLMs | ✅ | GUIDA_SITEMAP.md, GUIDA_INDICIZZAZIONE_AI.md, 12 §2 |
| Error tracking (Sentry) | ✅ (needs DSN) | 13 |
| Schedulable HTTP cron | 🟡 (schema ready, no jobs in the base repo) | 05 |
| Receiving webhooks from providers | 🟡 (pattern, not instances) | 03 §2 |
| In-app notifications with scheduling and expiry | 🟡 | 06 §3 |
| Push (OneSignal) and SMS (JoeSMTP, Twilio) | 🟡 (ready, keys needed) | 06 §4 |
| Second factor at login | 🟡 (off, AUTH_2FA) | 08 §5bis |
Persistent job queue (Jobs) and async calls | 🟡 | 05 §4 |
| Long-running CLI worker | 🟡 (needs shell + systemd) | 05 §5 |
| Backend form builder with response archive | 🟡 | 10 §2 |
| Content search | 🟡 | 10 §2 |
| Multi-driver storage (MySQL, MongoDB, file) | 🟡 | 07 §2 |
| Application cache on Redis/Memcached/APCu | 🟡 | 12 §4 |
| Import/export, backup, schema cloning | ⚪ | 07 §5 |
| Payments with driver-based gateways (Stripe: one-off, subscriptions, refunds, webhooks) | 🟡 (keys needed) | 10 §2 |
| E-commerce (cart, wishlist, payments) | ⚪ | 10 §2 |
| OAuth2 server / apiserver | ⚪ (routes present, folders missing) | 08 §1 |
| Queue broker (RabbitMQ) | ⚪ (library present, not wired) | 05 §4 |
| Remote updater | ⚪ (retired, made inert) | 05 §3 |
Non-negotiable rules
A summary of the pitfalls that have already caused damage in the ecosystem. Details are in the chapters.
<!--BeginX-->/<!--EndX-->markers are not comments. No spaces, no removals, no reordering. → 02 §2.2use_cache(false)at the top of every service and every dynamic page. → 12exitat the end of every JSON endpoint, otherwise the CMS appends the layout. → 03 §1execute()to write,query()to read: afterquery(),getInsertID()lies. → 07 §1.1- Query-string parameters must be declared in
$schema["request"], or the kernel discards them with a silent redirect. → 01 §5 - The router doesn't answer 404: it walks up. A guard on the path residue is needed. → 01 §4
- Session cookie parameters must be set before
session_start(), in a single place. → 08 §6 Auth::env()andCms::env()read different buckets. → 08 §4- The tenant/owner never comes from the body. → 03, 04
- Every migration also goes into
database.sql, withJC_SCHEMA_VERSIONbumped, and the release declares it in the CHANGELOG (· schema **N**,### Schema): that is how joecms.it knows whether to warn about updating the database. → 07 §4, 14 §5 display_errorsstays at 0; debugging is on demand with?__debug__. → 13- Lint after every mass change. → 13 §8
- The logo in emails is a PNG, never an SVG. By default it travels as an absolute URL, no longer as a
cid:attachment: some relays reject the whole message if it contains an attachment part. → 06 §2 JC_APP_SECRETis never regenerated: it goes into the backup. → 14 §2- A code sent by email never comes back in the response to the browser (activation, 2FA, recovery): it's the secret that proves access to the mailbox. → 08 §5
- A return address taken from the URL is only a path of the site: it goes through
Auth::redirectLocale(), or it's an open redirect. → 08 §5 - The server's
sql_modeis not relaxed: you fix the query or the schema. The code runs on the strict defaults of MySQL 8 and MariaDB and on Aiven'sANSIdialect. → 07 §1 - A text the visitor sees is never written in a single language: the dictionary in templates,
Auth::text()in account messages, per-language tables where there is no database. → 02 §2.3
Related documents
| File | Content |
|---|---|
../../PANORAMICA_JOECMS.md | architecture and history of decisions |
../../PRESENTAZIONE_JOECMS.md | non-technical presentation |
../../FIX_FUNZIONAMENTO.md | fixes that change behaviour |
../../MIGLIORIE_ESTETICHE.md | CSS/UI-only changes |
../../MIGRAZIONE_PHP7_PHP8.md | migration to PHP 8 |
../../INSTALLER_PIANO.md | detailed installer plan |
../../VGALLERY_NEXT_PIANO.md | new content management area |
../../IGIENE_SEGRETI.md | secrets management |
../../GUIDA_INDICIZZAZIONE_AI.md, ../../GUIDA_SITEMAP.md | reusable defaults |
../api-auth.md | operational reference for the public API |
../documentazione/cms-ricetta-portabile.md | the working recipe on the stack (from JoeSMTP) |
../documentazione/joesing-convenzioni.md | conventions and pitfalls (from JoeSING) |