DerEuroMark View RSS

TL;DR

• One small, internally consistent API: new(), from(), count(), build(), buildMany(), save(), saveMany(), state(), sequence(), sequenceField(), for(), has(), with(), recycle(), query(), table().
• Every fluent call returns a fresh factory. No more “oops, that test polluted the next one because the factory was reused”.
• Sharp static analysis: subclass @extends BaseFactory<\App\Model\Entity\Article> once; build(), buildMany(), save(), saveMany() all resolve to the concrete entity type from there.
• A bundled Rector config covers the mechanical call-site renames so the upgrade is mostly one command.
• Generator backend is pluggable and auto-detected: install fakerphp/faker or johnykvsky/dummygenerator, the factory picks whichever is available with no config required, and you can plug your own adapter.
• recycle($entity) reuses an already-built parent across multiple belongsTo branches of an association tree, instead of silently building duplicate parents N times.
• TableAssertionsTrait adds direct database-state assertions (assertTableHas, assertTableCount, assertEntityExists, …) with failure messages tuned for factory-driven tests.

Why we wanted to modernize

The original design from vierge-noire/cakephp-fixture-factories is what made fast, factory-driven testing the default in CakePHP land in the first place — credit where it’s due. But the codebase was shaped by a PHP 7 / early-PHP-8 sensibility, and a few things had drifted out of step with where the surrounding ecosystem landed:

• PHP 8.2+ features change what’s idiomatic. Readonly-style immutability, native enum support, first-class callable syntax, sharper generic templates — all of these unlock cleaner shapes than were possible when the API was first drawn. Immutable fluent factories and BackedEnum cases as first-class values both belong in this bucket.
• The static-analysis bar moved. PHPStan level 8 with strict generics is now table stakes for serious projects. The single @extends BaseFactory<\App\Model\Entity\Article> line carrying through to every terminal — build(), buildMany(), save(), saveMany(), from() — is a meaningful upgrade over the per-method docblock dance that 1.x had to do.
• The factory-DSL space matured. Laravel’s factories, Foundry in Symfony land, and our own v2 design iterations surfaced patterns worth borrowing — the count() modifier separated from the entry call, directional for() / has(), named state methods over inline state(...) shapes, sequence/cycle helpers. Some of that fits Cake idiomatically, some had to be adapted (we use save over Laravel’s create because Table::save() is the native verb), but the shape benefits from the cross-pollination.
• The 1.x surface grew organically. make() / makeMany() / getEntity() / getEntities() / persist() / persistEntity() / persistEntities() plus static finders on the factory class — each addition made sense in its moment, but together they were seven-plus terminals you had to keep straight, plus a result-set return path that looked like a query result but wasn’t quite, plus mutable factories that could leak state across reuse. v1.4 cleaned up the typing without changing the shape; v2 is the right moment to redraw the shape itself.

The brief I gave myself going in: a small, internally consistent surface that one paragraph teaches end to end, no footguns the docs have to warn around, and crisp generics so the IDE just knows. Everything below follows from that.

What v2 looks like

// Singular, in-memory
$user = UserFactory::new()->build();

// Singular, persisted
$user = UserFactory::new()->save();

// Plural via count() — note the explicit *Many() terminal
$users = UserFactory::new()->count(5)->saveMany();

// Plural with overrides applied to all
$users = UserFactory::new(['admin' => true])->count(3)->saveMany();

// Inline — the ad-hoc override
$user = UserFactory::new()->state(['name' => 'Foo'])->save();

// Per-row variation across count()
$users = UserFactory::new()
    ->count(3)
    ->sequence(
        ['role' => 'admin'],
        ['role' => 'editor'],
        ['role' => 'user'],
    )
    ->saveMany();

// Single-column variation that stacks across calls
$articles = ArticleFactory::new()
    ->count(6)
    ->sequenceField('status', 'draft', 'published')   // 2-cycle
    ->sequenceField('priority', 1, 5, 10)             // 3-cycle
    ->buildMany();

->sequenceField('status', ...Status::cases())

$user = UserFactory::new()
    ->afterBuild(fn (User $user) => $user->name = 'Built name')
    ->afterSave(fn (User $user) => $user->synced = true)
    ->save();

// belongsTo
$article = ArticleFactory::new()
    ->for(AuthorFactory::new(['name' => 'Mark']))
    ->save();

// has-many
$author = AuthorFactory::new()
    ->has(ArticleFactory::new()->count(3))
    ->save();

MessageFactory::for(UserFactory::new()) cannot resolve a unique belongsTo —
`Messages` declares 2 associations targeting `Users`:
  - Sender    (foreign key: sender_id)
  - Recipient (foreign key: recipient_id)

Use the explicit form to disambiguate:
  MessageFactory::new()->with('Sender',    UserFactory::new())
  MessageFactory::new()->with('Recipient', UserFactory::new())

$message = MessageFactory::new()
    ->for(UserFactory::new(['name' => 'Mark']), 'Sender')
    ->for(UserFactory::new(['name' => 'Lou']),  'Recipient')
    ->save();

// has() with an alias on a habtm association
$post = PostFactory::new()
    ->has(TagFactory::new()->count(3), 'PrimaryTags', pivot: ['featured' => true])
    ->save();

$country = CountryFactory::new(['code' => 'DE'])->save();

$users = UserFactory::new()
    ->count(5)
    ->recycle($country)
    ->has(AddressFactory::new()->count(2))   // Address also belongsTo Country
    ->saveMany();

// Direct table access (replaces 1.x Factory::get($id))
$article = ArticleFactory::table()->get($id);

// Dedicated query starting point (replaces static Factory::find / count)
$published = ArticleFactory::query()->find('published')->all();

$article = $articlesTable->newEntity(['title' => 'Existing']);
$factory = ArticleFactory::from($article);

Sharper static analysis

Declare the entity type once on the factory:

/**
 * @extends \CakephpFixtureFactories\Factory\BaseFactory<\App\Model\Entity\Article>
 */
class ArticleFactory extends BaseFactory
{
    // ...
}

…and PHPStan / Psalm resolve build(), buildMany(), save(), saveMany(), from() and friends to Article and array<Article> everywhere they’re called. No per-method overrides, no @phpstan-return magic.

If you have existing factories, the bundled FactoryAnnotatorTask keeps the docblocks in sync. With dereuromark/cakephp-ide-helper installed, bin/cake annotate classes (or annotate all) walks tests/Factory/ automatically.

Database-state assertions

TableAssertionsTrait adds a small set of assertion methods that read off Factory::query() with failure messages tuned for fixture-driven tests:

use CakephpFixtureFactories\TestSuite\TableAssertionsTrait;

class ArticleSyncServiceTest extends TestCase
{
    use TableAssertionsTrait;

    public function testSyncImportsExpectedRows(): void
    {
        ArticleFactory::new(['title' => 'Old', 'status' => 'draft'])->save();

        $this->articleSyncService->run();

        $this->assertTableCount(ArticleFactory::class, 3);
        $this->assertTableHas(ArticleFactory::class, ['title' => 'New', 'status' => 'published']);
        $this->assertTableMissing(ArticleFactory::class, ['status' => 'broken']);
    }
}

Available helpers: assertTableHas, assertTableMissing, assertTableCount, assertTableEmpty, assertEntityExists, assertEntityMissing. Compared to hand-rolling $this->fetchTable('Articles')->find()->where(...)->count() in tests, the failure messages tell you which factory, which conditions, and what the actual rows look like instead of just “Failed asserting 2 matches 3”.

Named entity pools with Story

The new Story scenario abstract is for fixtures with a bit of structure — when you want a named pool of users (”Admins”, “Editors”), draw random members from it for related rows, and have the whole thing build in one call:

