NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Tags for Laravel

Označovanie modelov

Štítky modelu zapisujú štyri metódy, rovnako na traite, na handle for() aj na fasáde. Typ je vždy posledný, voliteľný argument:

use RoundlyConsulting\Tags\DataTransferObjects\TagKey;

$live = Tags::type('label')->make('Live')->create();

// A model, a primary key (int), a slug or a name — mixed freely, the type last
$concert->attachTags([$live, 42, 'outdoor', 'Late night'], 'label');

// Keys of any key type (int, uuid, ulid) — they only ever resolve an existing tag
$concert->syncTags(Tags::keys($validated['labels']), 'label');
$concert->attachTags(TagKey::of('01JD3N8K2Q6ZB5W7R9T4XHV0YC'), 'label');   // UnknownTagKeyException if no such tag

// Unknown names of a free-form type are created on the fly; a curated type never creates
$concert->attachTags('Polka', 'genre');                  // TagNotFoundException

// A single type carries one tag: sync replaces it, attach refuses a second one
$concert->syncTags('jazz', 'genre');                      // sets the category
$concert->attachTags('rock', 'genre');                    // TagLimitExceededException — nothing written
$concert->syncTags(null, 'genre');                        // clears it

// Detach is lenient: names that name no tag are ignored
$concert->detachTags(['outdoor', 'no-such-label'], 'label');
$concert->clearTags('label');                             // every label
$concert->clearTags();                                    // every tag of every type
  • Vstupom je model Tag, primárny kľúč (int alebo TagKey akéhokoľvek typu kľúča), slug alebo názov — jeden alebo ľubovoľný iterovateľný zoznam. Obyčajný reťazec je názov, nikdy kľúč — okrem prípadu, keď je zapnuté tags.string_keys (nižšie).
  • attach pridáva. Neznáme názvy voľného typu sa vytvoria v rozsahu modelu; kurátorovaný typ nikdy nevytvára (TagNotFoundException). Prekročenie limitu typu vyhodí TagLimitExceededException a nezapíše nič — aj pri type s jedným štítkom.
  • sync nastaví štítky modelu jedného typu presne na zadanú množinu: zvyšné odpojí a chýbajúce pripojí; štítky iných typov nemení. sync(null) alebo sync([]) typ vyprázdni. Bez typu synchronizuje predvolený typ.
  • detach je zhovievavý — názvy bez štítku, zmazané štítky a štítky iného rozsahu preskočí — takže je idempotentný. Názov odoberie každý štítok, ktorý model pod ním v svojich rozsahoch nesie: globálny rock zmizne, aj keď jeho rozsah medzitým dostal vlastný rock, kým attach stále uprednostní štítok rozsahu.
  • clear odoberie všetky štítky jedného typu alebo všetkých typov.
  • Každá metóda označovania — na fasáde, handle aj traite — potom zahodí načítaný vzťah tags modelu, takže tagsOf() aj vaše resources vidia zápis.
  • Limit sa kontroluje len pre typy, do ktorých volanie pridáva, takže model, ktorý už limit po jeho znížení prekračuje, sa stále môže zmenšiť.

Kľúče: TagKey a Tags::keys()

TagKey::of($id) obalí jeden kľúč a Tags::keys($ids) zoznam — inty, reťazce alebo TagKey; čokoľvek iné vyhodí InvalidArgumentException. Kľúč vždy len nájde existujúci štítok: nikdy sa nečíta ako názov, takže z reťazca uuid či ulid už nemôže vzniknúť voľný štítok pomenovaný podľa neho. Kľúče fungujú všade, kde zoznam štítkov — attachTags, detachTags a syncTags (aj Tags::for() a ploché metódy), hasTag / hasAnyTags / hasAllTags, scopes withAnyTags / withAllTags / withoutTags a v katalógu find, findOrFail, findTrashed, findMany a reorder. Kľúč, ktorý neoznačuje žiadny použiteľný štítok (chýbajúci alebo chybný):

VolanieVýsledok
attach / syncUnknownTagKeyException (TagNotFoundException, kód tag_not_found) — nič sa nezapíše, žiadny štítok nevznikne.
detachPreskočí sa.
Query scopes, has*, find*Nevyhovie ničomu / null / false.

Kľúč iného rozsahu vyhodí TagScopeMismatchException, rovnako ako model iného rozsahu. Aj obyčajný int, ktorý neoznačuje žiadny štítok, vyhodí UnknownTagKeyException.

