---
title: "Fasáda Tags — Tags for Laravel | Roundly"
description: "Prehľad fasády Tags — define a types, handle katalógu type(), handle for($model), ploché metódy na označovanie, buildery a dátové objekty."
url: https://roundly-consulting.com/sk/open-source/navody/tags-for-laravel/fasada
language: sk
---

[Všetky balíky](https://roundly-consulting.com/sk/open-source.md)

[Tags for Laravel](https://roundly-consulting.com/sk/open-source/navody/tags-for-laravel.md)

# Fasáda Tags

Všetko ide cez jednu fasádu, RoundlyConsulting\\Tags\\Facades\\Tags (globálny alias Tags), ktorá je skratkou k singletonu TagsManager. Deklarujú sa na nej typy, type() sprístupní katalóg jedného typu, for() štítky jedného modelu a ploché metódy model označia a vrátia, čo sa naozaj zmenilo:

```php
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();
```

## Metódy manažéra

| Metóda | Vracia | Čo robí |
| --- | --- | --- |
| `define($type)` | `TagTypeBuilder` | Deklaruje typ, v boot() service providera. Reťazec alebo enum s reťazcovými hodnotami; druhá definícia vyhodí výnimku. |
| `extend($type, Closure $callback)` | `void` | Upraví typ z kódu aplikácie bez ohľadu na poradie providerov. |
| `types()` | `Collection<string, TagType>` | Všetky definované typy, vyhodnotené, podľa názvu. |
| `type($type)` | `TypeTags` | Katalóg jedného typu — vytváranie, hľadanie, presuny, našepkávanie… Neznámy názov vyhodí výnimku. |
| `find($key) / findOrFail($key)` | `?Tag / Tag` | Živý štítok akéhokoľvek typu podľa primárneho kľúča. |
| `for($taggable)` | `TaggableTags` | Štítky jedného modelu — handle s reťazením. |
| `attach($taggable, $tags, $type = null)` | `TagChanges` | Pridá štítky; neznáme voľné názvy sa vytvoria v rozsahu modelu. |
| `detach($taggable, $tags, $type = null)` | `TagChanges` | Odoberie štítky; názvy bez štítku sa ignorujú. |
| `sync($taggable, $tags, $type = null)` | `TagChanges` | Nastaví štítky modelu jedného typu (pri chýbajúcom type predvoleného) presne na tieto. |
| `clear($taggable, $type = null)` | `TagChanges` | Odoberie všetky štítky typu alebo všetkých typov. |
| `loadAncestors(iterable $tags)` | `void` | Načíta predkov mnohých štítkov jedným dotazom; null hodnoty preskočí. |
| `repair(?RepairOptions $options = null)` | `RepairReport` | Opraví cesty, kľúče rozsahu, osirotené priradenia a počty použití. |
| `Tags::fake()` | `TagsFake` | Len na fasáde — nahrávací fake, ktorý volania aj tak vykoná (pozrite Testovanie). |

perform() je na manažérovi tiež verejná, ale interná: je to jediný lievik, cez ktorý každá plochá metóda, handle, builder aj metóda modelu spúšťa svoju akciu, a háčik, cez ktorý nahráva fake. Z kódu aplikácie ju nevolajte.

## Tags::type($type) — katalóg

type() vráti nemenný handle TypeTags pre jeden typ, voliteľne zúžený cez within($scope). Čítanie vidí štítky rozsahu aj globálne; zápisy presne zodpovedajú rozsahu — handle s rozsahom nikdy nezapíše globálny štítok, handle bez rozsahu zapisuje len globálne štítky:

| Metóda | Vracia | Čo robí |
| --- | --- | --- |
| `within(?Model $scope, bool $includeGlobal = true)` | `TypeTags` | Ten istý katalóg v rozsahu: čítanie vidí štítky rozsahu a globálne (alebo len rozsahu), zápisy idú do rozsahu. |
| `definition()` | `TagType` | Vyhodnotený typ. |
| `make($name)` | `TagBuilder` | Začne nový štítok; reťazec je aktuálny jazyk, pole je mapa jazykov. |
| `create(TagData $data)` | `Tag` | Tá istá cesta kódu ako builder, z DTO. Zmazaný štítok s rovnakým názvom sa vráti s týmito atribútmi. |
| `findOrCreate(string\|array\|TagData $name)` | `Tag` | Štítok, ktorý názov označuje (v rozsahu, inak globálny), bez zmeny, alebo nový v rozsahu; zmazaný štítok s rovnakým názvom sa vráti taký, aký bol. Povolené aj pre kurátorované typy. |
| `edit(Tag $tag)` | `TagEditor` | Fluentná úprava štítku, potom save(). |
| `update(Tag $tag, UpdateTagData $data)` | `Tag` | Premenovanie alebo zmena popisu, ručného slugu, farby či ikony. |
| `rename(Tag $tag, string\|array $name)` | `Tag` | Reťazec premenuje aktuálny jazyk; mapa sa zlúči po jazykoch. |
| `move(Tag $tag, ?Tag $under = null, ?int $position = null)` | `Tag` | Nový rodič (null: koreň), voliteľne pozícia medzi novými súrodencami. |
| `reorder(?Tag $parent, array $order)` | `Collection<int, Tag>` | Zoradí súrodencov pod rodičom (pri null korene): najprv uvedené, potom ostatné. |
| `delete(Tag $tag, TagChildren $children = Refuse)` | `Tag` | Soft delete a odpojenie všade; deti: odmietnuť, presunúť alebo zmazať. |
| `restore(Tag $tag)` | `Tag` | Vráti zmazaný štítok bez jeho starých priradení tam, kde je teraz jeho rodič; pod zmazaným rodičom alebo nad limit hĺbky sa odmietne. |
| `find($tag) / findOrFail($tag)` | `?Tag / Tag` | Živý štítok v čitateľných rozsahoch: model, kľúč (int) alebo názov či slug (reťazec), štítok rozsahu pred globálnym. |
| `findTrashed($tag)` | `?Tag` | Zmazaný štítok presne z rozsahu tohto handle — rozsahu, do ktorého zapisuje obnovenie. |
| `findMany(array $keys)` | `Collection<int, Tag>` | Živé štítky podľa kľúčov v zadanom poradí; chybné, chýbajúce či cudzie kľúče sa preskočia. |
| `all() / roots()` | `Collection<int, Tag>` | Všetky živé štítky alebo korene, podľa pozície. |
| `tree(?Tag $root = null)` | `list<TagNode>` | Strom alebo jeden podstrom, jedným dotazom. |
| `suggest(string $term, ?int $limit = null)` | `Collection<int, Tag>` | Našepkávanie naprieč jazykmi. |
| `popular(?int $limit = null, ?string $on = null, ?Closure $where = null)` | `Collection<int, Tag>` | Najpoužívanejšie štítky — podľa počtu použití alebo naživo na jednej triede. |
| `query()` | `Builder<Tag>` | Živé štítky typu v čitateľných rozsahoch. |

## TagBuilder

make($name) vráti TagBuilder. Validuje hneď, kde sa dá — farba, ikona či rodič iného typu alebo rozsahu vyhodí výnimku už pri volaní — a oba koncové kroky zostavia TagData, takže builder aj DTO spúšťajú ten istý kód:

| Metóda | Vracia | Čo robí |
| --- | --- | --- |
| `description($description)` | `TagBuilder` | Čistý text; reťazec je aktuálny jazyk, pole mapa jazykov. |
| `slug($slug)` | `TagBuilder` | Ručný slug, už v tvare slugu — len pre kurátorované typy. |
| `color(?string $color) / icon(?string $icon)` | `TagBuilder` | Farba #rrggbb (uloží sa malými písmenami); identifikátor alebo emoji. |
| `under(?Tag $parent) / position(?int $position)` | `TagBuilder` | Živý rodič toho istého hierarchického typu a rozsahu — under(null) žiada koreň; bez volania je nový štítok koreňom a zmazaný štítok, ktorý názov vráti, zostane tam, kde bol. Pozícia 0–2147483647 medzi súrodencami. |
| `create() / findOrCreate()` | `Tag` | Vytvorí — zmazaný štítok s rovnakým názvom sa vráti s týmito atribútmi — alebo nájde pomenovaný štítok bez zmeny a vytvorí ho, len ak chýba; zmazaný štítok vrátený cez findOrCreate() si ponechá vlastné atribúty. |

## TagEditor

edit($tag) vráti TagEditor — zmení sa len to, čo zavoláte:

| Metóda | Vracia | Čo robí |
| --- | --- | --- |
| `name($name)` | `TagEditor` | Reťazec premenuje aktuálny jazyk; mapa sa zlúči po jazykoch. |
| `description(?$description)` | `TagEditor` | Zlúči sa po jazykoch; prázdna alebo null položka (\['sk' => null\]) vymaže daný jazyk, null vymaže všetky jazyky. |
| `slug($slug)` | `TagEditor` | Ručný slug — len pre kurátorované typy. |
| `color(?string) / icon(?string)` | `TagEditor` | null vymaže. |
| `save()` | `Tag` | Zostaví UpdateTagData a zavolá update(); zmení sa len to, čo ste zavolali. |

## Tags::for($model) — štítky jedného modelu

for() vráti handle TaggableTags. Zápisy idú cez ploché metódy — takže ich fake zaznamená a načítaný vzťah tags modelu sa zahodí, aby reťazené čítanie videlo zmenu — a vracajú handle na reťazenie. findMany() premení kľúče overené formulárom na štítky, v rozsahoch daného modelu:

| Metóda | Vracia | Čo robí |
| --- | --- | --- |
| `attach($tags, $type = null)` | `TaggableTags` | Cez Tags::attach(), ktorá po zápise zahodí načítaný vzťah tags modelu. |
| `detach($tags, $type = null)` | `TaggableTags` | Cez Tags::detach(). |
| `sync($tags, $type = null)` | `TaggableTags` | Cez Tags::sync(). |
| `clear($type = null)` | `TaggableTags` | Cez Tags::clear(). |
| `all()` | `Collection<int, Tag>` | Všetky štítky modelu podľa pozície — z načítaného vzťahu, ak je načítaný. |
| `of($type) / one($type)` | `Collection / ?Tag` | Štítky jedného typu alebo jeho jediný štítok (kategória). |
| `has($tag, $type = null)` | `bool` | Či model nesie štítok: model, kľúč, názov alebo slug v reťazi jazykov. |
| `hasAny($tags, $type = null) / hasAll(…)` | `bool` | Ktorýkoľvek alebo všetky z nich. |
| `findMany(array $keys, $type)` | `Collection<int, Tag>` | Živé štítky typu podľa kľúča v rozsahoch, ktoré tento model číta (jeho tagScope() a globálne štítky; pri type len globálnom len globálne), v zadanom poradí — postup pre kľúče overené cez TagsRule::for($type)->byId()->taggable($model). |
| `model()` | `Model&Taggable` | Model za handle. |

Metódy HasTags (attachTags(), tagsOf(), …) sú skratky nad týmto handle, takže všetko uvedené — aj fake — platí aj pre ne.

## Dátové objekty

Každé DTO je final readonly:

| DTO | Polia | Význam |
| --- | --- | --- |
| `TagData` | `name, description = [], slug = [], color = null, icon = null, parent = NotGiven, position = null` | Nový štítok. Názvy, popisy a ručné slugy sú mapy jazykov; reťazec je aktuálny jazyk. Vynechaný parent urobí z nového štítku koreň a zmazaný štítok, ktorý názov vráti, nechá tam, kde bol; null žiada koreň. |
| `UpdateTagData` | `name, description, slug, color, icon` | Každé pole je predvolene NotGiven a nemení sa; null vymaže popis, farbu či ikonu; mapa názvu či popisu sa zlúči po jazykoch a prázdna alebo null položka popisu vymaže len daný jazyk. |
| `TagChanges` | `taggable, attached, detached, created, restored` | Čo zápis štítkov naozaj zmenil; isEmpty(), ofType($type). |
| `TagSelection` | `tags, type` | Vstup volania so štítkami; TagSelection::of($tags, $type) pre akcie. |
| `TagNode` | `tag, children` | Jeden uzol z tree(), deti v poradí pozície. |
| `RepairOptions` | `paths = true, scopeKeys = true, counts = true, orphans = true, type = null, dryRun = false` | Čo opraví Tags::repair(). |
| `RepairReport` | `paths, cycles, scopeKeys, counts, orphans, unresolvableTypes, dryRun, trashedTaggings` | Čo oprava našla a opravila; isClean(). |

## PHP API dôveruje volajúcemu

Fasáda vynucuje doménové pravidlá — typy, limity, kurátorované zoznamy, rozsahy, strom — no nikdy sa nepýta Gate. Oprávnenia v tags.authorization strážia len JSON API; o tom, kto smie čo volať cez fasádu, rozhoduje váš kód.

## Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

[Ďalšie spôsoby podpory vrátane kryptomien](https://roundly-consulting.com/sk/podporte-nas.md)

Odoslaním daru súhlasíte s našimi [podmienkami prijímania darov](https://roundly-consulting.com/sk/podmienky-darov.md).

[Podporte našu open-source prácu (otvorí sa v novej karte)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Pridajte sa k nám na Patreone (otvorí sa v novej karte)](https://www.patreon.com/cw/roundly)

## Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

[Ponuka do 48 hodín](https://roundly-consulting.com/sk/kontakt.md) [Prezrieť všetky balíky](https://roundly-consulting.com/sk/open-source/navody/tags-for-laravel.md)