class BlogStory extends Story
{
    public function build(): void
    {
        $this->addToPool('Admins',  UserFactory::new(['role' => 'admin'])->count(2)->saveMany());
        $this->addToPool('Authors', UserFactory::new(['role' => 'author'])->count(5)->saveMany());

        foreach ($this->getPool('Authors') as $author) {
            ArticleFactory::new()
                ->count(3)
                ->for($author)
                ->saveMany();
        }
    }
}

addToPool, getPool, getRandom, getRandomSet are the surface; existing FixtureScenarioInterface implementations keep working unchanged.

Test isolation without $fixtures arrays

CakePHP’s classic fixture flow asks you to enumerate every table a test class might touch in a $fixtures property. That works, but it drifts: someone adds a Behavior that hits Logs, the test class doesn’t know, the fixture array doesn’t update, and you find out hours later when CI complains about leaked rows.

FactoryTransactionStrategy flips the model. Configure it once in config/app.php:

'TestSuite' => [
    'fixtureStrategy' => \CakephpFixtureFactories\TestSuite\FactoryTransactionStrategy::class,
],

Every test then runs inside a transaction on the primary connection, opened at setupTest() and rolled back at teardownTest(). Anything written during the test — factories, direct $table->save($entity) calls, raw $connection->execute('INSERT ...') — is automatically reverted. No per-class $fixtures array, no manual cleanup.

Two extras worth knowing:

• Multi-database setups still skip transactions on connections they never write to. The strategy opens eagerly on the primary connection (default test, override via the protected string $primaryConnection property in a subclass). Secondary connections are tracked lazily through BaseFactory::save() / saveMany() — so a test that only uses one connection only opens one transaction.
• Generator unique-state resets between tests. The strategy clears the cached generator instances at teardown, so the second test in a class doesn’t inherit the first test’s unique() history and can’t trip OverflowException on a small value space.

For the rare cases that need real commits — code that depends on Model.afterSaveCommit, commit-triggered behaviors, or rows being durably visible across a separate connection — opt into the lazy variant per-class with LazyTransactionTrait, or fall back to Cake’s Eager strategy as a temporary pressure valve. The upgrade guide covers the trade-off.

Pluggable generator backend

The generator behind definition() is no longer hard-wired to Faker. v2 introduces a GeneratorInterface with two adapters in the box:

• faker — fakerphp/faker, the well-known one, full locale catalogue, large provider list.
• dummy — johnykvsky/dummygenerator, smaller and designed for deterministic, seeded output.

You don’t have to pick one in config. The resolver runs in this order:

1. Explicit $type argument to CakeGeneratorFactory::create() — wins if you pass one.
2. Configure::read('FixtureFactories.generatorType') — wins next, for projects that want to pin a choice.
3. Auto-detection — if Faker\Generator is loaded, use faker; otherwise fall back to DummyGenerator\DummyGenerator if that’s installed; throw a clear FixtureFactoryException with installation guidance when neither is available.

Faker stays the tiebreaker when both libraries are installed (preserving the prior default), but a project that only depends on johnykvsky/dummygenerator no longer needs to declare anything in config/app.php to make it work — the factory just picks it up.

Override globally or per call when the auto-detected default isn’t what you want:

// config/app.php — pin Dummy regardless of what's installed
'FixtureFactories' => [
    'generatorType' => 'dummy',
],

// Or per call, scoped to one factory instance
$article = ArticleFactory::new()->setGenerator('dummy')->build();

Why pick one over the other?

• Faker gives you realistic-looking data and the broadest provider surface — names, addresses, jobTitles, IBANs. The price is that it seeds via PHP’s process-global mt_srand, which interacts with PHPUnit’s randomized test ordering and with anything else in the process touching mt_rand. Two CI runs of the same seeded test can drift because of factors outside the seed.
• DummyGenerator uses a per-instance XoshiroRandomizer seeded explicitly through the adapter, so the sequence depends only on the seed and the call order on that specific generator instance. CI failures on row 47 of a 100-row factory output replay locally with the same seed. It’s also smaller and faster — no locale catalogue to load — at the cost of a narrower provider surface.

For reproducible test data either way, set the seed once:

'FixtureFactories' => [
    'seed' => 1234,
    'defaultLocale' => 'en_US',  // explicit beats I18n fallback
],

If a test is flaky on the lowest-deps matrix and you can’t pin down why, switching that one test class to Dummy is often enough to confirm whether the flake was a Faker mt_srand interaction.

How to upgrade

The package ships a Rector config that covers the safe, mechanical call-site changes:

vendor/bin/rector process tests --config vendor/dereuromark/cakephp-fixture-factories/rector.php

The bundled rules cover:

• Factory::make(...) → Factory::new(...)
• Factory::make($data, $n) → Factory::new($data)->count($n)
• setDefaultTemplate() wrappers → definition(GeneratorInterface $generator)
• getEntity() → build(), getEntities() → buildMany()
• persistEntity() → save(), persistEntities() → saveMany()
• patchData(...) → state(...) (in factory helper methods such as asAdmin())
• static query helpers like Factory::find() → Factory::query()
• Factory::get($id, $opts) → Factory::table()->get($id, $opts)

A few things rector intentionally doesn’t do — like rewriting deprecated persist() calls, because that return type is shape-dependent and needs a human choice between save() and saveMany(). The Factory::find() rule also splits by arity: zero-arg Factory::find() rewrites to Factory::query() directly (CakePHP 5’s SelectQuery::find() requires a finder name, so the chained form would error at runtime), while calls with an explicit finder name keep the chained Factory::query()->find('name') shape.

There’s also a small set of behavior changes since 1.4 that aren’t mechanical — setGenerator() is instance-scoped by default now, setDefaultTemplate() is no longer wired up (the rector handles the rewrite, but if you skip rector your factories produce empty data silently), FactoryTransactionStrategy is eager again on the primary connection. The full list is in the upgrade guide.

What’s next

v2 is out and tested against a real sandbox app, currently available as 2.0.0-rc.1 for adopters who want to upgrade before the final tag drops. If you’re on the 1.4.x line, follow the upgrade guide — the migration tooling does most of the work, and the rest is documented as you hit it.

Issues, PRs, and “this confused me when I tried it” posts on the issue tracker all welcome.

Thanks

A big thank-you to pabloelcolombiano and the vierge-noire team for building cakephp-fixture-factories in the first place. It shaped how a generation of CakePHP projects write tests (fast, factory-driven, no $fixtures-array gymnastics), and this continued version stands entirely on that foundation. With the project not being maintained anymore in 2025, we decided to take over. The redesign is a continuation of their work.

Links