tags.string_keys (voliteľné)

Pri inštalácii s uuid alebo ulid číta tags.string_keys = true obyčajný reťazec, ktorý zodpovedá typu kľúča, najprv ako kľúč — presne tak, akoby bol obalený v TagKey — v metódach označovania, čítaniach, query scopes, TagsFilter aj TagsRule (režim názvov takú položku validuje ako kľúč typu). Neznámy reťazec v tvare kľúča potom vyhodí UnknownTagKeyException namiesto vytvorenia štítku a názov, ktorý sám vyzerá ako kľúč, je pri zapnutom prepínači dostupný len ako model Tag. Pri inštalácii s bigint nemá žiadny účinok: čísla zostávajú názvami. V 2.x je predvolene vypnutý.

Reťazenie

$concert
    ->syncTags($jazz, 'genre')                            // each write returns the model…
    ->attachTags(['Live', 'Outdoor'], 'label');

Tags::for($concert)
    ->detach('outdoor', 'label')                          // …or the handle, which drops the loaded
    ->attach('Rooftop', 'label')                          //    tags relation after every write
    ->of('label');                                        // Live, Rooftop

Čo sa naozaj zmenilo

Ploché metódy fasády vracajú TagChanges — ten istý objekt, ktorý vracia každá akcia:

$changes = Tags::sync($concert, ['live', 'Outdoor', 'Rooftop'], 'label');

$changes->attached;       // list<Tag> — put on the model by this call
$changes->detached;       // list<Tag> — taken off by this call
$changes->created;        // the attached tags this call created for new free-form names
$changes->restored;       // the attached tags this call brought back from deleted
$changes->isEmpty();      // true when nothing was attached or detached
$changes->ofType('label');

Tagged a Untagged sa spustia len vtedy, keď sa niečo zmenilo, a až po potvrdení transakcie; TagCreated alebo TagRestored sa spustí pre každý štítok, ktorý voľný názov vytvoril alebo vrátil.

Reťazce a predvolený typ

// No type: a string names a tag of tags.default_type ('tag' — flat, free-form, unlimited)
$article->attachTags(['laravel', 'php']);
$article->tagsOf('tag');

// Models and keys carry their own type, so a list may mix types when no type is given
$article->attachTags([$jazz, $live]);

// 'default_type' => null (or blank): every string must name its type
$article->attachTags('laravel');           // UnknownTagTypeException (type_required)

Poradie kontrol

Každé attach a sync vyhodnocuje vstup v pevnom poradí, takže to isté volanie zlyhá vždy rovnako — a nič sa nezapíše, kým neprejdú všetky kontroly:

#KontrolaVýnimka
1Kľúč bez štítku, potom viditeľnosť vstupu: model alebo kľúč štítku z rozsahu, ktorý model nevidí, odpovie presne ako chýbajúci — skôr, než by čokoľvek iné potvrdilo, že existuje.UnknownTagKeyException / TagScopeMismatchException
2Zmazaný štítok.TagNotFoundException
3Štítok iného typu, než uvádza volanie.TagTypeMismatchException
4Typy, ktoré model smie niesť, z oboch strán: zoznam on() typu a tagTypes() modelu.TagTypeNotAllowedException
5Reťazce: prázdny či pridlhý názov je neplatný; neznámy názov kurátorovaného typu sa nenájde.InvalidTagException / TagNotFoundException
6Limit každého typu, do ktorého volanie pridáva — volanie vyhodí výnimku a nezapíše nič.TagLimitExceededException

Čítanie bez N+1

foreach (Concert::with('tags')->get() as $concert) {
    echo $concert->tagOf('genre')?->name;                         // Jazz — filtered in memory
    echo $concert->tagsOf('label')->pluck('name')->join(', ');    // Live, Outdoor
}

$concert->hasTag('live', 'label');                  // a model, a key, a name or a slug
$concert->hasAnyTags(['live', 'free'], 'label');
$concert->hasAllTags(['live', 'outdoor'], 'label');

Tags::for($concert)->all();                         // every tag, by position
Tags::for($concert)->one('genre');                  // the same as tagOf()

tagsOf() a tagOf() pri načítanom vzťahu tags filtrujú v pamäti, inak spustia jeden dotaz — stránka s 25 modelmi a ich štítkami sú teda dva dotazy bez ohľadu na počet štítkov. Čítanie ignoruje priradenia zmazaného štítku.

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.

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.