A modular PHP 8.4+ service framework built on the Gated Demand Architecture (GDA).
Security runs before any module loads, and only the modules a request actually needs are ever wired in.
It ships as a native cross-platform CLI (hkm) built with Zig, so you install and
upgrade it like a Go/Rust binary — no Composer needed to get started.
- Purpose
- What we're building toward
- Project status — done vs. cooking
- Why GDA?
- Performance — measured
- Install
- The
hkmCLI - Your first project
- Core concepts
- The request lifecycle
- Building a feature — end to end
- The five access rules
- Batteries included (plugins)
- Development from source
- Security defaults
- License
HKM Kernel exists to make secure, cost-predictable PHP services the default — not the reward for discipline.
Most PHP frameworks boot the whole application, wire every service, and then decide what the request needs. That is convenient, but it means an unauthenticated request that should cost nothing still pays to construct half your app, and domain boundaries live only in your head (and your code reviews).
HKM inverts that with the Gated Demand Architecture:
- Security is the gate, not a middleware afterthought. A
SecurityGatewayruns before any module is wired. A denied request costs zero module construction. - You pay only for what a route uses. Modules are resolved from a per-request dependency graph and wired on demand. Nothing you didn't ask for is loaded.
- Boundaries are enforced by the runtime, not by convention. Cross-layer and cross-module access rules throw real exceptions, not lint warnings.
The goal is a framework where the fast, secure, well-bounded way to build something is also the easy way — and where you can drop in a first-party plugin (auth, tenancy, mail, OAuth2) without inheriting a monolith.
This is not Laravel, Symfony, or Slim. It borrows none of their conventions — no globals, no facades, no runtime auto-discovery. Everything is explicit and injected.
The north-star goals that guide every decision in this repo:
| Goal | What it means |
|---|---|
| Zero-cost denial | A blocked request never constructs a module. Security is measured in the gateway, not the controller. |
| Per-request minimalism | The kernel wires exactly the modules a route needs — and their transitive dependencies — and nothing else. |
| Runtime-enforced isolation | One module, one domain. Modules cannot reach into each other's internals; the container throws if they try. |
| A dependency-free kernel | The core should carry no vendor coupling. Request/Response/uploads become pure value objects (see cooking, below). |
| Infrastructure independence | The kernel defines ports; the project supplies adapters (MySQL, Redis, S3, SMTP…). Swap them without touching domain code. |
| Install like a binary | hkm is a native cross-platform launcher — no Composer required to get started, upgradeable in place. |
| Batteries, not a monolith | Auth, Users, Tenancy, OAuth2, Mail, and more ship as opt-in first-party plugins, each owning exactly one domain. |
Where things stand today. HKM is under active development. The architecture and the core plugins are in daily use, and releases are cut regularly — but some subsystems are still stabilizing. This section is the honest map.
- The GDA kernel — boot pipeline (10 fail-fast stages), security gateway, on-demand module loader, request-scoped DI with runtime scope enforcement, HTTP / CLI / Worker pipelines, domain + integration event system, and the port interfaces.
- The five access rules, enforced at runtime via
ModuleContainer::bindInternal(). - Native distribution —
hkmlauncher +hkm-configbuilt with Zig;.deb, macOS.app, and Windows.zipbundles published automatically fromCHANGELOG.md. - First-party plugins (see the full table) — Auth, User, Tenancy, OAuth2, Validation, Mail, Storage, Session/Cookie, HttpClient, SecurityFilters, I18n, View/ViteManifest/Pageflow.
- Multi-project, multi-tenant hosting — host-based
DomainResolver, strict per-tenant DB routing, and a project-over-plugin resource resolution model. - Database & migrations — the multi-driver
DatabasePort(MySQL / PostgreSQL / SQLite / SQL Server) and the standalone LetMigrate engine (fluent schema, seeders, CLI). - Frontend federation — per-project surfaces +
hkm uito mirror plugin UIs, with a Pageflow (Inertia-style) SPA bridge.
- Dependency-free HTTP core. The kernel's
Request/Response/UploadedFileare currently built onsymfony/http-foundationas a deliberate, temporary choice. They are being reimplemented as pure value objects so the kernel carries no vendor coupling. The kernel's own method surface ($request->input(),Response::json(), …) is the stable API — build against it and the switch will be non-breaking. - API surface hardening. We're at the
1.0.xline; some plugin contracts and config keys are still settling. Pin your version and read the CHANGELOG before upgrading. - Docs & guides. The layer deep-dives in
docs/guides/are being expanded and turned into a proper documentation site. - Test & tooling coverage. PHPStan (level 5) and the PHPUnit suite are wired as CI gates; coverage and static-analysis depth are still growing.
- Finish the dependency-free kernel and drop the transitional Symfony dependency.
- A public documentation site generated from the layer guides.
- More first-party adapters (queue backends, storage drivers, mail transports).
- Performance benchmarks published per release.
Found a gap or want to help? Open an issue or a discussion.
Most frameworks boot everything, then decide what to do. GDA inverts that:
| Principle | What it means in practice |
|---|---|
| Security before everything | A SecurityGateway runs before any module loads. A denied request costs zero module wiring. |
| Load only what is needed | Only the modules required for this route are registered — resolved from a dependency graph per request. |
| One module, one domain | Every module owns exactly one bounded business domain. No exceptions. |
| Isolation by default | Modules cannot touch each other's internals — request-scoped containers enforce this at runtime. |
| Infrastructure independence | The kernel defines port interfaces; the project supplies implementations (MySQL, Redis, S3, …). |
| Explicit over implicit | Everything is declared in module.json. Nothing is auto-discovered at runtime. |
The result: predictable performance (you pay only for what a route uses), strong domain boundaries that hold at runtime, and infrastructure you can swap without touching business code.
┌─────────────────────────────────────────────────┐
│ PROJECT LAYER (wiring only — no business logic)│
│ ┌─────────────────────────────────────────────┐ │
│ │ MODULE / PLUGIN LAYER (bounded domains) │ │
│ │ ┌───────────────────────────────────────┐ │ │
│ │ │ KERNEL │ │ │
│ │ │ boot · security · loading · DI · │ │ │
│ │ │ pipelines · events · ports │ │ │
│ │ └───────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
- Kernel — knows nothing about your domains. Changes rarely.
- Module/Plugin — knows nothing about the project. Wires to the kernel through contracts.
- Project — knows everything, contains no business logic. Pure wiring.
Every number below was measured on one machine — against a scaffolded project, and against a complete application built on it (see A real application, not a probe). None is estimated, and none is copied from a third party.
Harness: Apple M3 (8 cores, 16 GB), macOS 27.2, PHP 8.5.12 with OPcache
(opcache.enable=1), Swoole 6.2.5, nginx 1.31.8. Load generated with ab -k -c 20 -n 4000
after a 300-request warm-up, against a dedicated php-fpm master (pm=static, 4 children)
and a dedicated nginx on their own ports and logs. Swoole ran 4 workers. Run-to-run variance
is ±10–25% on a busy machine, so treat the ordering as solid and the absolute figures as
this laptop's.
Same routes, same .env — only the server differs.
| Server | small JSON /ping |
DB route (SQLite) | serial latency (-c 1) |
|---|---|---|---|
php -S built-in (1 process) |
609 req/s | 346 req/s | 2.6 ms |
| nginx + PHP-FPM (4 workers) | 1,591 req/s | 1,209 req/s | 2.6 ms |
| Swoole (4 workers) | 8,994 req/s | 4,840 req/s | 0.44 ms |
| raw PHP, no framework (FPM) | 11,791 req/s | — | 0.45 ms |
The serial number is the headline, not the throughput one. With a resident kernel, HKM
answers a request in 0.44 ms against 0.45 ms for a bare PHP script with no framework
at all — the per-request cost of the framework is, within measurement error, nothing. The
5.7× gap between Swoole and PHP-FPM is almost entirely Kernel::build() running again on
every request.
php -S serves one request at a time. That row exists only to show why it must never be
used for a benchmark or a deployment.
Same server, same code — only .env changed:
| Configuration | req/s | vs. shipped |
|---|---|---|
As scaffolded (APP_DEBUG=true, no BOOT_CACHE) |
163 | 1.0× |
BOOT_CACHE=1 |
997 | 6.1× |
+ APP_ENV=production, APP_DEBUG=false, ENV_CACHE=1 |
1,542 | 9.4× |
BOOT_CACHE is documented as ~86× on the compile step in isolation; end to end it is 9.4×
on throughput. A project deployed to PHP-FPM with the development defaults runs at roughly
a tenth of its capacity. Set all three on any FPM deployment, and clear
var/cache/manifests/ on deploy.
Identical conditions: the same nginx, the same php-fpm pool, the same one-route /ping
returning the same small JSON, each framework in its own production mode (Laravel
artisan optimize, Symfony APP_ENV=prod with a warmed cache).
| Framework | req/s | p50 | p99 |
|---|---|---|---|
| raw PHP (no framework) | 11,791 | 2 ms | 3 ms |
| HKM 1.21 — Swoole | 8,994 | 2 ms | 9 ms |
| Slim 4.15 — FPM | 5,299 | 4 ms | 5 ms |
| Symfony 8.1 — FPM | 2,470 | 8 ms | 14 ms |
| HKM 1.21 — FPM | 1,591 | 12 ms | 33 ms |
| Laravel 13.42 — FPM | 554 | 32 ms | 81 ms |
Read honestly, that says two different things:
- Resident, HKM is the fastest full framework here — 76% of raw PHP, 1.7× Slim (a micro-framework), 3.6× Symfony, 16× Laravel.
- Per-request on FPM, HKM is mid-pack — behind Symfony, ahead of Laravel. Symfony
compiles its container and routing to PHP at build time; HKM re-reads its manifests,
revalidates ports and security layers and boots every module on each request, and
BOOT_CACHEshortens that without removing it.
Two caveats that matter before anyone quotes this table:
- It is not equal work. HKM's
/pingpasses a WAF, a CSRF layer and a security gateway, and emits security headers. Slim's is a closure. That is a design difference, not overhead to be optimised away — but it is not like-for-like. - Swoole vs. FPM is architecture, not merit. Laravel Octane or Symfony with a persistent runtime would close most of that gap. Comparing HKM-on-Swoole with Laravel-on-FPM measures the deployment model, not the framework.
Every table above measures a route that returns a constant, which is the one case where framework overhead is the whole request. Add 50 ms of I/O — one database call, one API call, one queue push, i.e. any real endpoint — and run four workers on each target:
| Target (50 ms I/O, 4 workers) | c=4 | c=50 | c=200 |
|---|---|---|---|
| raw PHP — FPM | 76 | — | — |
| Slim 4.15 — FPM | — | 76 | — |
| Symfony 8.1 — FPM | — | 75 | — |
| HKM 1.21 — FPM | 70 | 70 | refused |
| Laravel 13.42 — FPM | — | 71 | — |
| HKM 1.21 — Swoole + coroutine hooks | 77 | 925 | 3,653 |
The arithmetic ceiling for four workers at 50 ms is 78 req/s, and every blocking
configuration sits on it. The five frameworks that spanned 21× on /ping span 9% here —
framework overhead is a fixed cost, so it matters in proportion to how little the handler
does. What changed throughput by 47× was the concurrency model, not the framework:
enable_coroutine=true alone buys nothing (the request runs in a coroutine, but a blocking
call still holds the worker), while SWOOLE_HOOK_FLAGS=2147483647 serves 3,653 req/s at
concurrency 200 with p50 unchanged at 52 ms.
Two other measured limits worth knowing before a deploy:
- PHP-FPM does not degrade past its pool — it refuses. At c=200, 199,624 of 200,000
responses were non-2xx in 2 ms:
kern.ipc.somaxconn(128 here) caps the listen queue whateverlisten.backlogsays, and raisingpm.max_childrendoes not move it. Swoole at the same concurrency queued and kept serving. - Swoole's default
dispatch_mode = 2pins a connection to a worker by hashing its fd. Four keepalive connections landed on two of four workers — half the server idle, 38 of 78 req/s.dispatch_mode = 3fixed it. This is exactly the shape of a reverse proxy's upstream pool.
Every number above is a route that returns a constant or sleeps. To measure what an application does, a complete GDA plugin was built and benchmarked — not a controller with a query in it, but the full shape the framework asks for:
| Layer | What it holds |
|---|---|
Domain/ |
Money (integer cents), Product and Order entities with private constructors, named constructors and recorded domain events, an OrderStatus enum |
Application/ |
CatalogService (cache-aside read), CheckoutService in the mandated transaction → collect → commit → dispatch shape, a validating PlaceOrderDTO |
Infrastructure/ |
two repositories touching DatabasePort only, three controllers at ≤3 lines, an audit listener on the integration event, a queued ReserveStockJob |
module.json |
solves: shop.catalog, five routes with filters and per-route requires, jobs[], config[] |
Backed by 500 seeded products, SQLite in WAL mode, Redis for cache and queue, and the project's WAF + CSRF + security gateway in front of every request.
POST /api/shop/orders does all of this per request: validate a DTO → authorize against the
Identity → load the products → open a transaction → insert the order → insert its lines →
decrement stock with a guarded UPDATE → commit → dispatch an integration event → write an
audit row from a listener → push a job to Redis.
| Route (c=20) | FPM 4ch | FPM 32ch | Swoole 4w | Swoole 32w |
|---|---|---|---|---|
/ping (no work) |
1,171 | 1,450 | 4,460 | 13,112 |
catalogue read, 1 Redis GET |
996 | 1,081 | 1,888 | 2,887 |
| catalogue read, 2 SQL queries | 990 | 557 | 871 | 3,834 |
| server-rendered HTML + layout | 905 | 1,257 | 859 | 3,085 |
uncached DB list (/api/tasks) |
— | 1,191 | 1,374 | — |
POST /orders (the chain above) |
515 | 385 | 286 | 578 |
Read the columns, not the rows. At equal worker counts Swoole loses the HTML render and the
write (859 vs 905, 286 vs 515): four resident workers are fewer parallel slots than four
FPM children plus the OS scheduler, once a request blocks on disk. Equalise at 32 and it wins
everything — 1.5× on the write, 9× on /ping. So the resident-kernel advantage is largest
where the framework is most of the request, and smallest where it is least of it.
Worker count, not the framework, set every number here. 4 → 32 children is worth 8.1× on an I/O-bound route and costs 25% on the write path, where 32 processes contend for 8 cores and one SQLite writer. Size the pool from the workload.
The Redis cache made the catalogue read slower — the opposite of the usual advice, so it
was priced directly: one local Redis round trip is 167–239 µs (floor 145 µs), the two SQLite
queries it replaced are 129 µs. Under a resident runtime the uncached route won both passes.
A cache is a bet that the thing behind it is expensive; check before taking it. (An earlier
version called has() then remember() — two round trips, 267–279 µs — which turns a small
win into a clear loss. One get() per hit.)
Correctness held exactly under load, which matters more than the throughput: 2,602 orders produced 5,203 line rows, the queue's jobs wrote 5,203 reservation rows, the event listener wrote 2,602 audit rows, and the queue drained to zero. Every job ran once; nothing was lost or duplicated.
These routes exist only in HKM, so this table is not a framework comparison. The cross-framework numbers are the
/pingand 50 ms rows above: resident, HKM is the fastest full framework measured; on an I/O-bound route all five land within 9% of each other; and per-request on PHP-FPM with cheap routes, HKM is behind Symfony, whose container and routes are compiled at build time.
File-backed queue (FileQueue), with a job that reads from SQLite through DatabasePort:
| rate | |
|---|---|
| enqueue | ~20,000 jobs/s |
| drain (500-job batch) | 2,558 jobs/s |
| drain (2,000-job batch) | 1,902 jobs/s |
The queue drained to zero on every run. Throughput falls as the batch grows because
FileQueue rewrites the whole file on each pop — fine for development, quadratic overall.
A Redis queue is O(1) per pop.
A job that does real work — two inserts, through a Redis queue, with its own
ModuleContainer — runs 7–9× slower than that: 269 jobs/s on one worker, 715 on four
(sub-linear, because the SQLite writer serialises). Plan a queue against the second number,
not the first.
Bind the queue in
withPorts(), not only in a module.WorkerLoopresolvesQueuePortfrom theCoreContainer, because it needs a queue before it has a job to build a module container for. A plugin that bindsQueuePortper request is invisible to the worker: HTTP pushes to the broker, the worker pops from the core binding, and it printsRemaining in 'default': 0while every job sits in the broker. Nothing throws. Measured, and the project template now says so where the binding lives.
Download the latest build from Releases.
Linux (Debian / Ubuntu / Kali)
sudo apt install ./hkm-kernel_<version>_amd64.deb
hkm doctor # verify PHP + extensionsmacOS (Homebrew) — the shortest path; php and composer come with it.
brew tap alfacode-team/hkm https://github.com/AlfaCode-Team/hkm-kernel
brew trust alfacode-team/hkm
brew install hkm
hkm doctorbrew trust is not optional. Homebrew 6 refuses to load a formula from a
third-party tap until you say you trust it, and it refuses at brew install
rather than at brew tap — so without that line the tap appears to succeed and
the install then fails with "Refusing to load formula … from untrusted tap".
macOS (installer) — no root, like the Linux installer: HKM.app goes to
~/Applications, the Gatekeeper quarantine flag is cleared, and hkm /
hkm-config land on your PATH. Nothing is written outside your home.
curl -fsSL https://github.com/AlfaCode-Team/hkm-kernel/releases/latest/download/install-macos.sh | shAdd --system for a machine-wide /Applications install — that is the only
path that asks for sudo. An install that already exists is updated where it is,
so re-running never leaves a stale copy shadowed by a new one.
macOS (manual) — extract hkm-kernel-<version>-macos-universal.tar.gz
wherever you want it, then run
HKM.app/Contents/Resources/opt/hkm-kernel/install.sh. The launcher
self-locates its kernel, so the bundle works from any directory.
Windows — extract hkm-kernel-<version>-windows-x86_64.zip, run
hkm-kernel\install.bat, and add the folder to PATH.
The launcher self-locates the kernel — no environment variables required on a standard install. Runtime PHP dependencies are resolved with Composer on the target at install time, so they match your exact PHP.
The Homebrew formula lives in this repository under HomebrewFormula/,
which is why the tap URL is the repo itself rather than a separate homebrew-hkm. It keeps the
project registry in ~/.local/share/hkm rather than inside the Cellar, so brew upgrade cannot
take your registered projects with it.
- PHP ≥ 8.4.1
- Extensions:
json, mbstring, ctype, tokenizer, filter, pdo, openssl, curl, fileinfo - At least one PDO driver:
mysql·pgsql·sqlite·sqlsrv - Optional:
redis,swoole/openswoole,gd,intl
| Command | Purpose |
|---|---|
hkm new <path> [--project=<name>] |
Scaffold a new project (secure defaults: .env chmod 600, Apache + nginx configs) |
hkm run [path|name] |
Run a project locally (PHP dev server) |
hkm cli [command] |
Run a project's console interactively |
hkm worker [args] |
Run a project's queue worker |
hkm list |
List registered projects |
hkm plugins [path|name] |
Analyse a project's enabled plugins/modules |
hkm module |
Inspect / update the first-party kernel packages |
hkm ui [sync|list|link|clean] |
Federate enabled plugins' UIs into the frontend |
hkm doctor |
Diagnose PHP, extensions, and the resolved kernel path |
hkm-config |
Set up / repair the full environment (kernel + userdata) |
hkm upgrade [--check] |
Check for and install a newer release |
hkm version / --version / -v |
Show the banner + version |
hkm <command> --dev |
Run any command against the development kernel checkout |
| Variable | Meaning |
|---|---|
HKM_KERNEL_HOME |
Kernel root (composer.json, vendor/, projects/, templates/) |
HKM_DEV_HOME |
Development kernel checkout used by --dev (hkm-config set-dev-home <path>) |
HKM_USERDATA_DIR |
Persistent registry (projects.json + platform.json) that survives updates |
HKM_PHP_BIN |
Override the php binary |
HKM_CLI_PATH / HKM_GLOBAL_AUTOLOAD |
Override the PHP CLI script / kernel autoload |
Run hkm-config once and it pins HKM_KERNEL_HOME and provisions a persistent
HKM_USERDATA_DIR (migrating any existing registry) into ~/.config/hkm/config.env.
# 1. Scaffold — creates a hardened project skeleton
hkm new ~/apps/shop --project=shop
# 2. Verify the environment
hkm doctor
# 3. Run it locally
hkm run shop
# → serving http://127.0.0.1:8000 (docroot pinned to app/public)
# 4. Console + queue worker for the same project
hkm cli shop migrate # run migrations (LetMigrate)
hkm worker shop # drain the job queueA project is wiring only. Its bootstrap composes the kernel from a shared base and declares which plugins it activates:
// projects/shop/bootstrap/app.php
/** @var Kernel $builder */
$builder = require __DIR__ . '/../../../app/bootstrap/base.php';
return $builder
->withProjectPath(dirname(__DIR__))
->withModules([
Plugins\Auth\Provider::class,
Plugins\User\Provider::class,
Plugins\Task\Provider::class,
])
->build();Incoming requests are mapped to a project by host (app.example.com → the shop
project) via DomainResolver, falling back to the HKM_PROJECT env var, then admin.
A plugin (local business module) lives under plugins/<Name>/, uses the Plugins\<Name>\
namespace, and follows a strict GDA folder layout:
plugins/Invoice/
├── module.json ← single source of truth
├── API/Contracts/InvoiceServiceContract.php ← the ONLY thing other modules may import
├── Domain/ ← entities, value objects, domain events (zero external imports)
├── Application/Services/InvoiceService.php ← transaction + event orchestration
├── Infrastructure/
│ ├── Persistence/InvoiceRepository.php ← DatabasePort only
│ ├── Gateways/StripeGateway.php ← vendor SDK only
│ └── Http/Controllers/InvoiceController.php ← ≤3-line actions
└── Provider.php ← implements ModuleContract
Routes, config, dependencies, and emitted events are declared, never discovered:
{
"name": "invoice",
"solves": "invoice.generation",
"type": "module",
"requires": ["database.query"],
"exposes": ["InvoiceServiceContract"],
"routes": [
{ "method": "GET", "path": "/api/invoices", "handler": "InvoiceController@index" },
{ "method": "POST", "path": "/api/invoices", "handler": "InvoiceController@create", "filters": ["auth", "throttle:60,1"] },
{ "method": "GET", "path": "/api/invoices/{id}", "handler": "InvoiceController@show" }
],
"emits": ["invoice.created", "invoice.paid"],
"config": ["INVOICE_CURRENCY", { "key": "INVOICE_TAX_RATE", "type": "float", "required": false }]
}If a module reads an env var that isn't in config[], boot fails — no silent misconfig.
The kernel defines interfaces; the project binds implementations once, at the app-lifetime container:
->withPorts([
DatabasePort::class => new MySQLAdapter(config('database')),
CachePort::class => new RedisAdapter(config('cache')),
QueuePort::class => new RedisQueueAdapter(config('jobs')),
MailPort::class => new SmtpMailAdapter(config('mail')),
StoragePort::class => new S3StorageAdapter(config('storage')),
])Swap MySQL for Postgres, or SMTP for SES, without touching a single line of domain code.
Request
│
▼ SecurityGateway (runs BEFORE any module loads)
│ Firewall → RateLimiter → CSRF → [your Auth layer] ── deny = zero module cost
▼
HTTP pipeline
1. CorrelationIdStage propagate X-Correlation-ID
2. SecurityStage run the gateway, attach Identity
3. ResolveStage route-manifest lookup → service name
4. LoadStage build dependency graph → wire ONLY those modules
↳ RouteFilterStage run the route's declared filters[] (auth, throttle, …)
5. ExecuteStage contract → DTO → controller → Response
6. ErrorStage (wraps all) classify → notify (Slack/Mail/DB/File) → HTTP response
Every stage is handle(Request $request, callable $next): Response. Modules add
cross-cutting behaviour by registering hooks in Provider::boot(), or opt individual routes
into named filters via module.json.
A complete vertical slice. Each layer has one job and may only talk to the layer below it.
// Domain/ValueObjects/Money.php
final readonly class Money
{
private function __construct(private int $amount, private string $currency) { // integer cents — NEVER float
if ($this->amount < 0) throw new \DomainException('Money cannot be negative');
}
public static function of(int|float $amount, string $currency): self {
return new self((int) round($amount * 100), strtoupper($currency));
}
public function add(self $o): self {
if ($this->currency !== $o->currency) throw new \DomainException('Currency mismatch');
return new self($this->amount + $o->amount, $this->currency); // operations return NEW instances
}
public function amount(): int { return $this->amount; }
}final class InvoiceService implements InvoiceServiceContract
{
public function __construct(
private readonly InvoiceRepository $repository,
private readonly TransactionManager $transaction,
private readonly DomainEventCollector $collector,
private readonly EventBus $eventBus,
private readonly Identity $identity, // from the SecurityGateway
) {}
public function create(CreateInvoiceDTO $dto): InvoiceResponseDTO
{
// authorization first
if (!$this->identity->hasPermission('invoice:create')) {
throw new ServiceException('invoice.unauthorized', layer: 'service.invoice');
}
$this->collector->beginCollection();
$this->transaction->begin();
try {
$invoice = Invoice::create(ClientId::from($dto->clientId), Money::of($dto->amount, 'USD'));
foreach ($invoice->releaseEvents() as $e) $this->collector->collect($e);
$this->repository->save($invoice);
$this->transaction->commit();
} catch (\Throwable $e) {
$this->transaction->rollback();
$this->collector->discard(); // ALWAYS — no phantom events on rollback
throw new ServiceException('invoice.create.failed', layer: 'service.invoice', previous: $e);
}
// integration events dispatch ONLY after a successful commit — never inside try{}
$this->eventBus->dispatch(new InvoiceCreatedIntegrationEvent($invoice->id()->value(), $dto->amount));
return InvoiceResponseDTO::from($invoice);
}
}final class InvoiceRepository
{
public function __construct(private readonly DatabasePort $db, private readonly Identity $identity) {}
public function find(string $id): Invoice
{
try {
$row = $this->db->queryOne(
'SELECT * FROM invoices WHERE id = :id AND tenant_id = :t AND deleted_at IS NULL',
['id' => $id, 't' => $this->identity->tenantId], // ALWAYS tenant-scoped
);
} catch (\PDOException $e) {
throw new RepositoryException("find invoice [$id]", layer: 'repository.invoice', previous: $e);
}
return $row ? InvoiceHydrator::hydrate($row) : throw new RepositoryException("Invoice [$id] not found");
}
}final class InvoiceController
{
public function __construct(private readonly InvoiceServiceContract $service) {} // contract only
public function create(Request $request): Response
{
$dto = CreateInvoiceDTO::fromRequest($request); // validation happens here
return Response::json($this->service->create($dto)->toArray(), 201);
}
}class Provider implements ModuleContract
{
public function solves(): string { return 'invoice.generation'; }
public function requires(): array { return [DatabasePort::class]; }
public function exposes(): array { return [InvoiceServiceContract::class]; }
public function register(ModuleContainer $c): void
{
$c->bindInternal(InvoiceRepository::class, fn($c) =>
new InvoiceRepository($c->make(DatabasePort::class), $c->make(Identity::class)));
$c->bind(InvoiceServiceContract::class, fn($c) => new InvoiceService(
$c->make(InvoiceRepository::class), $c->make(TransactionManager::class),
$c->make(DomainEventCollector::class), $c->make(EventBus::class), $c->make(Identity::class),
));
}
public function boot(HttpPipeline $http, CliPipeline $cli, WorkerPipeline $worker, EventBus $events): void
{
// $events->subscribe('payment.succeeded', MarkInvoicePaidListener::class);
}
}Add Plugins\Invoice\Provider::class to a project's withModules([...]) and the routes,
config validation, and DI are live.
$sut = new InvoiceService(
new InMemoryInvoiceRepository(), new FakeTransactionManager(),
new DomainEventCollector(), $bus = new FakeIntegrationEventBus(), Identity::asUser('u-1', 'tenant-a'),
);
$result = $sut->create($validDto);
$bus->assertDispatched(InvoiceCreatedIntegrationEvent::class, times: 1);
$this->assertNotNull($result->invoiceId);These are enforced at runtime by ModuleContainer::bindInternal() — a violation throws
ScopeViolationException, not a lint warning.
Controller → Service (published contract interface ONLY)
Service → Repository AND Gateway (the ONLY layer that may call both)
Repository → DatabasePort ONLY (no HTTP, no vendor SDK)
Gateway → Vendor SDK ONLY (no DB, no services)
Domain → NOTHING EXTERNAL (zero imports outside Domain/)
Never (a partial list the framework actively rejects):
- Routes defined in PHP — only in
module.json/proj.json. floatfor money — use aMoneyvalue object with integer cents.- Vendor exceptions (
\PDOException, Stripe, …) escaping their layer — translate them. - Integration events dispatched inside a
try{}— only after commit. - Another module's internal class imported — use its published contract.
getenv()for a.envvalue — use theenv()helper.- Business logic in a controller — max 3 lines.
The kernel ships no plugins and depends on none. Roughly thirty first-party plugins cover auth, users, tenancy, OAuth2, mail, storage, sessions, validation, i18n, templating and the SPA bridge — each its own package, owning exactly one domain.
hkm plugins domains # every plugin and the `solves` domain it claims
hkm plugins enable auth # install it, publish its assets, run its migrationsThen add its Provider to the project bootstrap's withModules([...]).
Each plugin documents itself in its own repository — README.md for what it
is, CLAUDE.md for its contract and configuration, and module.json as the
authoritative requires[] / exposes[] / config[]. This repository keeps no
plugin catalogue: a static list here is the copy that goes stale, and it did.
Repositories are at github.com/AlfaCode-Team/hkm-plugin-<name>.
git clone --recurse-submodules git@github.com:AlfaCode-Team/hkm-kernel.git
cd hkm-kernel
composer install # also wires the git hooks (core.hooksPath=.githooks)
vendor/bin/phpunit # run the test suite
# If you skip composer, enable the repo git hooks manually (strips AI co-author
# trailers from commit messages):
git config core.hooksPath .githooks
# Build the native launcher (needs Zig — see tools/.zig-version):
cd tools && zig build --release=small # → ../bin/hkm + ../bin/hkm-configVERSION=1.2.3 ./tools/bundle.sh all # .deb + macOS .app + Windows .zip → dist/
# MODULES=git ./tools/bundle.sh linux # fetch path-repo modules from pinned commitsReleases are cut by pushing a v* tag — CI runs the test suite first, then builds all three
OS bundles and publishes them automatically.
Development happens on the master dev branch; main is the stable release branch.
Releases are CHANGELOG-driven and automatic — you never tag by hand.
- Do your work on
masterand commit. - Add a new
## [x.y.z] - YYYY-MM-DDsection toCHANGELOG.md(below## [Unreleased]), describing the changes. - Open a PR
master→mainand merge it. - On merge, the Auto Release workflow (
.github/workflows/auto-release.yml) reads the top CHANGELOG version and, if novX.Y.Ztag exists yet, creates the tag and calls the Release workflow — which runs the test gate, builds all OS bundles, and publishes the GitHub Release (notes pulled from that CHANGELOG section).
Notes:
- A release only starts when the merge changes
CHANGELOG.mdand introduces a version not already tagged — ordinary merges don't publish anything. - No secret/PAT is required: Auto Release invokes the Release workflow directly via
workflow_call. - You can still cut a release manually at any time by pushing a
v*tag.
For deep dives, see the layer guides in docs/guides/ and the
CHANGELOG. Those guides cover the kernel (src/) and the packages
it runs on (modules/); the Project\ layer is documented in
hkm-project-layer, each
plugin in its own repository, and the hkm CLI in tools/.
Scaffolded projects are hardened out of the box:
.envischmod 600; debug output is force-disabled whenAPP_ENV=production.- Every project ships
app/public/.htaccess, and its nginx or Apache configuration is generated by the Edge plugin (hkm edge:apply) — the docroot pinned toapp/public, dotfiles denied, and baseline security headers added. - The
SecurityGateway(firewall → rate limiter → CSRF → your auth layer) runs before any module — denied requests never touch business code. - Keep secrets (
APP_KEY, JWT signing keys, DB credentials) out of the CLI config and, in production, behind aSECRETS_PROVIDER.
MIT — see LICENSE.