• Repository
• Documentation
• v2 upgrade guide
• Migration from vierge-noire/cakephp-fixture-factories
• 2.0.0-rc.1 release notes
• v2 design RFC (#40)

Log anything, not just CRUD

2.0’s headline feature is custom action events. The audit trail is no longer limited to Created / Updated / Deleted rows tied to an entity — anything you want to leave a forensic record of can flow through the same persister, the same hash chain, and the same admin viewer.

use AuditStash\Audit;

Audit::log(
    type: 'user.login',
    source: 'Users',
    primaryKey: $user->id,
    data: ['ip' => $request->clientIp()],
    meta: ['user_id' => $user->id, 'user_display' => $user->name],
);

Behind the scenes:

• A new AuditStash\Audit static facade dispatches the event.
• EventFactory falls back to a new AuditCustomEvent for unknown types.
• audit_logs.type widened from VARCHAR(7) to VARCHAR(64) so dotted scope strings fit.
• The admin templates (timeline, view, index filter dropdown, email alert) all learned to render custom events with a neutral grey marker and a generic Event payload card instead of mis-rendering them as deletions.

A real admin dashboard

The plugin now ships an at-a-glance dashboard at the admin root (configurable via AuditStash.routePath) so you stop landing on a paginated list as the first thing you see.

What’s on it:

• KPI cards: events today, active users, active sources (7d), coverage percentage.
• Daily activity chart over the last 30 days — pure CSS stacked bars, no chart library dependency.
• Top sources and top users over 7 days, click-through to the filtered viewer.
• Recent activity table reusing the existing AuditHelper::eventTypeBadge and formatRecord helpers.

Alongside it, a new Coverage report at /admin/audit-stash/coverage answers the question “which of my tables are actually being audited?”:

• Discovers Table classes from the app and every loaded plugin via Plugin::getCollection().
• Three statuses: Tracked (class exists + behavior attached), Missing (class exists but behavior NOT attached — a coverage gap), and Empirical (events recorded for a source we can’t map to a class — custom event sources, renamed tables, uninstalled plugins).
• Configurable deny-list via AuditStash.coverage.hidePlugins / AuditStash.coverage.hideTables.
• A self-recursion guard so the plugin doesn’t try to audit its own audit tables.

Native Slack and Discord alert channels

AuditMonitor already supported alert delivery, but until now you had to hand-write a Channel subclass to get a readable Slack or Discord message. The new release ships two platform-native channels you can drop in directly:

'channels' => [
    'class' => SlackChannel::class,
    'url' => env('SLACK_WEBHOOK_URL'),
],

• SlackChannel uses Block Kit (header / section / fields blocks) with a severity-colored attachment. Optional username / icon_emoji / channel overrides. Fields are mrkdwn-escaped, so a source containing < or @everyone can’t smuggle markup or pings.
• DiscordChannel uses the embed format with a decimal-RGB sidebar color and inline fields. Sets allowed_mentions: { parse: [] } defensively, omits the timestamp key when the audit row has no created, and normalises empty / null field values to n/a so Discord doesn’t reject the payload.
• Both channels link back to the admin view of the row that triggered the alert, so chat recipients can jump straight into the entry instead of pasting source / PK into the URL bar.

The shared HTTP, retry and error-logging plumbing was extracted into a new AbstractWebhookChannel — the documented extension point for whatever platform-native schema your tenant prefers.

Teams users: there’s no bundled TeamsChannel because Microsoft is sunsetting MessageCard incoming webhooks in favor of Adaptive Cards via Power Automate Workflows, which has a fundamentally different setup and trigger model. The Building your own channel docs section points at AbstractWebhookChannel as the extension seam for whatever schema your tenant currently accepts.

Lifecycle hooks for the monitor

Channels are the happy-path delivery mechanism — but they’re a closed set. Anything beyond the bundled platforms (per-context suppression, alert mutation, forwarding to Sentry, custom incident stores) used to require subclassing.

Two new events on the global EventManager fire around the existing rule-check / alert-send flow:

Rule-failure routing went a different way: instead of a third event, the rule-failure logger call now passes the full Throwable ('exception' => $e) so PSR-3 handlers like Monolog’s IntrospectionProcessor or the sentry/sentry Cake bridge pick up the stack natively. No new API surface, full forwarding to your existing error pipeline.

A real export workflow

Export is now its own page, not an inline button. Three pieces:

• AuditStash\Service\ExportService — streams the query in configurable batches (AuditStash.export.batchSize, default 1000), pre-flights with a count() against AuditStash.export.hardCap (default 100000), and refuses oversized exports with BadRequestException rather than silently truncating.
• A dedicated /admin/audit-logs/export form page showing the active-filter summary, row-count estimate, format picker (CSV / JSON / NDJSON), and a disabled submit button when the cap would be exceeded.
• A controller action that streams via php://temp + Laminas\Diactoros\Stream — bounded PHP-process memory, spills to disk past 2 MB.

NDJSON joins CSV and JSON for streaming-friendly machine consumers. Filters carry from the index page through to the form via query string and on through to the streaming download URL — so the row count you confirm is the row count you get. The default 30-day created-at floor is skipped when other narrowing filters (source, primarykey, transactionkey, etc.) are already set, so a deliberately-narrowed view never silently exports zero rows.

Security: deny-by-default admin access

This is the change most likely to bite on upgrade, and it’s deliberate.

Audit logs commonly contain who-did-what records — PII, IP addresses, before/after field values for every change. An accidentally forgotten host-side route guard would expose more than a typical admin page. So the plugin now refuses to serve any admin action unless AuditStash.adminAccess is explicitly set to a Closure. A missing config key, a non-Closure value, a Closure that returns anything other than literal true, or a Closure that throws — all yield a 403.

The config key was also renamed from accessCheck to adminAccess to align with the cakephp-queue posture and to read more naturally (describes what is gated rather than the function shape).

Escape hatch for users who want to delegate fully to their host AppController auth:

'AuditStash' => [
    'adminAccess' => fn() => true,
],

That’s now an explicit “I trust the upstream guard” choice rather than an accidental forgotten gate.

Forensic capture and a sensitive-field rule

Two opt-in observability additions:

EnvironmentMetadata learned a new capture constructor argument so applications can opt in to request-derived meta fields:

new EnvironmentMetadata(
    request: $request,
    capture: ['user_agent', 'referer', 'session_id'],
);

Off by default because these can carry PII / GDPR implications. Empty headers and inactive sessions are skipped so the audit row never gains an empty-string column. Unknown field names are filtered against an allow-list, so a typo can’t smuggle arbitrary values into meta.

SensitiveFieldRule is a new monitor rule that fires when a configured field on a configured table appears in an audit row’s changed (create / update) or original (delete) payload. Mirrors MassDeleteRule’s shape, slots into the existing channel pipeline with no infrastructure changes, defaults to high severity. Ideal for “alert me when anyone touches users.password_hash” style rules.

Tamper-evident audit logs

This one actually shipped back in 1.1.0 but never got a proper writeup, so it’s worth covering alongside 2.0: an opt-in SHA-256 hash chain over persisted audit rows, giving AuditStash the integrity guarantees that regulated environments — GoBD (DE), SOX (US), HIPAA, and friends — expect from the audit trail itself.

Each persisted row carries two new columns — prev_hash (the previous row’s hash) and hash (SHA-256 over the canonicalized current row plus that previous link). Editing any historical row breaks the chain at that row and every row after it; a verifier walking the table catches the break and points at the offending row.

Disabled by default. To turn it on:

'persisterConfig' => [
    'hashChain' => true,
],

…plus the new migration that adds prev_hash / hash / idx_hash. Rows written before the migration stay NULL in both columns — the chain simply anchors at the first row written after you flip the flag, so there’s no destructive backfill step.

A few mechanics worth flagging:

• Verification is a shipped CLI: bin/cake audit_stash verify_chain [--table=... --chunk=...] — streams the table in bounded memory and exits 1 on the first broken link with a human-readable reason. Drop it in cron or CI.
• The whole logEvents() batch runs in a single transaction; on MySQL / Postgres the chain tail is read with SELECT ... FOR UPDATE so concurrent writers serialize on it instead of orphaning links. SQLite’s database-level locking gives the equivalent guarantee.
• Hashing is schema-aware — only fields that exist on the target audit table are included in the digest, so custom audit tables (without e.g. display_value) verify cleanly without payload divergence across installs.
• Fail-loud: a save() failure mid-batch throws RuntimeException rather than silently dropping a row and breaking the chain at the tail.

Only TablePersister implements this — the Elastic Search persister can’t offer the same ordering guarantee, and the flag is ignored there. If you need tamper-evidence on Elastic, route audit events through SQL first and replicate downstream.

Full rationale, concurrency semantics, and the truncation-at-tail limitation (plus anchoring / heartbeat mitigations) are written up in docs/tamper-evidence.md.

Tracking file uploads (hashes, not content)

Audit rows are not the place to stash uploaded file blobs. The clean approach is a virtual field on the entity that exposes a stable fingerprint — a hash over the stored bytes, a CDN ETag, byte length, whatever is cheap and deterministic for your storage:

// src/Model/Entity/Document.php
protected function _getFingerprint(): ?string
{
    return $this->file_path
        ? hash_file('sha256', WWW_ROOT . $this->file_path)
        : null;
}

Virtual fields participate in entity diffs like any other column, so the audit row records “fingerprint changed from abc… to def…” without your audit table ever seeing the file body. No audit-side machinery required.

For legacy schemas where you can’t add a virtual field — uploads tracked in a sibling join table the audited entity doesn’t know about, for example — there’s a AuditStash.beforeLog event hook that fires before the audit row is persisted. One caveat called out explicitly in the docs: BaseEvent has no public setter for changed / original, so the event-hook path needs a small persister decorator to actually merge your additions in. The pattern is in docs/usage.md.

For the related case of recording that a sensitive field changed without storing the value itself, the existing 'sensitive' behavior config is still the right tool — no new machinery there either.

Testing helper trait

If you maintain a downstream application that uses audit-stash, you’ve probably written a one-off helper to assert “this controller action produced an audit row”. There’s now a shipped one:

use AuditStash\TestSuite\AuditAssertionsTrait;

class OrdersControllerTest extends TestCase
{
    use AuditAssertionsTrait;

    public function testCreateLogsAuditEntry(): void
    {
        $this->post(['controller' => 'Orders', 'action' => 'add'], [...]);

        $this->assertAuditLogged('Orders');
        $this->assertAuditFieldChanged('Orders', 'status', null, 'pending');
    }
}

Mixes into any TestCase that loads plugin.AuditStash.AuditLogs. Exposes assertAuditLogged, assertAuditNotLogged, assertAuditCount, assertAuditFieldChanged, plus a buildAuditQuery seam for custom assertions. Queries the audit_logs table directly so tests verify what was persisted, not just what an in-memory event queue produced.

The new docs/testing.md covers the full reference and the buildAuditQuery extension seam.

Where to next

If you’re upgrading from 1.x to 2.0, the two things to look at on the way in are:

1. Set AuditStash.adminAccess to an explicit Closure — even fn() => true is fine if you trust your upstream guard. A missing config key now yields a 403.
2. Run the migration that widens audit_logs.type to VARCHAR(64). It also drops the EnumType mapping on the column, which means $auditLog->type now returns a string instead of an AuditLogType enum.

Everything else is additive.

Feedback, bug reports, and feature requests (ideally as PRs) welcome over at the GitHub repo.

And This Time It Grew Up

Remember CakePHP 2’s ACL? The ACO/ARO trees, the aros_acos join table, the tutorial that taught a whole generation of us what “hierarchical permissions” even meant? That was a big idea for its time — permissions as data, managed at runtime, not baked into code. A lot of us learned authorization concepts from that component, and the DNA of today’s tools goes right back to it.

Some people remember: It was painful and slow to work with it, though.

Then the ecosystem evolved. CakePHP 3, 4, and 5 shipped cakephp/authorization and cakephp/authentication — clean, policy-based, composable. TinyAuth kept the lightweight INI-file style alive for teams who wanted configuration over code. Both approaches are great at what they do.

Maybe you also read my last blog post about authz topic.

The one thing that stayed a little wistful was the admin-UI story. Policies live in code; INI files live on disk; and every so often a project would ask, “Can ops toggle this without a deploy?” The honest answer used to be “not really”. That’s the gap TinyAuth Backend 3.x closes — and it’s the reason ACL, as a concept, is quietly having a comeback.

A complete rewrite, on purpose

TinyAuth Backend 3.x is a full rewrite. The breaking changes are real — the old tiny_auth_allow_rules and tiny_auth_acl_rules tables are dropped by the migration, PHP 8.2 and CakePHP 5.1 are the new minimums, and existing permissions need to be re-imported or recreated. The payoff is a plugin that feels native to modern CakePHP instead of bolted on around it.

The easiest way to understand the shape of the rewrite is to look at the schema, the UI, and the integration points side by side.

bin/cake tiny_auth_backend import allow
bin/cake tiny_auth_backend import acl

// config/app.php
use Psr\Http\Message\ServerRequestInterface;

'TinyAuthBackend' => [
    'editorCheck' => function (mixed $identity, ServerRequestInterface $request): bool {
        return $identity !== null && in_array('admin', (array)$identity->roles, true);
    },
],

// config/app.php
'TinyAuthBackend' => [
    'features' => [
        'allow'     => true,   // force enabled
        'acl'       => true,
        'roles'     => true,
        'resources' => false,  // force disabled
        'scopes'    => false,
    ],
],

Pick your rung: the four-strategy ladder

All of the above can be adopted incrementally. The demo app ships four usage strategies, arranged as a ladder. Start on the rung that fits where your project is today, and climb as needs grow. Every rung is a legitimate destination — you don’t have to reach the top to “win”.

// AdapterOnly: role-level request gating, nothing more.
// TinyAuthBackend reads from the DB, the admin UI writes to it,
// your controllers keep doing exactly what they were doing.

// Application::getAuthorizationService()
use TinyAuthBackend\Policy\TinyAuthResolver;

$resolver = new TinyAuthResolver([
    \App\Model\Entity\Article::class,
    \App\Model\Entity\Project::class,
]);

return new AuthorizationService($resolver);

public function edit(string $id)
{
    $article = $this->Articles->get($id);
    $this->Authorization->authorize($article, 'edit');
    // ...
}

public function index()
{
    $query = $this->Authorization->applyScope($this->Articles->find(), 'index');
    // Query now filtered by the user's scope — "own", "team", whatever.
}

Under the hood: a service per concern

The rewrite leans hard on small, focused services. If you want to build tooling around the plugin — custom import formats, a different UI, a scheduled sync — these are the handles:

• TinyAuthService — central permission checking
• HierarchyService — role hierarchy traversal and inheritance resolution
• ControllerSyncService — controller/action discovery from your application
• ResourceSyncService — entity resource/ability discovery
• ImportExportService — JSON/CSV export and legacy INI import
• FeatureService — enable/disable optional features at runtime
• RoleSourceService — flexible role data source resolution

Each one has a single job and a small surface area. Together they’re what makes the admin UI, the CLI commands, and the authorization integration feel like parts of the same system rather than three things stapled together.

Today’s take on a classic idea

A few things worth celebrating about where TinyAuth Backend 3.x landed:

• Flat, queryable schema. Eight tables, plain joins, plain SQL, no trees of nodes pretending to be both subjects and objects.
• A good neighbour to cakephp/authorization. It plugs into the framework’s policy layer rather than replacing it.
• Permissions as self-documenting data. Rule descriptions, export to JSON/CSV, auditable in a query.
• A real UI stack. HTMX + Alpine + Tailwind, dark mode included, no full-page reloads, scrolls and search that actually work.
• A gradual adoption story. Composite adapters, INI import, CLI sync, and four usage strategies you can climb through at your own pace.
• Identity-agnostic. Roles can come from wherever your auth story actually lives.
• No lock-in. You can stop at any rung, or step back a rung, without tearing things up.

So, is ACL back?

In spirit, yes. The concept that made ACL interesting in the first place — configure permissions as data, manage them in a UI, enforce them at runtime — is back, and it’s wearing modern CakePHP underneath. Normalized schema, reactive UI, first-class policy integration, flexible role sources, and a gradual adoption path that meets your project where it actually is.

Pick a rung, give it a spin, and see how far up the ladder your project wants to climb. The linked demo app below also has strict CSP and showcases that it works with strictest SecurityHeadersMiddleware implementations for maximum safety.

Links

• Demo app: github.com/dereuromark/cakephp-tinyauth-demo
• TinyAuth Backend: github.com/dereuromark/cakephp-tinyauth-backend
• TinyAuth: github.com/dereuromark/cakephp-tinyauth

The problem: env(’REMOTE_ADDR’)

Do not use env('REMOTE_ADDR') or low level env() wrapper directly. Those are always the direct TCP connection source, not necessarily the real IP. Make sure to always use ServerRequest::clientIp() when interacting with the user’s IP address.

When you move a CakePHP application behind a reverse proxy – for example, switching from PHP-FPM to FrankenPHP in Docker behind nginx, this issue becomes visible. Now env('REMOTE_ADDR') holds the internal IP of the proxy (e.g. 172.22.0.1 for Docker’s bridge network).

This breaks anything that relies on the raw environment variable:

• IP-based blacklists stop matching
• GeoIP lookups resolve to the wrong location
• Rate limiting becomes ineffective (all users share one IP)
• Logging records the proxy IP instead of the actual visitor

You’ll typically notice it first in the logs – every request line shows the same address:

[2026-04-09 14:22:01] login.INFO: User logged in {"user_id":42,"ip":"172.22.0.1"}
[2026-04-09 14:22:07] login.INFO: User logged in {"user_id":17,"ip":"172.22.0.1"}
[2026-04-09 14:22:11] login.WARN: Failed login attempt {"ip":"172.22.0.1"}

That’s the Docker bridge gateway, not your visitors.

The fix: ServerRequest::clientIp() + Middleware

CakePHP’s ServerRequest::clientIp() is proxy-aware. When trusted proxies are configured, it reads the real client IP from the X-Forwarded-For or X-Real-IP headers that the reverse proxy sets. When no proxy is involved, it falls back to REMOTE_ADDR – so it works correctly in both environments.

class TrustedProxyMiddleware implements MiddlewareInterface {

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        if ($request instanceof ServerRequest) {
            $trustedProxies = Configure::read('App.trustedProxies');
            if ($trustedProxies) {
                $request->setTrustedProxies((array)$trustedProxies);
            }
        }
        return $handler->handle($request);
    }
}

