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.