Inštalácia

Pridajte balík, publikujte jeho migrácie a spustite migráciu. Service provider aj globálny alias fasády Tags sa načítajú automaticky, spolu s providermi balíkov Roundly, na ktorých stojí (package-toolkit, enums, sluggable, translatable a query-builder):

composer require roundly-consulting/tags-for-laravel
php artisan vendor:publish --tag="tags-migrations"
php artisan migrate

Migrácie sa len publikujú — provider žiadnu z nich nenačíta, takže php artisan migrate spustí presne súbory, ktoré ste publikovali: tabuľku tags, spojovaciu tabuľku taggables a tabuľku tag_locks.

1. Typy kľúčov nastavte pred migráciou

Migrácie čítajú dva typy kľúčov. Ak všade používate bigint id, predvolené hodnoty sedia. Pri kľúčoch UUID alebo ULID ich nastavte pred php artisan migrate — po vytvorení tabuliek sú oba zafixované:

TAGS_PRIMARY_KEY_TYPE=uuid   # the package's own keys: tags.id, tags.parent_id, taggables.tag_id
TAGS_KEY_TYPE=uuid           # every taggable model (taggable_id) and scope model (scope_id)

Každý model so štítkami aj každý model rozsahu (tím, tenant, projekt) musí mať kľúč typu tags.key_type. Model s iným kľúčom vyhodí InvalidTagsConfigurationException s jeho názvom ešte pred spustením SQL a tags:doctor to nahlási.

2. Ak treba, premenujte tabuľky

Ak už aplikácia tabuľku tags má, premenujte najprv tabuľky balíka v publikovanej konfigurácii. Každý názov držte najviac na 30 znakoch — tvoria sa z neho názvy indexov v MySQL:

// config/tags.php — before php artisan migrate, when the app already owns a tags table
'tables' => [
    'tags' => 'taxonomy_tags',
    'taggables' => 'taxonomy_taggables',
    'locks' => 'taxonomy_locks',
],

3. Skontrolujte jazyky

Názvy štítkov sa ukladajú pre každý jazyk cez translatable-for-laravel a obyčajný reťazec označuje štítok v aktuálnom jazyku. Uistite sa, že jazyk aplikácie je v translatable.locales (predvolene en a sk) — inak označovanie podľa názvu vyhodí výnimku a tags:doctor to nahlási ako chybu:

// config/translatable.php (translatable-for-laravel) — every locale a tag name may be stored in
'locales' => ['en', 'sk', 'de'],

Migrácia tabuľky tags vytvorí jeden unikátny index slugov pre každý podporovaný jazyk. Jazyk pridaný neskôr potrebuje vlastný index a nastavenie slugov zmenené po vzniku štítkov si vyžaduje pregenerovanie uložených slugov — oboje cez príkazy sluggable-for-laravel:

# A locale added after migrating needs its unique slug index
php artisan sluggable:indexes "RoundlyConsulting\Tags\Models\Tag"

# A slug setting changed after tags exist (separator, dictionary, unicode, max length)
php artisan sluggable:regenerate "RoundlyConsulting\Tags\Models\Tag"

4. Model so štítkami

Implementujte kontrakt Taggable a použite trait HasTags, ktorý implementuje všetky jeho metódy:

use Illuminate\Database\Eloquent\Model;
use RoundlyConsulting\Tags\Concerns\HasTags;
use RoundlyConsulting\Tags\Contracts\Taggable;

final class Concert extends Model implements Taggable
{
    use HasTags;
}

Potom deklarujte typy štítkov v service provideri a môžete označovať — celý postup v jednom bloku:

use RoundlyConsulting\Tags\Facades\Tags;

// Declare your tag types once, in a service provider
Tags::define('genre')->hierarchical()->single();   // a curated category tree, one per model
Tags::define('label')->max(5);                     // free-form labels, up to five

// Build the tree (names are translatable; a plain string is the current locale)
$music = Tags::type('genre')->make(['en' => 'Music', 'sk' => 'Hudba'])->color('#f24e29')->create();
$jazz = Tags::type('genre')->make('Jazz')->under($music)->create();

// Tag any model that uses HasTags
$concert->syncTags($jazz, 'genre');
$concert->attachTags(['Live', 'Outdoor'], 'label');     // unknown labels are created on the fly

// Query: "music" also matches everything under it
Concert::withAnyTags(['music'], 'genre', descendants: true)->get();
Concert::withAllTags(['live', 'outdoor'], 'label')->get();

// Read without N+1
foreach (Concert::with('tags')->get() as $concert) {
    echo $concert->tagOf('genre')?->name;                         // Jazz
    echo $concert->tagsOf('label')->pluck('name')->join(', ');    // Live, Outdoor
}

// Autocomplete and popularity
Tags::type('label')->suggest('liv');    // prefix matches first, in every locale
Tags::type('label')->popular(10);

Publikovacie tagy

php artisan vendor:publish --tag="tags-config"         # config/tags.php
php artisan vendor:publish --tag="tags-translations"   # lang/vendor/tags/{en,sk}/…
php artisan vendor:publish --tag="tags-routes"         # routes/tags.php — replaces the package's file

JSON API je po inštalácii vypnuté. Ak ho chcete sprístupniť, nastavte TAGS_ROUTES=on — nenastavený prepínač ho nechá vypnuté aj v publikovanej konfigurácii, ktorej pole routes prepisuje len niektoré kľúče (pozrite JSON API).

Tabuľky

Preklady

Každý text pre používateľov ide cez menný priestor tags:: v angličtine (en) a slovenčine (sk) s rovnakými kľúčmi: enums.php (popisy enumov), messages.php (texty výnimiek), types.php (popis predvoleného typu: Tag / Štítok) a validation.php (hlásenia pravidla a názvy polí v API). Ak chcete niektorý riadok zmeniť, publikujte ich cez --tag=tags-translations; pre ďalší jazyk pridajte lang/vendor/tags/<locale>/….

php artisan about

php artisan about --only=tags

Sekcia Tags zobrazí typy kľúčov, predvolený typ (NONE, ak je prázdny), počet definovaných typov s prvými piatimi názvami a či sú routy zapnuté (ON). Názvy sa len čítajú, nevyhodnocujú, takže chybne definovaný typ príkaz nepokazí.