'App' => [
    'trustedProxies' => [
        '127.0.0.1',
        '172.16.0.0/12',
        '10.0.0.0/8',
        '192.168.0.0/16',
    ],
],

env('REMOTE_ADDR')
$_SERVER['REMOTE_ADDR']

use Cake\Routing\Router;

$ip = Router::getRequest()?->clientIp();

$routes->get('/debug-ip', function ($request) {
    return new Response(['body' => $request->clientIp()]);
});

Console/CLI context

clientIp() only makes sense during an HTTP request. If you have a queue worker or shell command that needs the visitor’s IP – say, to send a “new login from $ip” email asynchronously – you can’t recover it after the fact. Capture the IP at request time and persist it into the job payload, then read it from there in the worker.

Further reading

• CakePHP docs: ServerRequest
• CakePHP docs: Trusted Proxies

Bottom line

If you run CakePHP behind any reverse proxy – Docker, nginx, a load balancer, Cloudflare – always use ServerRequest::clientIp() with trusted proxies configured. It’s a one-time setup that prevents a whole class of subtle bugs.

Why Consider TOML?

Configuration formats involve trade-offs. YAML offers flexibility but brings complexity. JSON lacks comments and trailing commas. PHP arrays work but aren’t portable. TOML aims for a middle ground: human-readable, unambiguous, and easy to parse.

