Managing tags

use RoundlyConsulting\Tags\DataTransferObjects\TagData;

$genres = Tags::type('genre');

// The builder…
$music = $genres->make(['en' => 'Music', 'sk' => 'Hudba'])->color('#f24e29')->create();
$jazz = $genres->make('Jazz')->under($music)->position(0)->create();

// …or the DTO — the same code path
$rock = $genres->create(new TagData(name: 'Rock', parent: $music, icon: 'guitar'));

// Idempotent seeding: an existing tag is returned unchanged (never moved, recoloured or renamed),
// a missing one is created with every attribute — so the seeder may run again
$bebop = $genres->make('Bebop')->under($jazz)->color('#a7c4d6')->findOrCreate();
$live = Tags::type('label')->findOrCreate('Live');            // a name, a locale map or a TagData

$genres = Tags::type('genre');

$genres->find('jazz');              // a live tag by slug or name (along the locale chain), a key or a model
$genres->find(12);                  // by primary key (int)
$genres->findOrFail('jazz');        // TagNotFoundException when missing
$genres->findMany($ids);            // by keys, in the order given — malformed, foreign or missing keys skipped
$genres->findTrashed('jazz');       // a deleted tag of exactly this handle's scope, to restore it

$genres->all();                     // every live tag of the type, by position
$genres->roots();                   // the roots (every tag of a flat type)
$genres->query()->where('usage_count', '>', 10)->get();   // Builder<Tag> of the readable scopes

Tags::find($key);                   // a live tag of any type by primary key
Tags::findOrFail($key);

use RoundlyConsulting\Tags\DataTransferObjects\UpdateTagData;

// Fluently — only what you call changes
Tags::type('genre')->edit($jazz)->name('Jazz music')->color(null)->save();

// A rename of the current locale, or of several locales at once
Tags::type('genre')->rename($jazz, 'Jazz music');
Tags::type('genre')->rename($jazz, ['en' => 'Jazz music', 'sk' => 'Jazzová hudba']);

// The DTO — fields left out stay; null clears a description, colour or icon
Tags::type('genre')->update($jazz, new UpdateTagData(description: null, icon: 'sax'));

// A null (or blank) description entry clears that locale only
Tags::type('genre')->edit($jazz)->description(['sk' => null])->save();

use RoundlyConsulting\Tags\Enums\TagChildren;

$genres = Tags::type('genre');

$genres->delete($rock);                                   // soft-deletes it and detaches it everywhere
$genres->delete($music);                                  // TagHasChildrenException while it has live children
$genres->delete($music, TagChildren::Reparent);           // children move up to its parent
$genres->delete($music, TagChildren::Delete);             // the whole subtree goes

$genres->restore($rock);                                  // back, with no old taggings
$genres->restore($genres->findTrashed('rock'));           // find it by name first

// An admin panel calling Eloquent directly — safe, but it detaches nothing
$tag->delete();

// Reads ignore the leftover taggings at once; a restore through the package starts clean,
// and tags:doctor reports them as an error until you run:
// php artisan tags:repair --orphans

$jazz->type;                   // 'genre'
$jazz->name;                   // in the current locale
$jazz->slug;                   // in the current locale
$jazz->slugFor('sk');          // one locale's slug, or null
$jazz->description;
$jazz->color;                  // '#f24e29' or null
$jazz->icon;
$jazz->parent_id;
$jazz->depth;                  // 1 for a root
$jazz->position;               // among its siblings
$jazz->usage_count;            // taggings, kept in the same transaction as each write
$jazz->definition();           // its TagType

Tag::query()->ofType('genre')->within($team)->roots()->ordered()->get();