Konfigurácia

Balík funguje bez akejkoľvek konfigurácie. Súbor config/tags.php publikujte, len ak chcete niečo zmeniť:

php artisan vendor:publish --tag="tags-config"

Každý kľúč sa číta striktne: nenastavená hodnota — chýbajúca, null alebo prázdna — preberie predvolenú a chybná vyhodí InvalidTagsConfigurationException (alebo InvalidConfigurationException z package toolkitu) s názvom kľúča, nikdy nie tichý návrat k predvolenej hodnote.

Booleovské hodnoty sa čítajú ako true/false, 1/0, on/off alebo yes/no; čokoľvek iné vyhodí výnimku.
Celé čísla prijímajú int alebo reťazec s celým číslom a musia byť v rozsahu uvedenom v tabuľke — 5.5 či five vyhodí výnimku, namiesto toho, aby sa z nich stala 0.
Názvy tabuliek sú z písmen, číslic a podčiarkovníkov; názvy typov sú malými písmenami s voliteľným prefixom balíka; aliasy sú v snake_case.

Konfiguračný súbor

use RoundlyConsulting\Tags\Http\Resources\TagScopeResource;
use RoundlyConsulting\Tags\Models\Tag;

return [
    'primary_key_type' => env('TAGS_PRIMARY_KEY_TYPE', 'bigint'),
    'key_type' => env('TAGS_KEY_TYPE', 'bigint'),

    'tables' => [
        'tags' => 'tags',
        'taggables' => 'taggables',
        'locks' => 'tag_locks',
    ],

    'models' => [
        'tag' => Tag::class,
    ],

    'default_type' => 'tag',
    'types' => [],
    'overrides' => [],

    'names' => [
        'max_length' => 64,
    ],

    'descriptions' => [
        'max_length' => 500,
    ],

    'slugs' => [
        'max_length' => 80,
        'separator' => '-',
        'unicode' => false,
        'dictionary' => ['+' => 'plus', '#' => 'sharp', '&' => 'and', '@' => 'at'],
    ],

    'hierarchy' => [
        'max_depth' => 5,
    ],

    'suggest' => [
        'limit' => 10,
        'max_limit' => 50,
    ],

    'popular' => [
        'limit' => 10,
        'max_limit' => 100,
    ],

    'scopes' => [],
    'taggables' => [],

    'resources' => [
        'scope' => TagScopeResource::class,
    ],

    'authorization' => [
        'abilities' => [
            'view' => null,
            'manage' => 'tags.manage',
            'scope' => 'tags.scope',
        ],
    ],

    'routes' => [
        'enabled' => env('TAGS_ROUTES') ?: 'off',
        'prefix' => 'api',
        'middleware' => ['api', 'auth', 'throttle:tags-api'],
        'rate_limit' => 120,
        'suggest_rate_limit' => 120,
        'max_per_page' => 100,
        'max_tree_nodes' => 1000,
    ],
];

Typy kľúčov

Kľúč	Env	Predvolené	Účel
`primary_key_type`	`TAGS_PRIMARY_KEY_TYPE`	bigint	Vlastné kľúče balíka — tags.id, tags.parent_id a taggables.tag_id: bigint, uuid alebo ulid. Čítajú ho migrácie, preto ho nastavte pred migráciou; potom je zafixovaný.
`key_type`	`TAGS_KEY_TYPE`	bigint	Kľúče, na ktoré balík ukazuje: musí ho používať každý model so štítkami (taggable_id) aj každý model rozsahu (scope_id). Model s iným kľúčom vyhodí InvalidTagsConfigurationException, keď ho označíte alebo použijete ako rozsah; tags:doctor to nahlási.

Tabuľky a model štítku

Kľúč	Env	Predvolené	Účel
`tables.tags`	—	tags	Tabuľka štítkov. Písmená, číslice a podčiarkovníky; ak už aplikácia tabuľku tags má, premenujte ju pred migráciou.
`tables.taggables`	—	taggables	Spojovacia tabuľka — jeden riadok na štítok na modeli.
`tables.locks`	—	tag_locks	Jeden riadok zámku na strom (typ a rozsah). Každý názov tabuľky držte najviac na 30 znakoch: tvoria sa z neho názvy indexov v MySQL.
`models.tag`	—	Models\Tag	Model štítku; náhrada musí byť podtriedou modelu z balíka. Každý dotaz, vzťah aj factory použije nakonfigurovanú triedu.

Typy štítkov

Kľúč	Env	Predvolené	Účel
`default_type`	—	tag	Typ, ktorý označuje obyčajný reťazec, keď volanie typ neuvedie. Ak ho nikto nedefinuje, je plochý, voľný a bez limitu. Prázdna hodnota alebo null = žiadny predvolený typ: každý reťazec potom musí uviesť svoj typ.
`types`	—	[]	Vlastné typy aplikácie: názov => pravidlá (pozrite Typy štítkov).
`overrides`	—	[]	Pravidlá aplikované na akýkoľvek typ — aj typ iného balíka — po jeho definícii a všetkých callbackoch Tags::extend().

Názvy, popisy a slugy