TOML Syntax Primer

For those unfamiliar with TOML, here’s a quick overview of the format.

Basic key-value pairs:

title = "My Application"
version = 1.2
enabled = true

Tables (sections):

[database]
host = "localhost"
port = 5432

[database.credentials]
username = "admin"
password = "secret"

Arrays:

ports = [8080, 8081, 8082]
hosts = ["alpha", "beta", "gamma"]

Array of tables:

[[servers]]
name = "alpha"
ip = "10.0.0.1"

[[servers]]
name = "beta"
ip = "10.0.0.2"

Inline tables:

point = { x = 1, y = 2 }
database = { host = "localhost", port = 5432 }

Multiline strings:

description = """
This is a longer description
that spans multiple lines.
Whitespace is preserved."""

regex = '''\\d+\\.\\d+'''

Dates and times:

created = 2024-01-15T10:30:00Z
date_only = 2024-01-15
time_only = 10:30:00

Format Comparison: TOML vs YAML vs NEON

Each format has its quirks. Here’s how they compare in practice.

The “Norway problem” – unquoted strings becoming booleans:

# YAML 1.1 and some legacy parsers: This becomes boolean false
country: NO

# YAML 1.1 and some legacy parsers: These also become booleans
answer: yes
enabled: on

# TOML: Always a string, no ambiguity
country = "NO"

Whitespace sensitivity:

# YAML: Indentation matters - this is valid
database:
  host: localhost
  port: 5432

# YAML: This breaks everything
database:
  host: localhost
 port: 5432  # Wrong indentation = parse error or wrong structure

# TOML: Indentation is purely cosmetic
[database]
host = "localhost"
    port = 5432  # Works fine, though unconventional

Type ambiguity:

# YAML: Is this a string or a number?
version: 1.0      # Parsed as float 1.0                                                                                                                                                                                                                                                                    
version: "1.0"    # Parsed as string "1.0"                                                                                                                                                                                                                                                                 
version: 1.0.0    # Parsed as string "1.0.0" (silently)    

# YAML: Octal numbers surprise
permissions: 0755  # Parsed as decimal 493 in YAML 1.1

# TOML: Explicit typing required
version = 1.0.0    # Parse error - invalid syntax                                                                                                                                                                                                                                                          
version = "1.0.0"  # String (must quote it)                                                                                                                                                                                                                                                                
count = 42         # Integer                                                                                                                                                                                                                                                                               
ratio = 3.14       # Float

NEON specifics:

# NEON: Entity syntax (used in Nette DI)
service: App\MyService(@dependency, %parameter%)

# NEON: Concise syntax works well for Nette-style configuration
# but entity syntax does not map directly to TOML

Here’s the same configuration expressed in all three formats:

# Application configuration
title = "My App"
version = "2.1.0"
debug = false

[database]
host = "localhost"
port = 5432
name = "myapp"
pool_size = 10

[database.credentials]
username = "admin"
password = "secret"

[cache]
driver = "redis"
ttl = 3600

[[servers]]
name = "alpha"
ip = "10.0.0.1"
roles = ["web", "api"]

[[servers]]
name = "beta"
ip = "10.0.0.2"
roles = ["worker"]

[logging]
level = "info"
format = "json"
created = 2024-01-15T10:30:00Z

# Application configuration
title: My App
version: "2.1.0"
debug: false

database:
  host: localhost
  port: 5432
  name: myapp
  pool_size: 10
  credentials:
    username: admin
    password: secret

cache:
  driver: redis
  ttl: 3600

servers:
  - name: alpha
    ip: 10.0.0.1
    roles:
      - web
      - api
  - name: beta
    ip: 10.0.0.2
    roles:
      - worker

logging:
  level: info
  format: json
  created: 2024-01-15T10:30:00Z

# Application configuration
title: My App
version: "2.1.0"
debug: false

database:
    host: localhost
    port: 5432
    name: myapp
    pool_size: 10
    credentials:
        username: admin
        password: secret

cache:
    driver: redis
    ttl: 3600

servers:
    - name: alpha
      ip: 10.0.0.1
      roles: [web, api]
    - name: beta
      ip: 10.0.0.2
      roles: [worker]

