The 30-second version

Install it, load it, use your existing FormHelper calls:

composer require dereuromark/cakephp-tailwind-ui
bin/cake plugin load TailwindUi

In AppView:

use TailwindUi\View\UiViewTrait;

class AppView extends View
{
    use UiViewTrait;

    public function initialize(): void
    {
        parent::initialize();
        $this->initializeUi();
    }
}

That’s it. Every call you already have — $this->Form->control(), $this->Paginator->links(), $this->Flash->render(), $this->Html->badge() — now outputs DaisyUI-styled markup. Your templates don’t change.

Why another UI plugin?

The easy answer is “because the old one targets the wrong framework.” The real answer is that I wanted to test an idea: what if the class names weren’t hardcoded anywhere?

Bootstrap-ui has form-control and btn btn-primary baked into its templates, helpers, and widgets. If you want anything else — DaisyUI, KTUI, Flowbite, your company’s design system — you fork. Every time. And re-fork on every bootstrap-ui update.

TailwindUi takes a different approach: there’s exactly one map between semantic names and CSS classes, and you can replace it at runtime.

// config/bootstrap.php
Configure::write('TailwindUi.classMap', 'daisyui'); // default, can be omitted

That’s it. Want KTUI (Metronic)?

Configure::write('TailwindUi.classMap', 'ktui');

Want to override just one key without copying the rest?

Configure::write('TailwindUi.classMap', [
    'form.input' => 'input input-bordered input-lg w-full',
    'btn.primary' => 'btn-primary shadow-lg',
]);

Or use a preset plus overrides:

Configure::write('TailwindUi.classMap', 'ktui');
Configure::write('TailwindUi.classMapOverrides', [
    'btn.primary' => 'kt-btn-primary kt-btn-lg',
]);

The plugin ships two presets (daisyui and ktui) and accepts any PHP file in config/class_maps/ as a custom preset. Want a shadcn preset for your app? Write the 20 keys that differ. Everything else falls through to the DaisyUI defaults.

What you get — and where it’s actually better

When you drop TailwindUi in for bootstrap-ui, most things produce visually equivalent output. But there are a few spots where TailwindUi is measurably cleaner, and I think they’re worth calling out.

<div class="form-check">
    <input type="checkbox" name="tags[]" value="1" class="form-check-input" id="tags-1">
    <label class="form-check-label" for="tags-1">PHP</label>
</div>

<div class="mt-1 [&>label]:inline-flex [&>label]:items-center [&>label]:gap-2 [&>label]:cursor-pointer">
    <label for="tags-1">
        <input type="checkbox" name="tags[]" value="1" class="checkbox" id="tags-1">
        PHP
    </label>
</div>

Configure::write('TailwindUi.classMapOverrides', [
    'btn.primary' => 'btn-primary shadow-sm',
]);

<button onclick="this.closest('[role=alert]').remove()">×</button>

// Dark theme for admin area, default for front-end
if ($this->request->getParam('prefix') === 'Admin') {
    Configure::write('TailwindUi.classMap', 'ktui');
}

The ClassMap — actually, what’s in there?

The full map is ~60 keys in config/class_maps/daisyui.php. A taste:

return [
    // Form inputs
    'form.input'              => 'input input-bordered w-full',
    'form.select'             => 'select select-bordered w-full',
    'form.textarea'           => 'textarea textarea-bordered w-full',
    'form.checkbox'           => 'checkbox',
    'form.radio'              => 'radio',
    'form.switch'             => 'toggle',
    'form.label'              => 'label-text',
    'form.helpText'           => 'label-text-alt text-base-content/60',
    'form.error'              => 'text-error text-sm mt-1',
    'form.inputError'         => 'input-error',
    'form.container'          => 'mb-4',
    'form.containerHorizontal'=> 'flex items-start gap-4 mb-4',
    'form.labelHorizontal'    => 'w-48 pt-2 shrink-0 text-right',

    // Buttons
    'btn'          => 'btn',
    'btn.primary'  => 'btn-primary',
    'btn.danger'   => 'btn-error',
    'btn.outline'  => 'btn-outline',
    // ...

    // Pagination, alerts, breadcrumbs, cards, tables, icons...
];

Every helper reads from this map. When you call $this->Form->control('title'), the FormHelper asks for form.input and form.container and composes the right HTML. When you call $this->Html->badge('Active', ['class' => 'success']), the HtmlHelper strips success, reads badge.success, and emits badge badge-success.

