Every custom application I quote starts with the same list: sign-in, a password reset, an email that must not hold up the response, a nightly export, an admin who needs to see the site as the customer sees it. A WordPress site has that list solved before the first call. A custom application pays for it again. Building a php framework was my way of refusing to invoice it a fourth time.
Code: Atomic-Framework, GPL-3.0-or-later.
Five decisions shaped what came out: about 2 MB of core with authentication, queues, a scheduler, caching, a command line and a plugin manager, 1481 tests in 70+ classes, no failures. Each one is a rule I would repeat on another project, and each one has a cost I accepted.
Decision 1: start from a small base that is already old
Fat-Free Framework is the base. It has been around long enough to have the boring parts settled, and it is small enough that a developer can read it. The ORM comes from the same family, the WebSocket server is Workerman, and PHP 8.1 is the floor.
The alternative was a full-stack framework with an ecosystem. Its cost is weight on every request, and about 30 MB of core where mine is about 2 MB. On a small server that difference is memory per request, which turns into the number of concurrent visitors a client can afford. On a large server it is a number in the bill. Neither is free.
Decision 2: two queue drivers, because hosting decides
Redis with Lua scripts keeps the atomic queue operations atomic when several workers pull at once. A database driver with row-level locks does the same job on MySQL, slower, with no extra service. A project can start on the second and move to the first without rewriting a job.
I chose two drivers because the decision about Redis belongs to the client and the hoster, not to me. A small business does not buy a Redis instance to send a welcome email. A shop with ten thousand orders a day should not run its queue in the same table it reads on every page.
Decision 3: hooks a WordPress developer reads with no manual
add_action and apply_filters work the way they work in WordPress, next to a hierarchical event dispatcher with priorities. A team that spends most of the year in themes and plugins can move to a custom application without a new mental model for the extension point.
That is also the cheapest way to reuse a habit. The rules a studio already has about hooks, priorities and late loading stay true, so code review conversations do not start from zero.
Decision 4: providers are listed, not discovered
Only classes named in config/providers.php load. A plugin ships its own composer.json and route file, and plugin/deps install checks dependencies. Nothing appears because it happens to be in a folder.
The trade is a line in a config file each time. In exchange, a deployment has a fixed list of what runs, a missing dependency fails at install time rather than at the first request, and a plugin cannot take over the application by being copied in.
Decision 5: the command line is the interface for people
45+ commands: init scaffolds, health checks the environment, routes prints what is registered, cache/* and queue/* operate state, migrations/* runs timestamped migrations with batches and rollback, plugin/* manages plugins.
A team hands over a system, not a set of screenshots. When someone has to restore a queue at 02:00, the command exists and is documented, and the alternative is reading the source at that hour.
What the test count does not tell you
1481 tests in 70+ classes with 0 failures is a good number to print and a poor reason to trust a repository. The 218 skipped tests say more: Redis, Memcached and pcntl are not available on Windows, so they are skipped there instead of failing. A suite that fails on a laptop teaches developers to ignore red. A suite that skips with a named reason keeps the signal.
What the number does not measure is the boundary. Nothing here generates an admin panel, builds pages or sells products. Migrations are timestamped files, so a schema change is written by hand. Every one of those gaps is a place where an application still needs a framework with more opinions, or a developer with a clear head.
The licence and the next developer
GPL-3.0-or-later. A client site lives inside it without friction. A closed product needs a legal review first, and I would rather say that in the meeting than discover it in a contract.
A framework is a bet on the next person who opens the repository. That is the reason for the plain structure, the named layers and the CLI, and it is the reason the readme spends as much space on limits as on features.
What I take from this to the next project
Pick the base by what the next developer can read, not by what the job board asks for. Count the layers a request touches before it reaches your code. Keep the queue portable so the hosting decision stays with the client. Write the command that will be needed at night before it is needed.
The same three habits run through the rest of my work: property hooks in PHP 8.5 stay readable only when the rule is written down, LLM work in PHP starts with the boundary of what runs locally, and progressive enhancement is the same argument about a page that must work without the script.
Atomic Framework and its skeleton are on GitHub, and the projects page lists what is built on them.