logging:
    level: info
    format: json
    created: 2024-01-15T10:30:00Z

Library Features

Full TOML 1.0/1.1 support with strict validation for keys, tables, strings, numbers, and datetimes. The project also publishes a support matrix for current coverage and known gaps.

Error recovery – Rather than stopping at the first problem, it can collect multiple errors. Useful for tooling and editor integrations:

$result = Toml::tryParse($tomlString);
foreach ($result->getErrors() as $error) {
    echo $error->format($tomlString);
}

Simple API for common operations:

$config = Toml::decodeFile('config.toml');
Toml::encodeFile('output.toml', $data);

Separate Lexer/Parser/AST – The architecture allows direct AST access for analysis without full evaluation.

No required extensions – Works out of the box on PHP 8.2+. The php-ds extension is optional for performance.

Error Recovery

When parsing invalid TOML, the library can continue past the first error and collect multiple problems. This is particularly valuable for editor integrations and linters where you want to surface all detected issues at once:

$result = Toml::tryParse($tomlString);

if ($result->hasErrors()) {
    foreach ($result->getErrors() as $error) {
        echo $error->format($tomlString);
    }
}

Each error includes line and column information, making it straightforward to report precise locations in CLI output or IDE diagnostics.

Working with the AST

For tools that need to analyze configuration structure without evaluating it, such as linters, formatters, or editor plugins, direct AST access is available:

use PhpCollective\Toml\Toml;
use PhpCollective\Toml\Ast\Table;
use PhpCollective\Toml\Ast\KeyValue;

$document = Toml::parse($tomlString);

foreach ($document->items as $node) {
    if ($node instanceof Table) {
        echo "Found table: " . implode('.', $node->key->parts) . "\n";
    } elseif ($node instanceof KeyValue) {
        echo "Found key: " . implode('.', $node->key->parts) . "\n";
    }
}

This separation means you can traverse the document structure, check for specific patterns, or even implement custom validation rules beyond what TOML itself requires.

Real-World Use Cases

Application configuration:

// config/app.toml
$config = Toml::decodeFile(__DIR__ . '/config/app.toml');

$dbHost = $config['database']['host'];
$cacheDriver = $config['cache']['driver'] ?? 'file';

Environment-specific settings:

$env = getenv('APP_ENV') ?: 'development';
$config = Toml::decodeFile(__DIR__ . "/config/{$env}.toml");

Reading Python project configuration:

// Parse a pyproject.toml to extract dependencies or metadata
$pyproject = Toml::decodeFile('/path/to/pyproject.toml');

$projectName = $pyproject['project']['name'];
$dependencies = $pyproject['project']['dependencies'] ?? [];
$pythonVersion = $pyproject['project']['requires-python'];

Plugin or package metadata:

# plugin.toml
[plugin]
name = "My Plugin"
version = "2.1.0"
author = "Jane Doe"

[plugin.requirements]
php = ">=8.2"
extensions = ["json", "mbstring"]

[[plugin.hooks]]
event = "beforeSave"
handler = "App\\Hooks\\ValidateData"

[[plugin.hooks]]
event = "afterSave"
handler = "App\\Hooks\\ClearCache"

Using TOML Inside Framework Apps

These examples are not all equivalent.

