Addons
How addons are discovered, loaded, mounted and wired into the app.
On this page
What an addon is
A self-contained folder of PHP that can register services, listen to lifecycle events, and offer fields, views, routers and controllers, without changing framework code. The built-in dash is the largest example; clockwork (the profiler) is the simplest.
Where addons live
| Location | Id | Notes |
|---|---|---|
phlat/addons/{name}/ |
phlat/{name} |
Framework built-ins |
site/addons/{name}/ |
site/{name} |
Site-specific |
addons/{creator}/{name}/ at the project root |
{creator}/{name} |
Installed, each a pinned git submodule |
Enabling an addon
App::boot() loads every addon that has an addons.{id} config entry with enabled not false. The entry also holds the addon's settings, read with $app->addonConfig('phlat/dash', 'open') ({addon('phlat/dash', 'open')} in Latte):
{
"addons": {
"phlat/clockwork": { "mount": "clockwork" },
"site/newsletter": { "enabled": true }
}
}
An addon's alias is the last segment of its id (phlat/dash is dash). It is the only name used in @alias/view refs, {include '@alias/...'}, find('view=@alias/...'), event names (@alias/order.create:after) and page refs (p('@alias')). @phlat is the core's folder, so no addon may take that alias. Two addons with the same alias are a hard error at load.
index.php
If the addon folder has an index.php, it is included once per boot with $app and the addon's $path injected. Other files are not auto-loaded; require them from here.
<?php
// site/addons/newsletter/index.php
use Phlat\App;
use Phlat\Page;
// Defer anything session, registry or request-specific to a hook
$app->on('app.route:after', function (Page $page) use ($app) {
if ($app->session->isLoggedIn())
return;
(new NewsletterService($app))->trackVisit($page);
});
Events
$app->on($event, $handler) observes the request lifecycle. Hooks are observational only: return values are ignored, and a hook that wants to stop a request redirects or throws. See Event Hooks for the list.
Views and mounting
An addon offers views the same way the site does: views/{name}/ with its own router.php and controller.php.
An addon cannot add pages to the site by itself. One that ships a pages/ tree is served only when you mount it by creating a page, at any slug, whose view is the addon's:
// site/pages/admin/_index.json
{
"uuid": "<generated uuid>",
"view": "@dash",
"published": true
}
Create it in the dash or with phlat make:page. That page is the addon's home in the site: its settings are ordinary fields, with the page tree, permissions and history.
An addon whose index.json says "automount": true needs none of this. It is served from its own pages/ at /@{alias}, read-only, with no page in site/pages/ and no registry row. It keeps its settings in its addons.{id} config entry, and the addon owns every URL under /@{alias}. Icons, fonts and Clockwork are automounted; the dash and theme editor are mounted because they have fields to edit.
No I/O at the top level of index.php
index.php runs during addon loading, inside every request's critical path. Calls that do I/O, like $app->session or $app->registry(), belong in an $app->on(...) callback, so they run after the addons have loaded, with the request's context.
Reading $app->session at the top level of index.php calls session_start(), which takes a file lock, so concurrent requests queue behind it on every page.
// Wrong: runs while addons load, before the page is resolved
$loggedIn = $app->session->isLoggedIn();
// Right: runs once the page is routed, with that request's session
$app->on('app.route:after', function () use ($app) {
$loggedIn = $app->session->isLoggedIn();
});
Clockwork
Request profiling in the browser devtools while debug is on.
Dash
The editing interface, mounted as ordinary pages.
Fonts
Self-hosted web fonts, chosen by name in a theme.
Icons
The Lucide icon set behind one template tag and one cached sprite.
CLI
The phlat command line tool for scaffolding, maintenance and the registry.
OIDC
Sign in with any OpenID Connect provider, as a button on the login card.
TOTP
Two-factor sign-in with an authenticator app, with recovery codes and a reset for a lost device.