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:

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

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

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 Prezrieť všetky balíky