• CakePHP offers a real extension point for custom configuration engines.
• Symfony can consume TOML during container building, but TOML is not a first-class Symfony config format.
• Laravel can read TOML during bootstrapping, but its native config format remains PHP arrays in config/*.php.

CakePHP – Config engine integration:

// src/Configure/Engine/TomlConfigEngine.php
namespace App\Configure\Engine;

use Cake\Core\Configure\ConfigEngineInterface;
use Cake\Core\Exception\CakeException;
use PhpCollective\Toml\Toml;

class TomlConfigEngine implements ConfigEngineInterface
{
    protected string $path;

    public function __construct(string $path = CONFIG)
    {
        $this->path = $path;
    }

    public function read(string $key): array
    {
        $file = $this->path . $key . '.toml';

        if (!is_file($file)) {
            throw new CakeException("Could not load configuration file: {$file}");
        }

        return Toml::decodeFile($file);
    }

    public function dump(string $key, array $data): bool
    {
        $file = $this->path . $key . '.toml';

        return file_put_contents($file, Toml::encode($data)) !== false;
    }
}

// Register in bootstrap.php
Configure::config('toml', new TomlConfigEngine());
Configure::load('app_local', 'toml');

This is a proper CakePHP integration point because Configure is designed to work with custom engines.

Symfony – Custom parameter import pattern:

// src/DependencyInjection/TomlExtension.php
namespace App\DependencyInjection;

use PhpCollective\Toml\Toml;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\Extension;

class TomlExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container): void
    {
        $configFile = $container->getParameter('kernel.project_dir') . '/config/app.toml';

        if (file_exists($configFile)) {
            $tomlConfig = Toml::decodeFile($configFile);
            $container->setParameter('app.toml', $tomlConfig);
        }
    }
}

This can work in a bundle or application-specific extension, but it is still a custom pattern. Symfony’s standard configuration formats are YAML, XML, and PHP, so this is better framed as importing TOML-derived parameters than as native Symfony config loading.

Laravel – Boot-time import pattern:

// app/Providers/TomlConfigServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use PhpCollective\Toml\Toml;

class TomlConfigServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $tomlConfig = config_path('app.toml');

        if (file_exists($tomlConfig)) {
            config()->set('toml', Toml::decodeFile($tomlConfig));
        }
    }
}

This is useful when you want TOML-backed application settings inside a Laravel app, but it is not native Laravel config-file support. Keeping the imported data under a dedicated toml key avoids accidentally overwriting existing framework or package config keys.

Migrating from YAML or NEON

Converting existing configuration files is straightforward. Here’s a helper approach:

use PhpCollective\Toml\Toml;
use Symfony\Component\Yaml\Yaml;

// Load existing YAML
$yamlData = Yaml::parseFile('config.yaml');

// Write as TOML
Toml::encodeFile('config.toml', $yamlData);

For NEON (Nette):

use PhpCollective\Toml\Toml;
use Nette\Neon\Neon;

$neonContent = file_get_contents('config.neon');
$neonData = Neon::decode($neonContent);

// Filter out NEON-specific constructs like entities
// that don't translate directly to TOML
$cleanData = array_filter($neonData, fn($v) => !is_object($v));

Toml::encodeFile('config.toml', $cleanData);

Some things to watch for during migration:

• NEON entities (@service, %parameter%) have no TOML equivalent
• YAML anchors and aliases need to be expanded
• Deeply nested structures may become verbose in TOML
• Datetime literals need to match TOML’s RFC 3339-based syntax

Installation

composer require php-collective/toml

Requires PHP 8.2+. Optional: install php-ds extension for improved performance with large files.

Summary

TOML won’t replace YAML or NEON everywhere, but it has its place — especially when interoperating with tools that already use it. For PHP projects that need TOML support, this library provides a complete implementation.

Personally, I still reach for NEON or classic PHP arrays in most projects — for deeply nested configs, they’re simply more concise. TOML shines in flatter structures and cross-language tooling. What are you using?

Further Resources

• Library documentation
• TOML specification
• Interactive playground for testing

The Problem: Who Changed What, and Should They Have?

Every application that handles important data eventually faces the same questions:

• “Who deleted that customer record last week?”
• “Can we undo the changes made by that intern?”
• “We need an approval process before price changes go live”
• “The auditor wants to see every modification to financial records”

These aren’t edge cases. They’re fundamental requirements for any serious business application. Yet many frameworks leave you to implement these patterns from scratch, leading to inconsistent solutions scattered across your codebase.

CakePHP developers now have a comprehensive answer: Bouncer and AuditStash — two plugins that, together, provide complete data governance for your application.

Meet the Plugins

// In your Table class
public function initialize(array $config): void
{
    parent::initialize($config);

    $this->addBehavior('AuditStash.AuditLog', [
        'blacklist' => ['password', 'token'],
    ]);
}

// In your Table class
public function initialize(array $config): void
{
    parent::initialize($config);

    $this->addBehavior('Bouncer.Bouncer', [
        'actions' => ['add', 'edit', 'delete'],
    ]);
}

The Power of Combination

Here’s where it gets interesting. These plugins aren’t just useful individually — they’re designed to complement each other.

// AccountsTable.php
public function initialize(array $config): void
{
    parent::initialize($config);

    // Track ALL changes for compliance
    $this->addBehavior('AuditStash.AuditLog', [
        'blacklist' => ['internal_notes'],
    ]);

    // Require approval for modifications
    $this->addBehavior('Bouncer.Bouncer', [
        'actions' => ['edit', 'delete'],
        'bypassCallback' => function ($entity, $options) {
            // Auto-approve small changes by senior staff
            $user = $options['user'] ?? null;
            $isSenior = $user && $user->role === 'senior';
            $isSmallChange = abs($entity->balance - $entity->getOriginal('balance')) < 10000;

            return $isSenior && $isSmallChange;
        },
    ]);
}

// ArticlesTable.php
public function initialize(array $config): void
{
    parent::initialize($config);

    $this->addBehavior('AuditStash.AuditLog');
    $this->addBehavior('Bouncer.Bouncer', [
        'actions' => ['add', 'edit'],
    ]);
}

Writer submits article
       |
       v
  [Draft Created] --- AuditStash logs: "draft submitted"
       |
       v
Editor reviews diff
       |
    /     \
   v       v
Approve   Reject
   |         |
   v         v
Published  Writer notified
   |
   v
AuditStash logs: "approved and published"

// In your controller
$timeline = $this->AuditLogs->find('timeline', [
    'source' => 'articles',
    'primary_key' => $articleId,
]);

// Returns every change, who made it, when, and what changed

Real-World Features That Matter

# Export all audit data for a user
bin/cake audit_stash gdpr export --user 42 --output user-42-data.json

# Anonymize user's audit trail (keeps records, removes PII)
bin/cake audit_stash gdpr anonymize --user 42

# Or completely delete if required
bin/cake audit_stash gdpr delete --user 42

Original:    "Product costs $100"
User A:      "Product costs $120"  (pending)
User B:      "Product costs $95"   (pending)

Admin sees both proposals side-by-side and decides

// config/audit_stash.php
return [
    'AuditStash' => [
        'retention' => [
            'default' => '2 years',
            'financial_records' => false,  // Never delete
            'session_logs' => '30 days',
        ],
    ],
];

# Clean up old logs (respects retention policies)
bin/cake audit_stash cleanup --force

$this->addBehavior('AuditStash.AuditLog', [
    'ignoreTimestampOnly' => true,  // Skip if only modified changed
    'ignoreWhitespace' => true,     // Skip whitespace-only edits
    'ignoreFields' => ['view_count', 'last_accessed'],
]);

The Admin Interfaces

Both plugins ship with complete admin interfaces:

Getting Started

Installation is straightforward:

composer require dereuromark/cakephp-audit-stash
composer require dereuromark/cakephp-bouncer

Load the plugins:

// src/Application.php
public function bootstrap(): void
{
    parent::bootstrap();

    $this->addPlugin('AuditStash');
    $this->addPlugin('Bouncer');
}

Run migrations:

bin/cake migrations migrate --plugin AuditStash
bin/cake migrations migrate --plugin Bouncer

Add behaviors to your tables, and you’re protected.

Conclusion

Data governance isn’t optional anymore. Regulations like GDPR, SOX, and HIPAA demand accountability. Users expect undo functionality. Businesses need approval workflows.

AuditStash and Bouncer bring these enterprise patterns to CakePHP with minimal configuration:

• AuditStash answers “what happened?” with complete change tracking
• Bouncer answers “should this happen?” with approval workflows
• Together, they provide complete data governance for any CakePHP application

Both plugins have reached their 1.0.0 stable releases, ready for production use.

Links:

• https://github.com/dereuromark/cakephp-audit-stash
• https://github.com/dereuromark/cakephp-bouncer

The Reflection Tax

Modern PHP DTO libraries are clever. Too clever. They use runtime reflection to magically hydrate objects from arrays, infer types from docblocks, and validate on the fly. It’s beautiful—until you profile it.

Every. Single. Instantiation. Pays the reflection tax.

For a simple API endpoint returning 100 users? That’s 100 reflection calls. For a batch job processing 10,000 records? You’re burning CPU cycles on introspection instead of actual work.

And then there’s the IDE problem. Magic means your IDE is guessing. “Find Usages” becomes “Find Some Usages, Maybe.” PHPStan needs plugins. Autocomplete works… sometimes.

What If We Just… Generated the Code?

Here’s a radical idea: what if we did all that reflection once, at build time, and generated plain PHP classes?

Why Another DTO Library?

The PHP DTO landscape in 2026 looks like this:

• Native PHP 8.2+ readonly classes: Manual implementation
• spatie/laravel-data: Laravel-specific, runtime reflection
• cuyz/valinor: Framework-agnostic runtime mapper
• symfony/serializer: Component-based serialization

These are excellent tools, but they share a common limitation: runtime reflection overhead. Every time you create a DTO, the library inspects class metadata, parses types, and builds the object dynamically.

What if we did all that work once, at build time?

Basic concept

The idea is not that radical after all. Similar implementations have existed for more than 15 years, way before modern PHP and the new syntax and features it brought along. I have been using it for a bit more than 11 years now myself.

You decide on config as XML, YAML, NEON or PHP. PHP using builders is the most powerful one, as it has full auto-complete/type-hinting:

return Schema::create()
    ->dto(Dto::create('User')->fields(
        Field::int('id')->required(),
        Field::string('email')->required(),
        Field::dto('address', 'Address'),
    ))
    ->toArray();

Run the generator:

vendor/bin/dto generate

Get a real PHP class:

class UserDto extends AbstractDto
{
    public function getId(): int { /* ... */ }
    public function getEmail(): string { /* ... */ }
    public function getAddress(): ?AddressDto { /* ... */ }
    public function setEmail(string $email): static { /* ... */ }
    // ...
}

No magic. No reflection. Just PHP.

History

The concept was first used almost 2 decades ago in e-commerce systems that had a high amount of modular packages and basically disallowed all manual array usage. All had to be DTOs for maximum extendability and discoverability. The project could add fields per DTO as needed. The XMLs of each module as well as project extensions were all merged together. XML makes this easy, and the generated DTOs are fully compatible with both core and project level.

I never needed the “merging” feature, but I did like how quickly you could generate them, and that it could always generate full DTOs with all syntactic sugar as per current “language standards”.

Personally I always liked the XML style, because with XSD modern IDEs have full autocomplete and validation on them. But in some cases PHP might be more flexible and powerful.

Features That Matter

<dto name="User">
    <field name="id" type="int" required="true"/>
    <field name="email" type="string" required="true"/>
    <field name="roles" type="string[]" collection="true"/>
</dto>

$user = new UserDto();
$user->setName('John');
$user->setEmail('john@example.com');

$user = new UserDto(['name' => 'John']);
$updated = $user->withEmail('john@example.com');
// $user is unchanged, $updated has new email

Dto::immutable('Event')->fields(/* ... */);

// From snake_case database
$dto->fromArray($dbRow, false, UserDto::TYPE_UNDERSCORED);