That’s the entire design. There’s no inheritance hierarchy, no service locator, no factory pattern. It’s a config array.

What about KTUI / Metronic?

The plugin was actually born out of a Metronic v9 project. Metronic ships with KTUI — Keenthemes’ Tailwind component library — which uses classes like kt-input, kt-btn kt-btn-primary, kt-card, kt-badge kt-badge-success. Completely different naming from DaisyUI, same idea.

To use it, set one config key:

Configure::write('TailwindUi.classMap', 'ktui');

The plugin then emits <input class="kt-input">, <button class="kt-btn kt-btn-primary">, etc. The helper API, your templates, your controllers — all unchanged.

There’s one honest caveat: KTUI isn’t on a CDN and isn’t purely a CSS file. Metronic’s styles.css is Tailwind v4 tree-shaken against Metronic’s own source files, so classes Metronic didn’t use (like bg-yellow-50 or arbitrary variants) aren’t in the compiled bundle. If you’re building a real KTUI app, you’d compile Tailwind v4 yourself against your own template sources and everything the plugin emits gets picked up.

The plugin ships a ktui layout (templates/layout/ktui.php) that initializeUi() auto-selects when the KTUI preset is active, so you don’t have to juggle that manually.

Bake theme

Because this is a FriendsOfCake-style plugin, it has a bake theme:

bin/cake bake template Articles --theme TailwindUi

This generates index.php, view.php, add.php, and edit.php with DaisyUI-styled cards, zebra tables, pagination, and action buttons. The templates use the plugin’s helpers, which means they automatically work with any preset. Bake once, swap presets, different output.

A real example

Here’s an article CRUD form after installing the plugin. No manual classes:

<?= $this->Form->create($article, ['align' => 'horizontal']) ?>
<?= $this->Form->control('title') ?>
<?= $this->Form->control('user_id', ['options' => $users]) ?>
<?= $this->Form->control('body', ['type' => 'textarea', 'rows' => 8]) ?>
<?= $this->Form->control('tags._ids', ['multiple' => 'checkbox', 'options' => $tags]) ?>
<?= $this->Form->control('published_date', ['type' => 'date']) ?>
<?= $this->Form->control('price', ['prepend' => '$', 'help' => 'USD']) ?>
<?= $this->Form->control('active', ['type' => 'checkbox', 'switch' => true]) ?>
<?= $this->Form->submit('Save Article', ['class' => 'primary']) ?>
<?= $this->Form->end() ?>

Every single control gets the right Tailwind/DaisyUI classes. The horizontal alignment uses flex. The switch checkbox is a DaisyUI toggle. The input group shows a $ prepended. The help text gets an aria-describedby link. Tags render as a multi-checkbox group with the correct _ids wiring.

Same template, swap to KTUI preset, every input becomes kt-input, every button becomes kt-btn kt-btn-primary, every checkbox becomes kt-checkbox. The template file never changes.

The roadmap

The plugin is a ~90% drop-in replacement for bootstrap-ui. The 10% is captured in issue #1:

• Inline form layout (align => 'inline')
• staticControl() method
• Floating labels
• Label tooltips
• Tooltip-style validation error feedback

If any of them are blockers for you, open an issue or PR.

For typical admin panels, CRUD pages, and forms — the 85% covers everything you actually use every day.

Try it

composer require dereuromark/cakephp-tailwind-ui
bin/cake plugin load TailwindUi

Screenshots (DaisyUI left, KTUI right for each component) in the docs/ folder.

Repository: github.com/dereuromark/cakephp-tailwind-ui

Feedback, bug reports, and preset contributions (Flowbite, Preline, shadcn, your own design system) are very welcome.

Installing the RC

composer require cakephp/cakephp:5.4.0-RC2 --update-with-dependencies

If you maintain plugins, also try your plugin’s test suite against the RC — that is where most surprises tend to live.

ORM: new default eager loading strategy

The default loading strategy for HasMany and BelongsToMany associations changed from select to subquery. For most apps this is a net win on larger result sets — it avoids the N+1 multi-IN(...) query that grew unbounded with page size.

If a specific association regresses for you (e.g. very small parent sets, or strange index plans on your DB), opt back in explicitly:

$this->hasMany('Comments')
    ->setStrategy('select');

The behavior is identical, only the default flipped. Worth re-running your slowest endpoints and comparing query plans.

ORM: transaction commit callbacks finally fire correctly

