The Tags facade

Everything goes through one facade, RoundlyConsulting\Tags\Facades\Tags (global alias Tags), sugar over the TagsManager singleton. Types are declared on it, type() reaches the catalog of one type, for() one model’s tags, and the flat verbs tag a model and return what really changed:

use RoundlyConsulting\Tags\Facades\Tags;

// Types — declared once, at boot
Tags::define('genre')->hierarchical()->single();
Tags::types();                                            // every type, resolved

// The catalog of one type, optionally within a scope
$genres = Tags::type('genre');
$jazz = $genres->make('Jazz')->under($music)->create();
$genres->tree();
Tags::type('label')->within($team)->suggest('liv');

// One model's tags — a chainable handle
Tags::for($concert)->sync($jazz, 'genre')->attach(['Live', 'Outdoor'], 'label');
Tags::for($concert)->of('label');
Tags::for($concert)->findMany($validatedIds, 'label');    // keys a form validated, in the model's scopes

// Flat verbs return what really changed
$changes = Tags::attach($concert, ['live'], 'label');    // TagChanges
Tags::detach($concert, ['outdoor'], 'label');
Tags::sync($concert, null, 'genre');                      // clears the category
Tags::clear($concert);                                    // every tag of every type

// Any tag by key, ancestors for a whole page, maintenance
Tags::find($key);
Tags::loadAncestors($concerts->map(fn (Concert $concert) => $concert->tagOf('genre')));
Tags::repair();

Manager methods

perform() is public on the manager too, but internal: it is the single funnel every flat verb, handle, builder and model method runs its action through, and the hook the fake records with. Don’t call it from app code.

Tags::type($type) — the catalog

type() returns an immutable TypeTags handle for one type, optionally narrowed with within($scope). Reads see the scope’s tags plus the global ones; writes match the scope exactly — a scoped handle never writes a global tag, an unscoped one writes global tags only:

The TagBuilder

make($name) returns a TagBuilder. It validates eagerly where it can — a colour, an icon, a parent of another type or scope throws at the call — and both terminals build a TagData, so the builder and the DTO run the same code:

The TagEditor

edit($tag) returns a TagEditor — only what you call changes:

Tags::for($model) — one model’s tags

for() returns a TaggableTags handle. Writes go through the flat verbs — so the fake records them, and the model’s loaded tags relation is dropped so a chained read sees the change — and return the handle for chaining. findMany() turns keys a form validated into tags, in the model’s own scopes:

The HasTags methods (attachTags(), tagsOf(), …) are shorthands over this handle, so everything here — the fake included — applies to them too.

Data objects

Every DTO is final readonly:

The PHP API trusts its caller

The facade enforces the domain rules — types, limits, curated lists, scopes, the tree — but never asks a Gate. The abilities in tags.authorization guard the JSON API only; code calling the facade decides who may call what.