// To camelCase for JavaScript
return $dto->toArray(); // default camelCase

// To snake_case for Python API
return $dto->toArray(UserDto::TYPE_UNDERSCORED);

<dto name="Order">
    <field name="items" type="OrderItem[]" collection="true" singular="item"/>
</dto>

$order->getItems();           // ArrayObject<OrderItemDto>
$order->addItem($itemDto);    // Type-checked
$order->hasItems();           // Collection not empty

$config->addSetting('theme', $settingDto);
$theme = $config->getSetting('theme');

Dto::setCollectionFactory(fn($items) => collect($items));

// Now all getters return Laravel collections
$order->getItems()->filter(...)->sum(...);

$company = new CompanyDto($data);

// Safe nested reading with default
$city = $company->read(['departments', 0, 'address', 'city'], 'Unknown');

// Deep cloning - nested objects are fully cloned
$clone = $company->clone();
$clone->getDepartments()[0]->setName('Changed');
// Original unchanged

vendor/bin/dto typescript --output=frontend/src/types/

export interface UserDto {
    id: number;
    email: string;
    name?: string;
    roles: string[];
}

export interface OrderDto {
    id: number;
    customer: UserDto;
    items: OrderItemDto[];
}

$dto = new UserDto();
$dto->setEmail('new@example.com');

$changes = $dto->touchedToArray();
// ['email' => 'new@example.com']

// Perfect for partial database updates
$repository->update($userId, $changes);

$email = $dto->getEmail();        // string|null
$email = $dto->getEmailOrFail();  // string (throws if null)

$email = $dto->getEmailOrFail(); // PHPStan now knows it is not nullable

<field name="id" type="int" required="true"/>

new UserDto(['name' => 'John']);
// InvalidArgumentException: Required fields missing: id

Dto::create('User')->fields(
    Field::string('name')->required()->minLength(2)->maxLength(100),
    Field::string('email')->required()->pattern('/^[^@]+@[^@]+\.[^@]+$/'),
    Field::int('age')->min(0)->max(150),
)

$rules = $dto->validationRules();
// ['name' => ['required' => true, 'minLength' => 2, 'maxLength' => 100], ...]

<field name="status" type="\App\Enum\OrderStatus"/>

// From enum instance
$order->setStatus(OrderStatus::Pending);

// From backing value - auto-converted
$order = new OrderDto(['status' => 'confirmed']);
$order->getStatus(); // OrderStatus::Confirmed

<field name="price" type="\Money\Money"/>
<field name="createdAt" type="\DateTimeImmutable"/>

Field::class('date', \DateTimeImmutable::class)->factory('createFromFormat')

Field::string('email')
    ->transformFrom('App\\Transform\\Email::normalize')  // Before hydration
    ->transformTo('App\\Transform\\Email::mask')         // After serialization

Dto::create('BaseEntity')->fields(
    Field::int('id')->required(),
    Field::class('createdAt', \DateTimeImmutable::class),
)

Dto::create('User')->extends('BaseEntity')->fields(
    Field::string('email')->required(),
)
// UserDto has id, createdAt, and email

// UserDto with fields: id (int, required), name (string), email (string, required)
/**
 * @return array{id: int, name: string|null, email: string}
 */
public function toArray(?string $type = null, ?array $fields = null, bool $touched = false): array

vendor/bin/dto jsonschema --output=schemas/

Real-World Patterns

class UserController
{
    public function show(int $id): JsonResponse
    {
        $user = $this->repository->find($id);
        $dto = UserDto::createFromArray($user->toArray());

        // Snake case for JSON API
        return new JsonResponse($dto->toArray(UserDto::TYPE_UNDERSCORED));
    }
}

public function update(Request $request, int $id): Response
{
    $dto = new UserDto();
    $dto->fromArray($request->all(), false, UserDto::TYPE_UNDERSCORED);

    // Only update fields that were actually submitted
    $this->repository->update($id, $dto->touchedToArray());

    return new Response('Updated');
}

$event = new OrderPlacedDto([
    'eventId' => Uuid::uuid4()->toString(),
    'aggregateId' => $orderId,
    'occurredAt' => new DateTimeImmutable(),
    'order' => $orderDto,
]);

// Create corrected version without mutating original
$corrected = $event->withVersion(2);

Performance: The Numbers

We ran comprehensive benchmarks comparing php-collective/dto against plain PHP, spatie/laravel-data, and cuyz/valinor. Test environment: PHP 8.4.17, 10,000 iterations per test.

Versions used: php-collective/dto dev-master (e4e1f9c), spatie/laravel-data 4.19.1, cuyz/valinor 2.3.2. A standalone comparison also includes spatie/data-transfer-object 3.9.1 and symfony/serializer 8.0.5.

Simple DTO Creation (ops/sec, higher is better):
┌──────────────────────────────────────────────────────────────────┐
│ Plain PHP        ████████████████████████████████████    3.64M/s │
│ php-collective   ██████████████████                      1.68M/s │
│ laravel-data     █                                       67.7K/s │
│ valinor          █                                       63.4K/s │
└──────────────────────────────────────────────────────────────────┘

Complex Nested DTO (ops/sec, higher is better):
┌──────────────────────────────────────────────────────────────────┐
│ Plain PHP        ██████████████████████████████████       571K/s │
│ php-collective   ███████████████████                      322K/s │
│ laravel-data     ████                                    20.5K/s │
│ valinor          ███                                     14.6K/s │
└──────────────────────────────────────────────────────────────────┘

When to Use php-collective/dto

Choose php-collective/dto when:

• Performance matters (API responses, batch processing)
• You want excellent IDE and static analysis support
• You prefer configuration files over code attributes
• You need both mutable and immutable DTOs
• You work with different key formats
• You want to share types with TypeScript frontends
• You value reviewable, inspectable generated code

Consider alternatives when:

• You’re already deep in Laravel and want framework integration (laravel-data)
• You need advanced validation like conditional rules or cross-field dependencies
• You want runtime-only, no build step (valinor)

Summary

php-collective/dto brings the best of code generation to PHP DTOs:

The library is framework-agnostic, well-documented, and actively maintained.

For many apps the performance overhead of reflection might not be relevant. After all, you might only have a few DTOs per template for simpler actions. But in the case that you are handling a huge amount of DTOs, a less magic way could be a viable option. At least it will be more efficient than trying to nano-optimize on other parts of the application.

Migration Path: From Arrays to DTOs

Adopting DTOs doesn’t have to be a big-bang rewrite. Here’s a practical, incremental path from raw arrays to fully typed DTOs — each step delivers value on its own.

// Controller
public function view(int $id): Response
{
    $user = $this->Users->get($id, contain: ['Addresses', 'Roles']);
    $data = $user->toArray();

    // Pass array to service
    $summary = $this->buildSummary($data);

    return $this->response->withJson($summary);
}

private function buildSummary(array $data): array
{
    return [
        'full_name' => $data['first_name'] . ' ' . $data['last_name'],
        'city' => $data['address']['city'] ?? 'Unknown',  // exists?
        'role_count' => count($data['roles'] ?? []),       // array?
    ];
}

// Define the DTO config
Dto::create('UserSummary')->fields(
    Field::string('fullName')->required(),
    Field::string('city'),
    Field::int('roleCount'),
);

vendor/bin/dto generate

// Controller — only the return type changes
public function view(int $id): Response
{
    $user = $this->Users->get($id, contain: ['Addresses', 'Roles']);

    $summary = new UserSummaryDto([
        'fullName' => $user->first_name . ' ' . $user->last_name,
        'city' => $user->address?->city,
        'roleCount' => count($user->roles),
    ]);

    return $this->response->withJson($summary->toArray());
}