Kľúč	Env	Predvolené	Účel
`names.max_length`	—	64	Znakov na jazyk, 1–255.
`descriptions.max_length`	—	500	Znakov na jazyk, 1–10000. Popisy sú čistý text.
`slugs.max_length`	—	80	Znakov na slug, 1–255.
`slugs.separator`	—	-	Jeden až tri zo znakov - . _ ~.
`slugs.unicode`	—	false	Ponechať v slugoch ne-ASCII písmená (CJK, cyrilika, …). Pri vypnutí sa názov, z ktorého nezostane žiadne ASCII písmeno ani číslica, odmietne ako nevhodný na slug.
`slugs.dictionary`	—	+ plus, # sharp, & and, @ at	Znaky, ktoré sa v slugoch vypíšu slovom, takže C, C++ a C# zostanú tri štítky (c, c-plus-plus, c-sharp).

Hierarchia, našepkávanie a popularita

Kľúč	Env	Predvolené	Účel
`hierarchy.max_depth`	—	5	Najhlbší strom, 1–10 úrovní (koreň je úroveň 1). Typ, ktorý chce viac, sa na túto hodnotu oreže.
`suggest.limit`	—	10	Počet návrhov, keď volanie limit neuvedie, od 1 po suggest.max_limit.
`suggest.max_limit`	—	50	Najviac návrhov, ktoré jedno volanie vráti, 1–1000.
`popular.limit`	—	10	Počet najpoužívanejších štítkov, keď volanie limit neuvedie, od 1 po popular.max_limit.
`popular.max_limit`	—	100	Najviac štítkov, ktoré jedno volanie popularity vráti, 1–1000.

Aliasy a resources pre API

Kľúč	Env	Predvolené	Účel
`scopes`	—	[]	Alias pre API => trieda modelu rozsahu, pre ?scope=alias:kľúč. Aliasy sú v snake_case (^[a-z][a-z0-9_]{0,63}$); názov triedy sa nikdy neprijme.
`taggables`	—	[]	Alias pre API => trieda modelu so štítkami, pre popular?on=alias.
`resources.scope`	—	TagScopeResource::class	JsonResource, cez ktorý sa vykreslí vlastník štítku s rozsahom; dostane model rozsahu. Prázdna hodnota alebo null = {id, type} z balíka; čokoľvek, čo nie je inštanciovateľný potomok JsonResource, vyhodí výnimku s názvom kľúča.

Autorizácia

Kľúč	Env	Predvolené	Účel
`authorization.abilities.view`	—	null	Gate oprávnenie, ktorého sa API pýta pred každým čítaním, s názvom typu a rozsahom. null = bez kontroly.
`authorization.abilities.manage`	—	tags.manage	Gate oprávnenie, ktorého sa API pýta pred každým zápisom, s názvom typu a cieľovým rozsahom (null = globálny zápis). Rozhoduje aj o tom, kto vidí súkromné typy a — vždy v rozsahu daného štítku, takže globálny štítok si pýta globálnu správu — počty použití, preklady a zmazané štítky. Prázdna hodnota = tags.manage.
`authorization.abilities.scope`	—	tags.scope	Gate oprávnenie, ktorého sa API pýta s modelom rozsahu vždy, keď požiadavka pošle ?scope=. Zamietnutý rozsah odpovie 422 unknown_alias presne ako rozsah, ktorý neexistuje, takže odkaz neprezradí id žiadneho tenanta. Prázdna hodnota = tags.scope.

JSON API

Kľúč	Env	Predvolené	Účel
`routes.enabled`	`TAGS_ROUTES`	off	Sprístupní JSON API — vypnuté, kým ho nezapnete. Zapísané ako env('TAGS_ROUTES') ?: 'off' a nenastavený prepínač (chýbajúci v publikovanej konfigurácii, ktorej pole routes prepisuje len niektoré kľúče, null alebo prázdny) je tiež vypnutý.
`routes.prefix`	—	api	Prefix URI; lomky na okrajoch sa odstránia, null = žiadny.
`routes.middleware`	—	['api', 'auth', 'throttle:tags-api']	Middleware každého endpointu; so Sanctum použite auth:sanctum. tags:doctor upozorní, ak v zozname nie je žiadne auth middleware.
`routes.rate_limit`	—	120	Požiadavky za minútu na používateľa (na IP pri anonymnom volajúcom) v limiteri tags-api, 1–100000.
`routes.suggest_rate_limit`	—	120	Požiadavky za minútu na používateľa (inak na IP) vo vlastnom limiteri tags-suggest endpointu na našepkávanie.
`routes.max_per_page`	—	100	Najväčšia stránka zoznamu, 1–1000; predvolená veľkosť stránky je 20.
`routes.max_tree_nodes`	—	1000	Najväčšia odpoveď ?tree=1, 1–100000; väčší strom odpovie 422 tree_too_large.

Neskoršia zmena nastavenia slugov mení to, ako sa porovnávajú nové reťazce, nie už uložené slugy — potom spustite sluggable:regenerate na modeli štítku (pozrite Inštaláciu).

Prostredie

Z env sa číta len typ kľúčov a prepínač API:

TAGS_PRIMARY_KEY_TYPE=bigint
TAGS_KEY_TYPE=bigint
TAGS_ROUTES=on

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