Metaúdaje komentárov

Každý komentár má stĺpec meta typu json s povolenou hodnotou null — jsonb na PostgreSQL, json na MySQL, text na SQLite — s castom na pole. Uložíte doň to, čo vaša aplikácia potrebuje o komentári vedieť a čo telo ani stav nepovedia: kanál, ktorým prišiel, rolu autora či príznak internej poznámky. Stĺpec pribudol vo verzii 1.1.0 vo vlastnej migrácii — postup prechodu nájdete v Inštalácii.

Zápis metaúdajov

Pripojíte ich cez meta() v builderi alebo argumentom meta: v WriteCommentData:

use RoundlyConsulting\Comments\DataTransferObjects\WriteCommentData;
use RoundlyConsulting\Comments\Facades\Comments;

Comments::on($ticket)
    ->as($agent)
    ->body('Checked the logs, looks like a timeout.')
    ->visible(false)
    ->meta(['tickets' => ['internal' => true, 'role' => 'agent', 'channel' => 'web']])
    ->post();

Comments::write(new WriteCommentData(commentable: $post, body: 'Hi', meta: ['source' => 'import']));

• Opakované volania meta() sa zlúčia: kľúče najvyššej úrovne z neskoršieho volania nahradia skoršie a ostatné kľúče zostanú — ide o plytké array_replace, nie o hĺbkové zlúčenie.
• Kľúče zoskupte pod vlastný menný priestor (['tickets' => [...]]), aby sa dva balíky, prípadne balík a vaša aplikácia, pri zápise do toho istého komentára navzájom neprepisovali.
• Prázdne znamená žiadne: meta([]), predvolená hodnota, neuloží nič a stĺpec zostane null.
• Poradie kľúčov sa nezachová — PostgreSQL jsonb aj MySQL kľúče objektov preusporiadajú, preto porovnávajte obsah, nie poradie.
• Comments::update() metaúdaje nemení a neskôr ich zmeniť nemožno žiadnou metódou — zapíšte ich pri uverejnení komentára.

Comments::on($ticket)
    ->body('Forwarded from the help desk.')
    ->meta(['tickets' => ['role' => 'agent']])
    ->meta(['source' => 'email'])                 // merged: 'tickets' is kept
    ->meta(['tickets' => ['internal' => true]])   // replaces the whole 'tickets' key
    ->post();
// stored: ['tickets' => ['internal' => true], 'source' => 'email']

Čítanie metaúdajov

$comment->meta();                             // the whole array — [] when there is none
$comment->meta('tickets.role');               // 'agent'
$comment->meta('tickets.priority', 'normal'); // the default when the path is absent
$comment->hasMeta('tickets.internal');        // true — a key holding null counts as present
$comment->meta;                               // the raw cast attribute: array|null

Filtrovanie podľa metaúdajov

Fluentné query podľa nich filtruje a filtre sa kombinujú so všetkým ostatným v CommentQuery — s radením, počtami aj hromadným moderovaním:

use RoundlyConsulting\Comments\Facades\Comments;

Comments::for($ticket)->whereMeta('tickets.internal', false)->oldest()->get();   // the public replies
Comments::for($ticket)->whereMeta('tickets.role', 'agent')->count();
Comments::for($post)->whereMetaMissing('tickets')->get();                       // comments no package tagged
Comments::for($ticket)->whereMeta('tickets.internal', true)->hideAll();         // composes with bulk moderation

• whereMeta($path, $value) vyberie komentáre, ktoré majú na ceste $path hodnotu $value. Porovnávajte s tým PHP typom, ktorý ste uložili: json boolean zodpovedá true alebo false, json číslo hodnote int, json reťazec hodnote string — SQLite nepovažuje 5 a '5' za rovnaké. Hodnota je string, int alebo bool; ak hľadáte chýbajúci kľúč, použite whereMetaMissing().
• whereMetaMissing($path) vyberie komentáre, ktorým cesta $path chýba, vrátane komentárov úplne bez metaúdajov. Kľúč s hodnotou json null je prítomný — rovnaké pravidlo ako pri hasMeta().
• Cesty sa zapisujú malými písmenami v bodkovej notácii a kontrolujú sa ešte pred tým, než sa dostanú do SQL: segmenty z malých písmen, číslic a podčiarkovníkov, pričom žiadny nesmie obsahovať iba číslice. Čokoľvek iné — Tickets.role, tickets->role, $.tickets, tickets.*, tickets[0] — vyhodí InvalidCommentMetaPathException. Hodnota sa vždy odovzdáva ako viazaný parameter.
• Filtre používajú json syntax ciest query buildera, takže sa na SQLite, PostgreSQL aj MySQL správajú rovnako — vlastná testovacia sada balíka ich spúšťa na všetkých troch.

V testoch a v JSON

Factory modelu Comment má stav meta([...]) — pozrite Testovanie. CommentResource meta nevracia, pretože metaúdaje často obsahujú interné príznaky; resource rozšírte o to, čo má vaše API zobraziť.