Second behavior change worth retesting: Model.afterSaveCommit and Model.afterDeleteCommit are now correctly dispatched when save() or delete() runs inside an outer transaction. Previously these events were either suppressed or fired at the wrong moment in nested-transaction scenarios — a long-standing footgun for anyone using event listeners for audit logs, search-index updates, notifications, or other post-commit side effects.

If you have code like this:

$this->Articles->getEventManager()->on(
    'Model.afterSaveCommit',
    fn($event, $article) => $this->Search->index($article),
);

$connection->transactional(function () {
    $article = $this->Articles->save($newArticle);
    $this->Comments->save($firstComment);
    // afterSaveCommit for $article was previously NOT fired here in 5.3
});

…the search index now updates exactly once, after the outer transaction commits. Rolled-back transactions correctly discard the pending callbacks, and they don’t leak between transactions.

The underlying machinery is also exposed publicly as Connection::afterCommit() if you want to defer arbitrary post-commit work yourself:

$connection->afterCommit(function () {
    $this->mailer->sendWelcome($user);
});
// fires after the outermost transaction commits;
// runs immediately if no transaction is active.

This is the kind of fix that quietly removes a class of bugs — but it also means any listener you previously expected never to fire in those nested-save paths will now actually run. Re-check your event listeners.

ORM: stricter entity class checks

Table::delete($entity), save(), patchEntity(), and loadInto() previously accepted any EntityInterface. A copy-paste bug like $this->Invoices->delete($orderEntity) would happily delete from the wrong table — silent data loss, no exception.

5.4 (#19428) adds a runtime assertion at the persistence and marshalling chokepoints. If the entity’s concrete class doesn’t match the table’s configured entity class, you get an InvalidArgumentException instead:

$order = $this->Orders->get(1);
$this->Invoices->delete($order);
// InvalidArgumentException: Entity of class App\Model\Entity\Order
// does not match table entity class App\Model\Entity\Invoice

The escape hatch is the generic Cake\ORM\Entity itself, so ad-hoc usage like $table->delete(new Entity(['id' => 1])) still works. Only Entity subclasses that belong to a different table get rejected, which is the actual bug we want to catch.

The check is wired into:

• save(), saveOrFail(), saveMany(), saveManyOrFail()
• delete(), deleteOrFail(), deleteMany(), deleteManyOrFail()
• patchEntity(), patchEntities()
• loadInto()

This is a behavior change in a minor: code that previously silently mis-fired will now throw. Worth grepping your codebase for cross-table delete() / save() calls before deploying the RC.

/**
 * @method \App\Model\Entity\Invoice|false delete(\App\Model\Entity\Invoice $entity, array $options = [])
 * @method \App\Model\Entity\Invoice deleteOrFail(\App\Model\Entity\Invoice $entity, array $options = [])
 * @method iterable<\App\Model\Entity\Invoice> deleteMany(iterable<\App\Model\Entity\Invoice> $entities, array $options = [])
 * @method \App\Model\Entity\Invoice loadInto(\App\Model\Entity\Invoice $entity, array $contain)
 */
class InvoicesTable extends Table

'IdeHelper' => [
    'concreteEntitiesInParam' => 'strict',
],

ORM: type-safe unhydrated reads

SelectQuery->disableHydration() always returned arrays at runtime, but the static type still resolved to entity|array — so every array access needed a cast or a PHPStan ignore. Worse, disableHydration() becomes a hard error in 6.0.

5.4 adds Table::unhydratedFind() returning a dedicated UnhydratedSelectQuery. It behaves exactly like a normal select query (eager loading, finders, the lot), but because it extends SelectQuery<array<string, mixed>>, first() / all() / toArray() / iteration resolve to arrays at the type level:

$rows = $this->Articles->unhydratedFind()
    ->where(['published' => true])
    ->all();

foreach ($rows as $row) {
    echo $row['title']; // typed as array, no cast, no PHPStan ignore
}

Use it anywhere you read raw rows for performance or export and never needed entities. It is the forward-compatible replacement for disableHydration().

DateTimeType accepts date-only strings

A small marshalling fix that removes a common validation papercut: a datetime column fed a date-only Y-m-d string (e.g. from a <input type="date">) used to marshal as invalid. 5.4 accepts it and sets the time to midnight:

// posting 'starts_at' => '2026-06-28' to a datetime field
$event = $this->Events->newEntity($data);
$event->starts_at; // 2026-06-28 00:00:00 — no longer an error

If you previously worked around this with a separate date column or manual 00:00:00 concatenation, you can drop that glue.

New query expression methods

A small but very welcome batch of expression helpers landed on the query builder. They replace patterns that used to need raw SQL or awkward orWhere() gymnastics.

notBetween() — the missing partner to between():

$query->where(function (QueryExpression $exp) {
    return $exp->notBetween('Articles.published', $start, $end);
});

inOrNull() / notInOrNull() — match a list or include rows where the column is NULL. This is the single most common reason people reach for raw SQL today:

$exp->inOrNull('Articles.category_id', [1, 2, 3]);
// generates: (Articles.category_id IN (1,2,3) OR Articles.category_id IS NULL)

isDistinctFrom() / isNotDistinctFrom() — null-safe equality, finally as a first-class expression:

$exp->isNotDistinctFrom('Articles.author_id', $authorId);
// matches when both are NULL too, unlike plain '='

EXCEPT / EXCEPT ALL set operations on SelectQuery:

$active = $this->Users->find()->where(['active' => true]);
$banned = $this->Users->find()->where(['banned' => true]);

$activeNotBanned = $active->except($banned);

And stringAgg() on FunctionsBuilder — a portable wrapper over GROUP_CONCAT / STRING_AGG so you no longer have to branch on driver:

$query->select([
    'Articles.author_id',
    'tags' => $query->func()->stringAgg('Tags.name', ', '),
])->groupBy(['Articles.author_id']);

Collection convenience methods

The collection trait got five additions that round out gaps people have hit for years:

$collection = collection(['a' => 1, 'b' => 2, 'c' => 3]);

$collection->keys();                   // ['a', 'b', 'c']
$collection->values();                 // [1, 2, 3]
$collection->implode(', ');            // "1, 2, 3"

// Conditional pipelines — no more breaking out of the chain:
$results = collection($rows)
    ->when($onlyActive, fn($c) => $c->filter(fn($r) => $r->active))
    ->unless($includeArchived, fn($c) => $c->reject(fn($r) => $r->archived))
    ->toList();

when() / unless() are the big quality-of-life ones — long collection chains that previously had to be torn apart for a single conditional filter() now stay fluent.

Text::mask() and Text::maskValue()

Two new sibling helpers for safe logging and partial display:

use Cake\Utility\Text;

// Mask by position
Text::mask('4111111111111111', 4, 8);
// => "4111********1111"

// Mask specific values inside a string
Text::maskValue(
    'API call with token=sk-abcd1234 from user mark@example.com',
    ['sk-abcd1234', 'mark@example.com']
);
// => "API call with token=*********** from user ****************"

Useful in logs, audit trails, and anywhere PII or secrets accidentally end up in user-visible strings.

TestCase::mockModel() with Mockery

Mocking table classes used to be one of the rougher corners of testing. The new helper sets up a partial Mockery mock that is already wired into the table locator:

$Articles = $this->mockModel('Articles');
$Articles->shouldReceive('publishLatest')
    ->once()
    ->andReturn(true);

// Controller code that does fetchTable('Articles') now gets the mock
$this->post('/articles/publish-latest');
$this->assertResponseOk();

PHPUnit itself stopped supporting the old style of mocking with notices on newer versions — this is the supported path going forward.

Enum labels

A small but lovely addition for anyone using PHP enums as form options or table columns: EnumLabelTrait plus the #[Label] attribute give you human-readable labels without a switch statement:

use Cake\Database\Type\EnumLabelTrait;
use Cake\Database\Type\Attribute\Label;

enum ArticleStatus: string
{
    use EnumLabelTrait;

    #[Label('Draft')]
    case Draft = 'draft';

    #[Label('Pending review')]
    case Pending = 'pending';

    case Published = 'published'; // falls back to "Published"
}

ArticleStatus::Pending->label(); // "Pending review"

The label string also flows through __d() translation if you set up a domain, so it plays nicely with i18n. Combined with FormHelper::enumOptions() (now public), enum-backed select boxes become a one-liner.

A fluent filesystem utility

Cake\Utility\Fs\Finder is a new fluent file-discovery API — pattern matching, depth limits, hidden-file handling, exclusions, cross-platform paths. It replaces hand-rolled RecursiveIteratorIterator gymnastics:

use Cake\Utility\Fs\Finder;

$finder = (new Finder())
    ->in(ROOT . DS . 'src')
    ->name('*.php')
    ->notPath('*/Test/*')
    ->depth(3);

foreach ($finder->files() as $file) {
    // SplFileInfo for each match
}

Internally CakePHP already uses it for I18nExtractCommand and command scanning. The path helpers (Cake\Utility\Fs\Path::join() etc.) are also drop-in replacements for the older pathCombine() calls.

JsonStreamResponse

Streaming large JSON payloads without buffering them in memory is now first-class:

use Cake\Http\Response\JsonStreamResponse;

return new JsonStreamResponse(function () {
    foreach ($this->Reports->find()->all() as $row) {
        yield $row->toArray();
    }
});

The generator emits items into a JSON array as they are produced — handy for exports and reports that would otherwise OOM your worker.

Forward-compat: Commands now auto-hydrate $io and $args

In 6.0 the execute() signature drops the $io and $args arguments. 5.4 lays the groundwork by hydrating them as properties before execute() runs:

class MyCommand extends Command
{
    public function execute(Arguments $args, ConsoleIo $io): int
    {
        // Already works today AND forward-compatible:
        $this->io->out('Hello');
        $this->args->getArgument('name');

        return static::CODE_SUCCESS;
    }
}

Migrate to $this->io / $this->args now and your commands will need no changes when 6.0 lands.

RequestToDto attribute

A new attribute system maps request data into typed DTO action arguments — like Symfony’s MapRequestPayload but native:

use Cake\Controller\Attribute\RequestToDto;
use Cake\Controller\Attribute\Enum\RequestToDtoSource;

public function create(
    #[RequestToDto(source: RequestToDtoSource::Body)]
    CreateArticleDto $dto,
): Response {
    $article = $this->Articles->newEntity($dto->toArray());
    // ...
}

Sources are Body, Query, Request (merge of both), and Auto (the default — picks Query for GET/HEAD, otherwise Body).

The only contract the attribute enforces on your DTO class is a single static method:

public static function createFromArray(array $data): static;

public static function createFromArray(array $data, bool $ignoreMissing = false, ?string $type = null): static

<dto name="CreateArticle">
    <field name="title" type="string" required="true"/>
    <field name="body" type="string" required="true"/>
    <field name="authorId" type="int" required="true"/>
    <field name="tags" type="string[]"/>
    <field name="publishedAt" type="\Cake\I18n\DateTime"/>
</dto>

bin/cake dto generate

use App\Dto\CreateArticleDto;
use Cake\Controller\Attribute\RequestToDto;
use Cake\Http\Response;

public function add(
    #[RequestToDto] CreateArticleDto $dto,
): Response {
    // $dto is fully typed and immutable — no manual hydration, no array soup.
    $article = $this->Articles->newEntity($dto->toArray());
    if ($this->Articles->save($article)) {
        return $this->redirect(['action' => 'view', $article->id]);
    }
    // ...
}

Also landed

A handful of smaller-but-noteworthy changes that didn’t get their own section:

• In-tree DI container forked from thephpleague/container (#18090). CakePHP has used league/container for years; 5.4 ports it into core as Cake\Container\Container so the framework controls its own evolution. League remains the default for BC; opt into the in-tree version with Configure::write('App.container', 'cake'). Tagged services land via Definition::getTags(). Plugin authors: skim it so you know it’s coming.
• CSP-compatible hidden form inputs (#19414). FormHelper now uses the HTML5 hidden attribute instead of inline style="display:none", so strict Content-Security-Policy setups (style-src without 'unsafe-inline') stop silently breaking forms.

New: Lock component

The biggest feature to land between RC1 and RC2: Cake\Lock, a new component for distributed locking (#19370). It closes a long-standing parity gap with Symfony Lock and Laravel Cache::lock().

Cache-style configuration, with engines for Redis, Memcached, File (flock), and Null (no-op for tests). Non-blocking acquire() and blocking acquireBlocking() with timeout, lock refresh for long-running jobs, owner verification on release, plus a fluent synchronized() wrapper:

Lock::synchronized('rebuild-search-index', function () {
    // Critical section runs at most once across all workers.
});

If you currently work around the gap with database advisory locks or a third-party lock library, this is the one to swap in and stress-test during the RC window.

What we need from you

The RC window is short. Before 5.4.0 lands, please:

1. Pull the RC into a non-production branch of your app and run your full test suite.
2. Re-run a few heavy endpoints — the eager-loading default flip is the most likely place to see surprises (good or bad).
3. Try your plugins against the RC. Plugin maintainers, this is the moment to publish a 5.4-compatible tag.
4. File issues on cakephp/cakephp with a minimal reproduction.

Every issue caught now is one that does not bite someone after the stable tag. Thanks for testing.

Where this plugin fits

The plugin is meant for the multiple-reaction case. If you only need a single binary opinion, such as star, favorite, or like, dereuromark/cakephp-favorites is the smaller fit. If you need weighted scores, averages, or star ratings, dereuromark/cakephp-ratings is the better tool.

Use cakephp-reactions when the UI should offer several response types for the same record:

• articles with 👍, ❤, 🎉, and 👀,
• comments with 👍 and 👎,
• roadmap items with 🚀,
• support replies with ❤ or 😄,
• private business-domain keys such as approved, blocked, or needs-review.

The stored reaction value is just a string. Emoji are first-class values, but the plugin does not require them.

Installation

Install the package with Composer:

composer require dereuromark/cakephp-reactions

Load the plugin and run its migration:

bin/cake plugin load Reactions
bin/cake migrations migrate -p Reactions

The current branch targets CakePHP 5.1+ and PHP 8.2+.

The database model

The migration creates one table, reactions_reactions. Each row stores the host model name, the host record id, the reacting user id, the reaction key, and the creation timestamp.

The important columns are:

• model: the stored model string, for example Posts or Blog.Articles,
• foreign_key: the primary key value of the host record,
• user_id: the user who reacted,
• reaction: the emoji literal or named key.

The table has a unique index across model, foreign_key, user_id, and reaction. That is what makes writes idempotent and prevents duplicate rows for the same user/reaction pair.

The foreign_key column is polymorphic. It is not a real database foreign key, because one reaction table can point at many different host tables. Before running the migration, you can choose the foreign-key column type through the global Polymorphic.type configuration:

'Polymorphic' => [
    'type' => 'integer', // integer, biginteger, uuid, or binaryuuid
],

For integer and biginteger primary keys, signedness follows Migrations.unsigned_primary_keys.

On MySQL, the migration gives the reaction column an utf8mb4_bin collation. That matters for emoji. Binary comparison keeps grouping and uniqueness byte-for-byte, so different emoji do not collapse into the same comparison weight under a broad case-insensitive collation.

Attach the behavior

Every model that can receive reactions gets the Reactable behavior:

// in src/Model/Table/PostsTable.php
public function initialize(array $config): void {
    parent::initialize($config);

    $this->addBehavior('Reactions.Reactable', [
        'allowed' => ['👍', '👎', '❤', '🎉', '🚀'],
    ]);
}

The allowed option is optional. Set it to an array when you want a fixed reaction set. Set it to null when arbitrary non-empty keys are acceptable:

$this->addBehavior('Reactions.Reactable', [
    'allowed' => null,
]);

The behavior gives the host table methods for common operations:

$this->Posts->addReaction([
    'modelId' => $postId,
    'userId' => $userId,
    'reaction' => '👍',
]);

$this->Posts->removeReaction([
    'modelId' => $postId,
    'userId' => $userId,
    'reaction' => '👍',
]);

$result = $this->Posts->toggleReaction([
    'modelId' => $postId,
    'userId' => $userId,
    'reaction' => '🚀',
]);

$counts = $this->Posts->reactionCounts($postId);
$mine = $this->Posts->userReactions($postId, $userId);

addReaction() is idempotent. It returns the new reaction id when a row is created, and null when the same row already exists. removeReaction() returns the number of deleted rows. toggleReaction() returns the action that happened and fresh counts:

[
    'action' => 'added', // or 'removed'
    'counts' => [
        '👍' => 3,
        '🚀' => 1,
    ],
]

Counts are returned as an array keyed by reaction and sorted by reaction key for deterministic output.

Typed reactions with enums

The plugin includes a Reactions\Reaction enum for the default GitHub-style set:

use Reactions\Reaction;

$behavior = $this->Posts->getBehavior('Reactable');

$behavior->react($postId, by: $userId, with: Reaction::ThumbsUp);
$behavior->unreact($postId, by: $userId, with: Reaction::ThumbsUp);
$behavior->toggle($postId, by: $userId, with: Reaction::Rocket);

The bundled enum cases are:

• ThumbsUp: 👍,
• ThumbsDown: 👎,
• Laugh: 😄,
• Confused: 😕,
• Heart: ❤,
• Party: 🎉,
• Rocket: 🚀,
• Eyes: 👀.

Applications can also define their own string-backed enum:

enum ArticleReaction: string {
    case Helpful = 'helpful';
    case NeedsWork = 'needs-work';
    case Approved = 'approved';
}

Then use those enum cases in the behavior config and calls:

$this->addBehavior('Reactions.Reactable', [
    'allowed' => [
        ArticleReaction::Helpful,
        ArticleReaction::NeedsWork,
        ArticleReaction::Approved,
    ],
]);

$this->Articles
    ->getBehavior('Reactable')
    ->react($articleId, by: $userId, with: ArticleReaction::Helpful);

The short methods react(), unreact(), and toggle() live on the behavior instance. They are intentionally not exposed as table magic methods, because those method names are generic and can collide with other behaviors. The array-form table methods are still available and also accept BackedEnum values in the reaction field.

Configure public aliases

When reaction requests go through the plugin controller or helper, the plugin uses public aliases. The alias is part of the URL and form payload, so it should be short, stable, and explicitly configured:

'Reactions' => [
    'models' => [
        'Posts' => 'Posts',
        'Articles' => 'Blog.Articles',
    ],
    'allowed' => ['👍', '👎', '❤', '🎉', '🚀'],
],

This gives you URLs such as:

/reactions/reactions/toggle/Posts/123

Unknown aliases are rejected. That is an important boundary: the browser should not be allowed to submit arbitrary table class names.

Render a reaction widget

Load the helper in AppView:

// in src/View/AppView.php
public function initialize(): void {
    parent::initialize();

    $this->loadHelper('Reactions.Reactions');
}

Render the widget and counts in a view:

// in templates/Posts/view.php
echo $this->Reactions->widget('Posts', $post->id);
echo $this->Reactions->counts('Posts', $post->id);

The widget renders the current user’s selected reactions and a <details> picker for the available reactions. Internally it uses FormHelper::postLink() with block => true, which keeps generated forms out of nested form markup. Your layout must output the postLink block once:

<?= $this->fetch('postLink') ?>

The helper’s default icon set is derived from Reactions\Reaction, but you can replace it:

$this->loadHelper('Reactions.Reactions', [
    'icons' => [
        'thumbsup' => '👍',
        'heart' => '❤',
        'rocket' => '🚀',
    ],
    'html' => '<span class="reaction%s" aria-hidden="true">%s</span>',
]);

The array key is the stored reaction value. The array value is what gets rendered.

If you need custom markup, ask the helper for the toggle URL and build the UI yourself:

$url = $this->Reactions->urlToggle('Posts', $post->id);

Choose a request strategy

The plugin supports two UI submission strategies.

The default strategy posts to the plugin controller. This is the simplest setup:

echo $this->Reactions->widget('Posts', $post->id);

The controller reads the current user id from the configured session key, validates the alias, validates the reaction key, writes the row through ReactionsTable, refreshes counters when needed, and redirects back for normal HTML requests.

For JSON or AJAX toggle requests, the controller returns a small payload:

{
    "action": "added",
    "counts": {
        "👍": 3,
        "🚀": 1
    }
}

The second strategy posts back to the current host controller action and lets ReactableComponent process the reaction payload:

// in src/Controller/PostsController.php
public function initialize(): void {
    parent::initialize();

    $this->loadComponent('Reactions.Reactable');
}

Load the helper with the action strategy:

$this->loadHelper('Reactions.Reactions', [
    'strategy' => 'action',
]);

With this setup, the helper includes alias, id, reaction, and action in the POST body. The component checks whether the current controller action is enabled, loads the behavior when needed, validates the payload, reads the user id, and delegates to addReaction(), removeReaction(), or toggleReaction().

Use the controller strategy when a plugin route is acceptable. Use the action strategy when reactions should be handled inside an existing page flow.

Counter caches for list views

Counting reactions on detail pages is usually cheap. On list pages, repeatedly counting reactions for many records can get expensive. For that case, enable the optional counter cache.

Add a column to the host table:

$this->table('posts')
    ->addColumn('reactions_count', 'integer', [
        'default' => 0,
        'null' => false,
    ])
    ->update();

Enable it on the behavior:

$this->addBehavior('Reactions.Reactable', [
    'counterCache' => true,
    'fieldCounter' => 'reactions_count',
]);

The plugin recomputes the total count after add, remove, and toggle operations. Recomputing costs a little more than incrementing, but it self-heals after manual data changes. If the configured counter column does not exist, the write is skipped, which makes staged deployments easier.

Direct calls to ReactionsTable::add() or ReactionsTable::remove() bypass the behavior. Use the behavior for normal application writes when you want counters to stay in sync automatically.

Querying reacted content

The behavior adds two finders.

Use reactions to load one host record with its reactions and reacting users:

$post = $this->Posts
    ->find('reactions', id: $postId)
    ->firstOrFail();

Use reactedBy to find host records a user has reacted to:

$posts = $this->Posts
    ->find('reactedBy', userId: $userId)
    ->all();

These finders are useful for detail pages, profile activity, notification features, and dashboards.

Custom user models

By default, reactions belong to Users through user_id. If your application uses another user table class, configure it:

$this->addBehavior('Reactions.Reactable', [
    'userModelClass' => 'Accounts',
]);

For a fully custom association:

$this->addBehavior('Reactions.Reactable', [
    'userModel' => 'Authors',
    'userModelConfig' => [
        'className' => 'Accounts.Users',
        'foreignKey' => 'user_id',
    ],
]);

The reaction table uses that association for its existsIn rule, so invalid user ids are rejected at the table layer.

Admin backend

The plugin ships an admin listing for reaction rows:

/admin/reactions

Access is deny-by-default. You must configure Reactions.adminAccess with a closure that returns literal true for allowed requests:

use Cake\Http\ServerRequest;

'Reactions' => [
    'adminAccess' => function (ServerRequest $request): bool {
        $identity = $request->getAttribute('identity');

        return $identity !== null && in_array('admin', (array)$identity->roles, true);
    },
],

The admin backend can list reaction rows and filter by configured models.

Security model

The plugin keeps the browser-facing surface intentionally narrow.

Do not trust submitted user ids. The controller and component read the current user id from the server-side session configuration. When you call the behavior directly, pass the authenticated user id from your own server-side identity logic.

Always configure Reactions.models for models exposed through the controller strategy. The submitted alias is public input. The plugin rejects aliases that are not mapped.

Use allowed when arbitrary reaction keys are not part of your product design. The behavior and controller both enforce the configured allow-list.

Reaction entity foreign keys are not intended for direct mass assignment. Write through the behavior or table methods so validation, uniqueness, and counters stay consistent.

Keep the admin backend closed until your application explicitly allows the request through adminAccess.

Troubleshooting

If reaction buttons render but do nothing, check your layout first:

<?= $this->fetch('postLink') ?>

This should be placed just before the closing </body> tag.

The helper stores generated forms in the postLink block. Without fetching that block, the visible links will not have the backing POST forms.

If you see an invalid alias error, verify your Reactions.models config:

'Reactions' => [
    'models' => [
        'Posts' => 'Posts',
    ],
],

If a reaction key is rejected, check the behavior-level allowed config first. The controller uses the host table’s loaded behavior config when available and falls back to Configure::read('Reactions.allowed').

If counters do not update, confirm that the host table has the behavior loaded, that counterCache is enabled, and that the configured counter column exists.

A complete minimal setup

For a simple posts application, the setup can be as small as this.

Configuration:

'Reactions' => [
    'models' => [
        'Posts' => 'Posts',
    ],
    'allowed' => ['👍', '👎', '❤', '🎉', '🚀'],
    'sessionKey' => 'Auth.User',
    'userIdField' => 'id',
],

Posts table:

public function initialize(array $config): void {
    parent::initialize($config);

    $this->addBehavior('Reactions.Reactable', [
        'allowed' => ['👍', '👎', '❤', '🎉', '🚀'],
    ]);
}

View helper:

public function initialize(): void {
    parent::initialize();

    $this->loadHelper('Reactions.Reactions');
}

Template:

echo $this->Reactions->widget('Posts', $post->id);
echo $this->Reactions->counts('Posts', $post->id);

Layout:

<?= $this->fetch('postLink') ?>

That gives you a working, POST-based reaction widget with server-side validation, duplicate protection, and count rendering.

Demo

Check out the sandbox examples for a live demo.

Closing thoughts

cakephp-reactions deliberately keeps the data model small and the integration points idiomatic. The plugin does not force one presentation style or one set of emoji. It gives your CakePHP application a dependable reaction table, a Reactable behavior, a helper for the common UI, controller and component flows, typed enum support, optional counters, and secure defaults around public aliases and admin access.

That makes it useful for the common social-style reaction UI, but also for business workflows where the reaction keys are not emoji at all. In both cases, the same core rule holds: a user can express several distinct reactions to a record, and each distinct reaction is stored once.

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 <?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 !== ’’ && strstartswith($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.