Éclair's architecture

The Éclair CMS architecture comes down to one rule: only make PHP work when it's needed. This lesson follows a request from end to end, from the web server to the static cache, shows how data is stored without a database and which class does what. You'll then be able to debug, customize or host Éclair knowing how it works inside.

How does a request travel through the Éclair CMS architecture?

It all starts from one observation: most visits ask for a page that hasn't changed. So the Éclair CMS architecture sends it back as is, without reading a single piece of content. Here is the path a request takes.

1. The web server. On Apache or LiteSpeed, .htaccess sends any URL that isn't an existing file to index.php. It returns a 404 for app/, data/, cache/, hidden files (except .well-known) and any .php file other than index.php, and passes the Authorization header on to the MCP connector.
2. The index.php fast path. For a GET or HEAD request, index.php reads cache/runtime.php, then looks for the page in cache/pages/ under the md5 of the path. If it finds it, it returns the page's saved headers, its ETag and X-Cache: HIT, or a 304 Not Modified if the browser already has this version.
3. Bootstrap. Otherwise, app/bootstrap.php checks the PHP version (8.1 at least), loads eclair-config.php if it exists, defines ECLAIR_DATA and ECLAIR_DEBUG, registers autoloading for the Eclair\… classes, then calls Eclair\App::run().
4. Routing. App::run() sets up error handling and hands the request to the right module (table below).
5. Rendering. Site::handle() only accepts GET and HEAD, enforces a single URL per piece of content (trailing slash, uppercase, index.php: 301 redirect), serves the generated files (robots.txt, sitemap.xml, llms.txt, feeds, .md versions), then looks up the content. A page rendered with a 200 status is saved by Cache::put().

Search, the 404 page, the appearance preview, Visual mode and the admin are never cached. To see the fast path at work, request the same page twice:

# 1st call: the application generates the page, then saves it
curl -sI https://exemple.fr/contact | grep -i -E 'etag|x-cache'
# ETag: "0745734655e7d523"

# 2nd call: served by index.php from cache/pages/, without loading the application
curl -sI https://exemple.fr/contact | grep -i -E 'etag|x-cache'
# ETag: "0745734655e7d523"
# X-Cache: HIT

# The cache file is named after the md5 of the requested path
php -r 'echo md5("/contact"), PHP_EOL;'   # 90609cfd31a32bdbd3d81843c57d356b

Flat-file storage: the Store class

The Éclair CMS architecture does without a database: each piece of data is a data/<name>.php file that starts with the line <?php exit; ?>, followed by readable JSON. Requested from the web, it returns nothing, even on a server that ignores .htaccess files. Here is the beginning of a real menus file:

<?php exit; ?>
{
    "main": [
        {
            "type": "content",
            "id": "af59e5ba0a",
            "label": "",
            "url": ""
        }
    ]
}

Four mechanisms keep this storage safe, even on a busy shared server:

• Atomic writes: Store::atomic() writes a temporary file, then renames it, so a reader never sees a half-written file. Files get 0600 permissions, and the folders in data/ and cache/ get 0700.
• No injectable code: Store::write() encodes the JSON with JSON_HEX_TAG and JSON_HEX_AMP. A < becomes <, so the <?php sequence can't appear in the data.
• Lock: Store::locked() takes an exclusive lock (flock) on data/.lock during every read-modify-write operation.
• Controlled names: Store::file() only accepts lowercase letters, numbers, hyphens and slashes. There's no way out of data/.

Every class that writes data follows this pattern, Redirects::add() for example:

use Eclair\Store;

$menus = Store::read('menus', []);           // read, with a default value
Store::locked(function (): void {            // read, modify, write with no race
    $list = Store::read('redirects', []);
    // … modify $list …
    Store::write('redirects', $list);        // temporary file, 0600, rename
});

The files in the data/ folder

The last column shows what the ZIP backup on the Security page keeps: secrets and short-lived data are left out.

Updates never touch data/, and the ECLAIR_DATA constant can even move it outside the public folder.

The main classes in app/lib/

All classes live in the Eclair\ namespace, one file per class, with no framework and no Composer:

Why does the cache clear on every change?

A changed title also appears in a menu, a post card and the breadcrumbs. Rather than guess these dependencies, the Éclair CMS architecture clears everything: Cache::purge() runs after every save of content, settings, menus, categories, media, a profile or the custom CSS. It deletes the files in cache/pages/ and rewrites cache/runtime.php; each page is regenerated on its first visit.

<?php exit; ?>
{"on":true,"expires":0,"host":"exemple.fr","https":true}

index.php reads this small file on every request:

• on: cache active (Static page cache checked, debug mode off);
• expires: the time of the next scheduled post, after which index.php ignores the cache and Cache::checkExpiry() clears it;
• host and https: the official host and protocol, once the address is verified, so that redirects are never bypassed.

Security headers and CSP

Security::headers() produces three sets of headers: site, admin and text (sitemap, llms.txt, feeds). They depend on the settings, never on the request, so nobody can poison the cache with a forged header. Here are the headers of a public page served over HTTP, recorded on Éclair 1.8:

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'sha256-…'; img-src 'self' data: https:; media-src 'self' https:; frame-src https://www.youtube-nocookie.com https://player.vimeo.com; connect-src 'self'; form-action 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=(), browsing-topics=()
Cross-Origin-Opener-Policy: same-origin

Theme::hash() computes the sha256 hash of the CSS inlined in the page: only that <style> tag is allowed, no inline script is permitted, and the only public script is assets/site/site.js. Over HTTPS, upgrade-insecure-requests is added, along with Strict-Transport-Security if the HSTS option is checked. The admin is stricter still: no inline styles, frame-ancestors 'none', noindex and Cache-Control: no-store, private.

Translations

• Admin: every string is written in French in the code, with t(). I18n::t() looks up its translation in app/lang/<lang>.json.gz, compiled by tools/i18n.php and indexed by the CRC32 hash of the French text. Without the zlib extension, the admin stays in French.
• Public site: Theme::t('key', $lang) reads the Theme::STRINGS array (“Contents”, “Key takeaways”, “Read in”…) in six languages, and Theme::words() gives the words used in URLs (page, author, search, shop) in the site's language.

Key points

• In the Éclair CMS architecture, a page already generated is served by index.php from cache/pages/ without loading the application: X-Cache: HIT proves it.
• Everything else goes through app/bootstrap.php, then App::run(), which routes to the installer, the admin, the contact form, MCP or the site.
• Data is stored as JSON files behind <?php exit; ?>, written atomically, with 0600 permissions and under a lock.
• The cache clears completely on every change and rebuilds itself on the next visit.
• Security headers depend only on the settings: the cache can't be poisoned.

Going further

• Local development and testing: run Éclair on your machine and replay its 550 checks.
• Customize the theme templates: change the rendering without breaking the CSP.
• Nginx, VPS, proxy and CDN: reproduce the .htaccess rules outside Apache.
• Advanced security and maintenance: integrity, backups and updates.
• PHP documentation: flock() and rename(), at the heart of how Store writes.
• OWASP: Content Security Policy Cheat Sheet.

All the lessons of this path