Skip to content

Modular PHP Framework: How 2 MB Carries 5 Layers

5 min read Notes

Modular PHP Framework: How 2 MB Carries 5 Layers

A modular php framework is measured by what it assembles before the first line of application code runs. Atomic Framework answers with a bootstrap call, a provider list, routes split by request type and about 2 MB of core. The five layers below are the order in which a request meets them.

Code: Atomic-Framework, GPL-3.0-or-later.

The base is Fat-Free Framework, the ORM comes from cortex-atomic, and the WebSocket server runs on Workerman. PHP 8.1 or newer, version v0.1.4, 1481 tests in 70+ classes.

Layer 1: the bootstrap and the provider list

return \Engine\Atomic\Core\Bootstrap::boot();

bootstrap/app.php stays thin. Anything application-specific lives in a service provider, and providers listed in config/providers.php register before the framework lifecycle starts. A team that needs its hooks registered first gets them without editing the entry point, which is the difference between an upgrade that merges and an upgrade that fights.

Layer 2: routes split by request type

Four files, loaded by context rather than by a single router definition: routes/web.php and routes/web.error.php for HTML, routes/api.php, routes/cli.php, routes/telemetry.php. A CLI command never registers an HTTP route, and the error route does not load for an API call.

Middleware is named in config/middleware.php and attached to a route pattern:

return [
    'auth'  => App\Http\Middleware\Authenticate::class,
    'admin' => App\Http\Middleware\RequireAdmin::class,
];

$this->route('GET /admin/*', 'AdminController->index', ['auth', 'admin']);

A middleware implements MiddlewareInterface with handle() for the decision and process() for the response, so a rejected request returns a Response with a 401 instead of throwing into a log nobody reads.

Layer 3: a queue with two drivers

Manager::instance()->push('email', [
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
]);

Redis runs the atomic queue operations as Lua scripts, which keeps them atomic when two workers pull at once. The database driver uses row-level locks instead, so a project without Redis still gets a queue. Retry, TTL and a monitor work on both, and php atomic queue/worker, queue/monitor, queue/retry cover the operation side.

Layer 4: the scheduler and the cache

$scheduler->call(function () {
    Log::info('Cleanup executed');
})->daily()->at('03:00')->timezone('UTC');

The cron parser handles POSIX expressions, the timezone travels with the task, and a task that runs past 300 seconds is stopped. schedule/run executes what is due, schedule/work keeps the loop alive, schedule/list shows what is registered.

The cache has four drivers behind one interface: Redis, Memcached, database, folder. CacheManager::instance()->cascade() walks them in order, and a namespace invalidation clears a family of keys in one call. Transient adds WordPress-like storage on top. One method exists for a reason worth naming: flush_local_cache() refreshes the generation inside a long-running worker. Without it a worker answers from a cache that was invalidated hours ago, and that failure looks like random stale data until someone reads the worker code.

Layer 5: hooks, plugins and i18n

Event::instance()->on('user.created', $handler, priority: 10) dispatches hierarchically. Next to it sits a hook layer compatible with WordPress, with add_action and apply_filters, so a plugin written for a WordPress habit still reads correctly.

Plugins are explicit providers: only classes listed in config/providers.php load, each with its own composer.json and route file, and php atomic plugin/deps install checks dependencies. Nothing is discovered by scanning a folder, and that is a deliberate trade against a plugin that loads because it happens to be on disk.

i18n resolves the language in a fixed order: URL prefix, GET parameter, cookie, session, Accept-Language, default. It generates hreflang for the localized URLs, which is the part a hand-built multilingual site usually gets wrong.

What the tests cover

composer test runs 1481 tests in 70+ classes with 0 failures. 218 are skipped because Redis, Memcached and pcntl are unavailable on Windows. composer test-fw limits the run to the framework, composer test-integration to integration, and --filter "Auth" narrows it to one group while a change is being made.

Where the edges are

There is no admin generator and no page builder. Migrations are timestamped files with batches and rollback, not a schema diff, so a column rename is written by hand. The licence is GPL-3.0-or-later, which matters for a closed product before it matters for a client site. The core trades breadth for size: about 2 MB against roughly 30 MB for a full-stack framework with the same kind of tooling.

Four commands to a running app

composer create-project globus-studio/atomic-framework-application myapp
cd myapp
cp .env.example .env
php atomic init/key

php atomic health checks extensions and configuration, php atomic routes prints every registered route, php atomic version confirms what is installed.

Related: pcre router for the micro framework that dispatches all routes with one preg_match, and mcp server in php for exposing tools over JSON-RPC without a framework at all.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation