DerEuroMark View RSS

What actually changed

Two things had to line up: the framework had to declare the generics, and the tooling had to emit the matching doc-blocks.

// config/app.php (or app_local.php)
'IdeHelper' => [
    'genericsInParam' => true,
    'concreteEntitiesInParam' => 'strict',
],

/**
 * @method \App\Model\Entity\User saveOrFail(\App\Model\Entity\User $entity, array $options = [])
 */

/**
 * @method \App\Model\Entity\User saveOrFail(\App\Model\Entity\User $entity, array<string, mixed> $options = [])
 */

The last gap

Flipping the switch got us most of the way. One small leak remained, fixed upstream:

• Helper base class. The annotator never emitted an extends tag, so every helper tripped missingType.generics on TView. It now prepends @extends \Cake\View\Helper<\Cake\View\View> – gated by a runtime reflection check on the parent, so it self-disables on older cores instead of emitting an invalid generic.

One LSP gotcha worth remembering

When you override a framework method, you cannot narrow a parameter type below the parent’s. A bare array in the parent is effectively array<array-key, mixed>, so an override typed array<string, mixed> raises method.childParameterType:

Parameter #1 … should be contravariant with parameter … of method …::beforeFilter()

The fix is to use the equal type, not a narrower one:

/**
 * @param \Cake\Event\EventInterface<\Cake\Controller\Controller> $event
 */
public function beforeFilter(EventInterface $event) { /* ... */ }

// and for plain array overrides, prefer the wide form:
// @param array<mixed> $config   (not array<string, mixed>)

array<mixed> still satisfies missingType.iterableValue while staying contravariant with the parent. Best of both.

The result

My sandbox app went from 383 errors to 0 at PHPStan level 8 with phpstan-strict-rules and type-perfect enabled – and crucially, with the two blanket ignores removed:

     ignoreErrors:
-        - identifier: missingType.generics
-        - identifier: missingType.iterableValue
         - identifier: new.internalClass

CakePHP now joins Symfony/Doctrine in clean level-8-with-generics territory, and goes further by auto-generating the annotations via IdeHelper.
And we are light-years ahead of other major PHP frameworks that are still on PHPStan level 1-5. CakePHP ships with a clean architecture, no hidden magic or anti-patterns and enables developers the right way.
PHPStan level 8+ on core and app level ensures the highest possible code quality and developer experience and literally prevents bugs and security issues before they happen.

Flip the switch, re-annotate, delete the ignores and enjoy one of the leading rapid application development frameworks in the ecosystem.

The pipeline: build, resolve, render

The mental model is three steps, in order:

flowchart LR
    A["1 · Build<br/>tree"] --> B["2 · Resolve<br/>per-request"] --> C["3 · Render<br/>markup"]

Build declares what is in the menu — labels, links, icons, badges, nested submenus. It knows nothing about the current request or the logged-in user. Resolve takes the built tree and applies per-request state on top: which item is active, which branch is an ancestor of the active item, which items are visible to this user. Render turns the resolved tree into output.

The split matters because it’s what makes the same menu definition reusable. A menu you define once at boot time is resolved fresh for every request and rendered into whatever shape that page needs — a sidebar here, a breadcrumb there, JSON for the SPA tab on the same page.

Building: PHP, arrays, or a database row

The common case is fluent PHP:

use Menu\Menu;

$menu = Menu::create(['class' => 'nav nav-pills']);
$menu->addItem('Home', '/');
$menu->addItem('Docs', 'https://book.cakephp.org', [
    'attributes' => ['target' => '_blank', 'rel' => 'noopener'],
]);

$account = $menu->addItem('Account', '#');
$account->getSubMenu()->addItem('Profile', ['controller' => 'Users', 'action' => 'profile']);
$account->getSubMenu()->addItem('Logout',  ['controller' => 'Users', 'action' => 'logout']);

A link can be a string URL or a CakePHP array URL. The array form is almost always the better choice: the Router resolves base paths, plugins, and prefixes for you, which means active matching keeps working in subdirectory installs and across plugin remounts. The string form is there for external links and the odd hard-coded edge case.

A few things you get out of the box, with no extra helpers:

• Section headers (addHeader) render as a non-link <li> — perfect for grouping a sidebar.
• Dividers (addDivider) render the <hr> / separator semantic without you handling escape rules.
• Icons and badges are first-class options, not strings you smuggle through the label.
• displayChildren = false renders the item as a leaf even when it has a submenu — useful when an admin section has child items that shouldn’t appear in the chrome but should still resolve as active.

For larger setups you can skip the PHP entirely:

$menu = Menu::fromArray([
    'attributes' => ['class' => 'nav'],
    'items' => [
        ['label' => 'Articles', 'link' => '/articles', 'submenu' => [
            'items' => [['label' => 'View', 'link' => '/articles/view']],
        ]],
    ],
]);

// rows: [['id' => 1, 'parent_id' => null, 'label' => 'Articles', 'link' => '/articles'], ...]
$menu = Menu::fromFlat($rows);

fromFlat() is the one I get the most mileage out of in CMS-style apps — a single menu_items table with parent_id self-references, edited in an admin UI, materialised back into a real tree on each render. The inverse — Menu::toArray() — round-trips back to the same shape that fromArray() accepts, so a built menu can be cached, serialised, or shipped over the wire.

Tree manipulation: reorder, move, merge, split

Building a menu is rarely a one-shot operation. The most common reason you reach for this plugin in the first place is “plugin X wants to add an item to menu Y, after the third entry, but only if the user is staff”. So the API for re-arranging items after they exist is first-class:

// Insert relative to a sibling (id or key):
$menu->insertBefore($menu->newItem('What\'s New', '/changelog'), 'articles');
$menu->insertAfter($menu->newItem('Beta', '/beta'), 'home');

// Move an existing item to a specific slot:
$menu->moveToFirstPosition('account');
$menu->moveToLastPosition('logout');
$menu->moveToPosition('articles', 2);

// Reorder by id/key (unlisted items keep their order, appended after):
$menu->reorder(['home', 'articles', 'account']);

// Sort, filter, and find across direct children:
$menu->sortBy('weight');
$menu->filter(fn ($item) => $item->isVisible());
$items = $menu->find(fn ($item) => str_starts_with($item->getLabel() ?? '', 'Admin'));

// Active state lookups:
$current = $menu->getActiveItem();
$menu->clearActive();

Two operations that show up in surprising places:

• merge($other) deep-copies another menu’s items into this one. The source stays intact, so you can keep a master menu and merge slices into per-page composites without aliasing bugs.
• slice($offset, $length) and split($at) give you derived menus by copy. “Render this menu as a two-column dropdown” becomes:

['primary' => $left, 'secondary' => $right] = $menu->split(4);

Pair these with the tree-integrity guarantees and you can rearrange aggressively without the “why is this item rendering twice” class of bug ever showing up.

Named menus and the helper

The helper lets you register menus by name once and render them many times:

$this->Menu->register('main', static function ($menu): void {
    $menu->addItem('Home', '/');
    $menu->addItem('Articles', ['controller' => 'Articles', 'action' => 'index']);
});

echo $this->Menu->render('main');

register() is idempotent by default — calling it twice returns the same menu — so you can scatter the call across templates and elements without worrying about double-registration. Pass ['rebuild' => true] if you actually want to wipe and rebuild.

// Named-menu lifecycle:
$main = $this->Menu->getOrCreate('main');
$this->Menu->has('main');
$this->Menu->remove('main');
$this->Menu->reset(); // wipe every named menu

// Active item + path (after resolution):
$current = $this->Menu->getCurrentItem('main');
$path = $current ? $this->Menu->extractPath($current) : [];

// Breadcrumbs — three flavours depending on where you want to render:
$crumbs = $this->Menu->getBreadcrumbs('main'); // plain array
$this->Menu->populateBreadcrumbs('main'); // push into CakePHP's BreadcrumbsHelper
echo $this->Menu->renderBreadcrumbs('main'); // render directly via BreadcrumbRenderer

Resolvers: active state and visibility, without if-trees in your menu code

The resolver layer is where I think the plugin earns its keep. Instead of every menu helper sprouting a giant match over controllers and actions, you compose a small ResolverCollection. The bundled resolvers cover most apps out of the box:

Compose them in any order:

use Menu\Resolver\Psr7UrlResolver;
use Menu\Resolver\UrlArrayResolver;
use Menu\Resolver\SectionResolver;
use Menu\Resolver\LoggedInResolver;
use Menu\Resolver\AuthorizationResolver;

$resolvers = (new \Menu\Resolver\ResolverCollection())
    ->add(new UrlArrayResolver($request)) // active state
    ->add(new SectionResolver($request)) // also active state (section badges)
    ->add(new LoggedInResolver($identity)) // visibility
    ->add(new AuthorizationResolver(fn ($item) =>
        is_array($item->getLink()?->getRawUrl())
            ? $this->AuthUser->hasAccess($item->getLink()->getRawUrl())
            : null,
    ));

Each resolver inspects every item, mutates runtime state (active, visible, expanded), and hands the tree to the next one. Order matters — later resolvers see what earlier ones decided — but the structure of the tree never changes. Re-render the same menu for a different request and the previous active state is overwritten cleanly.

A couple of well-loved options that ride on top:

• singleActive => true — when several items match the current URL (a parent and a child both pointing at the same route, for example), keep only the deepest visible match active. Breaks ties by document order so the active trail is unambiguous.
• hideEmptyBranches => true — if an authorization resolver hides every leaf under a parent, skip the now-empty dropdown instead of rendering a hollow chevron.
• additionalResolvers — the helper applies the URL resolvers automatically; this option lets you tack extras on without losing the defaults.

The TinyAuth recipe is the one that gets people most excited:

use Menu\Item\ItemInterface;
use Menu\Resolver\AuthorizationResolver;

echo $this->Menu->render('admin', [
    'hideEmptyBranches' => true,
    'additionalResolvers' => [
        new AuthorizationResolver(function (ItemInterface $item): ?bool {
            $url = $item->getLink()?->getRawUrl();

            return is_array($url) ? $this->AuthUser->hasAccess($url) : null;
        }),
    ],
]);

A single menu definition, no role-aware branches in the template, and every user sees exactly the items they can actually reach.

// Named CakePHP routes — works against Router::url(['_name' => ...]):
$menu->addItem('View', ['_name' => 'articles:view']);

// Fuzzy / prefix matching — /articles/view/42 still marks /articles/view active:
$menu->addItem('Articles', ['controller' => 'Articles', 'action' => 'view'], [
    'fuzzy' => true,
]);

// Alternate routes — mark this item active for any of these too:
$menu->addItem('Inbox', ['controller' => 'Messages', 'action' => 'index'], [
    'matchRoutes' => [
        ['controller' => 'Messages', 'action' => 'unread'],
        ['controller' => 'Messages', 'action' => 'starred'],
    ],
]);

// Per-item override of query-string handling:
$menu->addItem('Search', '/search', ['ignoreQueryString' => true]);

Renderers: pick the shape, keep the tree

A renderer never decides active state or visibility. It only reflects what resolution already decided. That means swapping renderers is a per-call choice, not a refactor:

echo $this->Menu->render($menu); // string template
echo $this->Menu->render($menu, ['renderer' => Bootstrap5Renderer::class]);
echo $this->Menu->render($menu, ['renderer' => NavbarRenderer::class]);
echo $this->Menu->render('sidebar', ['renderer' => Bootstrap5SidebarRenderer::class]);
echo $this->Menu->render($menu, ['renderer' => JsonRenderer::class, 'pretty' => true]);
echo $this->Menu->renderBreadcrumbs('main');

The bundled renderers all emit accessible markup out of the box — aria-current="page" on the active label, aria-expanded on collapsible branches, the right role attributes on nav / menubar / menuitem. The sidebar wires each branch to its collapse element through a unique id so it works with the stock Bootstrap bundle and zero custom JavaScript.

The distinction between Bootstrap5Renderer and NavbarRenderer is worth calling out: Bootstrap5Renderer emits the inner <ul class="nav"> and expects you to wrap it. NavbarRenderer emits the whole <nav> chrome — brand, responsive navbar-toggler, the collapsible navbar-nav, and dropdowns for nested items. Drop it straight into a layout and you have a working top bar; no extra markup, no Bootstrap JS glue.

If none of them fit, the renderer interface is small enough that a custom one is an afternoon’s work — and per-call template overrides let you tweak just the bits you care about without subclassing.

A small detour: keeping the tree honest

The pipeline is only as trustworthy as the data structure under it. A menu is a tree of items, and trees are easy to corrupt by accident — the same item attached to two parents, a removed item that still thinks it has a parent, a child added back to its own grandchild’s submenu. The plugin used to let you do all of these. It didn’t lie, exactly, but the failure modes were quiet: the wrong branch rendered, the wrong item resolved as active, a stale reference held the old parent’s classes.

A recent round of PRs tightened this up.

Direct menu ownership. Items now know which Menu they were last attached to. Move an item across menus and the source forgets it; the destination claims it. That single invariant rules out the “item belongs to A but lives in B’s tree” class of bug.

Detach on move. add() / insertBefore() / insertAfter() now detach the item from its previous parent before reattaching. Before this, moving an item into a different submenu left it attached to the old one as a phantom — most renderers happily rendered it twice.

Explicit detach(). If you hold a reference to an attached item and want to move or reuse it elsewhere, you say so:

$item->detach();
$otherMenu->add($item);

The fluent setter is part of ItemInterface, so editor tooling surfaces it the moment you start typing.

Cycle checks. Adding an item into its own descendant subtree now throws instead of producing a RuntimeException deep in the renderer (where the stack trace is nine frames away from your actual mistake).

Fail loudly on misses. remove() and removeByKey() now throw when the id or key doesn’t exist, instead of silently returning. The old swallow-and-continue behaviour was a footgun every time you renamed an item: the removal silently did nothing and the menu kept showing the old entry.

Things you only notice once you’ve used it for a week

• Menu::collect() returns an ItemCollection over the whole tree depth-first, so you can findById, findByKey, or findByParent without recursing by hand.
• Menu::merge(), Menu::slice(), Menu::split() give you derived menus by copy — the source stays intact, which means “render this menu as two columns” is two method calls.
• freeze() locks the structure of a menu but leaves runtime resolver state mutable. Useful when you want to publish a built menu from a service and have application code resolve it without accidentally adding items.
• bin/cake menu generate Main writes a config/menu_main.php spec under the Menu.menus Configure key. The helper auto-registers anything it finds there on initialize(), so $this->Menu->render('main') works without any wiring in AppView.
• The default Bootstrap5Renderer honours per-item displayChildren = false on the anchor itself, not just the submenu, so admin chrome stays clean when you only want the parent clickable.

Why it’s small on purpose

The plugin has no runtime dependencies beyond CakePHP itself, ships on PHPStan level 8, and the entire test suite runs in under a second. That’s deliberate — a menu plugin should never be the thing that pushes you onto a higher Cake or PHP minimum, and it should never be the thing that slows your test suite down. The trade is that everything beyond the bundled renderers and resolvers is yours to write, but the interfaces are small enough that you’ll be writing fifty-line classes, not three-hundred-line subclasses.

Get it

composer require dereuromark/cakephp-menu
bin/cake plugin load Menu

Full docs, including the recipes catalogue, live at https://dereuromark.github.io/cakephp-menu/. The live sandbox is the fastest way to see the renderers side-by-side before you wire it into your app.

If you maintain a CakePHP app and you’ve got a hand-rolled MenuHelper lying around, this is the plugin you can replace it with — and once the build / resolve / render split clicks, you’ll wonder why you kept reinventing it.

The problem: a locked door with no doorbell

Put yourself in a researcher’s shoes. You notice an exposed endpoint on a site. You want to do the right thing and report it privately. So you start hunting:

• Is there a /security page? Usually not.
• A security@ mailbox? Maybe, maybe monitored.
• A contact form? It caps your message at 500 characters and eats attachments.
• The company on social media? Now you are discussing a vulnerability in public.

Every dead end raises the odds of one of two bad outcomes: the reporter gives up, or the details end up somewhere public. Neither is what you want.

What security.txt is (RFC 9116)

security.txt is a small, plain-text file described by RFC 9116, “A File Format to Aid in Security Vulnerability Disclosure” (Informational, 2022, by Edwin Foudil and Yakov Shafranovich). You serve it over HTTPS as text/plain at a well-known location:

https://example.com/.well-known/security.txt

Inside, it is just Field: value lines. Two fields are required, the rest are optional:

A couple of details matter in practice:

• Order does not matter between different fields. The one exception: multiple Contact lines are read top-down as order of preference.
• Expires is the trap. It must be a date in the future. A security.txt you wrote two years ago and forgot is, by the spec, stale — and a stale file signals an inattentive team.

Why a standard at all? Because researchers should not have to reverse-engineer your org chart. One predictable path, machine-readable, that scanners and humans both know to check.

Why it matters: lower the barrier, route to the right channel

security.txt is cheap to add and pays off in two ways.

It reduces friction. The faster a finder can reach the right inbox, the more likely they report at all — and the less likely the issue leaks while they search. You are removing excuses for public disclosure.

It routes people to the proper channel. This is the part teams underrate. “Proper channel” means private, monitored, and expected:

• A private intake (a dedicated mailbox, or GitHub’s private vulnerability reporting) instead of a public issue tracker.
• A stated Policy so the reporter knows what to expect: do you offer safe harbor? A disclosure timeline? Credit?
• A real human on the other end who has agreed to receive these.

Make that path obvious and you turn a potential zero-day-on-Twitter into a quiet, coordinated fix. That is the whole game: make auditing and reporting easy, and make the easy path the safe one.

Our take: a CakePHP middleware that never goes stale

We wanted security.txt on our CakePHP apps, but a static file has that Expires problem — somebody has to remember to bump the date forever. So we built it as a small PSR-15 middleware in the cakephp-setup plugin (3.21.0+).

See it in action: sandbox.dereuromark.de/.well-known/security.txt

A few design choices made it pleasant to use:

• It is a middleware, not a route. The file is public and fixed-shape, so it short-circuits the request before routing and authentication ever run. No controller, no route entry, no auth exceptions.
• Expires is computed on every request. By default it is “one year from now”, so it is always valid. The maintenance problem simply disappears.
• Config is a typed value object. You describe the document with a SecurityTxt object — named arguments, IDE autocomplete, and type checks — instead of a loose array of magic strings.
• Contact is enforced. Since RFC 9116 requires it, the object throws if you forget it. Misconfiguration fails at boot, not silently at runtime.

Wiring it up is one call in your application’s middleware stack:

use Setup\Middleware\SecurityTxt;
use Setup\Middleware\SecurityTxtMiddleware;

public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    $middlewareQueue->add(new SecurityTxtMiddleware(new SecurityTxt(
        contact: 'https://github.com/owner/repo/security/advisories/new',
        canonical: 'https://example.com/.well-known/security.txt',
        policy: 'https://github.com/owner/repo/security/policy',
        preferredLanguages: 'en, de',
    )));

    // ... the rest of your stack

    return $middlewareQueue;
}

That serves the following at both /.well-known/security.txt and the legacy /security.txt, with a fresh Expires on every hit:

Contact: https://github.com/owner/repo/security/advisories/new
Policy: https://github.com/owner/repo/security/policy
Canonical: https://example.com/.well-known/security.txt
Preferred-Languages: en, de
Expires: 2027-05-23T00:00:00.000Z

Other niceties: HEAD requests return headers without a body, path matching is base-path aware (so it works for apps mounted in a subdirectory), and there is a raw-array escape hatch for fields the value object does not cover yet.

Pair it with a SECURITY.md

If you have an open (Git) repository for your project, this can be an additional help.

security.txt says where to report; a SECURITY.md says how and what to expect. On GitHub, a SECURITY.md (in the repo root, .github/, or docs/) is rendered at /security/policy and surfaced in the repo’s Security tab — which is exactly what the Policy field above points to.

The two reinforce each other:

• Contact points at GitHub’s private vulnerability reporting, not a public issue.
• Policy points at SECURITY.md, which spells out the process and timeline.

Now both a scanner and a human land in the same private, expected place.

Try it today

Adding security.txt is one of the highest-leverage, lowest-effort things you can do for the security posture of a public app. It is a handful of lines, and it tells the world you want to hear about problems.

• Read the standard: RFC 9116
• Generate or validate a file: securitytxt.org
• CakePHP users: the security.txt middleware docs

Make the door easy to find, put a doorbell on it, and answer when it rings.

Agnostic middleware code

The PSR-15 middleware can easily be ported to any PSR-15-compatible framework. Adjust it by copy and paste into your ecosystem if needed (middleware + DTO). The Response class would need to be replaced by whatever you might be using. Also the InstanceConfigTrait usage. Here a possibly agnostic version:

<?php

declare(strict_types=1);

/**
 * Serves an RFC 9116 security.txt. Pure PSR-15 + PSR-17: it depends only on the
 * injected factories, so it runs in any compliant stack.
 *
 * The required `Expires` field is computed on every request, so it never goes
 * stale. `Contact` is required; constructing without one throws.
 */
class SecurityTxtMiddleware implements MiddlewareInterface
{
    /** @var array<string, string|array<string>> */
    private array $fields;

    private string $expiresInterval;

    public function __construct(
        SecurityTxt $document,
        private readonly ResponseFactoryInterface $responseFactory,
        private readonly StreamFactoryInterface $streamFactory,
        private readonly string $path = '/.well-known/security.txt',
        private readonly bool $serveRootFallback = true,
        private readonly int $cacheMaxAge = 86400, // 1 day; was CakePHP's DAY constant
    ) {
        $this->fields = $document->toFields();
        $this->expiresInterval = $document->expiresInterval;

        if (SecurityTxt::normalize($this->fields['Contact'] ?? null) === []) {
            throw new InvalidArgumentException(
                'SecurityTxtMiddleware requires at least one non-empty Contact field (RFC 9116).',
            );
        }
    }

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $method = $request->getMethod();
        if ($method !== 'GET' && $method !== 'HEAD') {
            return $handler->handle($request);
        }

        if (!$this->matches($this->relativePath($request))) {
            return $handler->handle($request);
        }

        $rendered = $this->render();

        $response = $this->responseFactory->createResponse()
            ->withHeader('Content-Type', 'text/plain; charset=utf-8')
            ->withHeader('Content-Length', (string)strlen($rendered)); // correct even for HEAD

        if ($this->cacheMaxAge > 0) {
            $response = $response->withHeader('Cache-Control', 'max-age=' . $this->cacheMaxAge);
        }

        // HEAD: same headers as GET, but no body.
        $body = $method === 'HEAD' ? '' : $rendered;

        return $response->withBody($this->streamFactory->createStream($body));
    }

    private function matches(string $path): bool
    {
        return $path === $this->path
            || ($this->serveRootFallback && $path === '/security.txt');
    }

    /**
     * Resolve the request path relative to the application base path. The `base`
     * attribute is set by some frameworks (e.g. CakePHP) for subdirectory installs;
     * elsewhere getAttribute() returns '' and this is a pure-PSR-7 no-op.
     */
    private function relativePath(ServerRequestInterface $request): string
    {
        $path = $request->getUri()->getPath();
        $base = (string)$request->getAttribute('base', '');
        if ($base !== '' && str_starts_with($path, $base)) {
            $path = substr($path, strlen($base));
        }

        return $path !== '' ? $path : '/';
    }

    private function render(): string
    {
        $lines = [];
        foreach (SecurityTxt::normalize($this->fields['Contact'] ?? null) as $contact) {
            $lines[] = 'Contact: ' . $contact;
        }
        foreach ($this->fields as $name => $value) {
            if ($name === 'Contact' || $name === 'Expires') {
                continue;
            }
            foreach (SecurityTxt::normalize($value) as $item) {
                $lines[] = $name . ': ' . $item;
            }
        }
        $lines[] = 'Expires: ' . $this->expires();

        return implode("\n", $lines) . "\n";
    }

    private function expires(): string
    {
        $timestamp = strtotime($this->expiresInterval) ?: strtotime('+1 year');

        return gmdate('Y-m-d\TH:i:s.000\Z', (int)$timestamp);
    }
}

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;
        },
    ]);
}