Úprava, mazanie a obnovenie

use RoundlyConsulting\Comments\Facades\Comments;

Comments::update($comment, 'Edited body');                  // dispatches CommentUpdated
Comments::update($comment, 'Edited body', editor: $user);   // names the editor in the edit history
Comments::delete($comment);                // soft delete, dispatches CommentDeleted
Comments::restore($comment);               // restore a soft-deleted comment

Comments::update() na nové telo uplatní pravidlá zápisu: oreže ho a skontroluje dĺžku, zastaví ho zámok subjektu alebo zamknuté vlákno (CommentsLockedException) a preverí ho blocklistom presne ako pri zápise — zhodu akcia reject odmietne, inak sa komentár presunie do pending alebo hidden. Zmienky sa po každej úprave znova zosynchronizujú a odošle sa CommentUpdated.

Soft deletes

Komentáre sa mažú mäkko (soft delete), takže sa nič nestratí omylom. Comments::delete() odošle CommentDeleted; Comments::restore() komentár vráti bez odoslania udalosti. Zmazané komentáre zostávajú dostupné cez soft-delete scopy Eloquentu:

use RoundlyConsulting\Comments\Models\Comment;

Comment::onlyTrashed()->get();     // soft-deleted comments
Comment::withTrashed()->find($id); // include soft-deleted rows

Akcia za update()

Comments::update() spúšťa UpdateCommentAction, ktorá prijíma DTO UpdateCommentData — z jobu ju môžete zavolať priamo (pozrite DI a akcie):

use RoundlyConsulting\Comments\Actions\UpdateCommentAction;
use RoundlyConsulting\Comments\DataTransferObjects\UpdateCommentData;

app(UpdateCommentAction::class)->execute(new UpdateCommentData(
    comment: $comment,
    body: 'Edited body',
    editor: $user, // optional — recorded on the revision while edit_history is on
));

Pri zapnutej autorizácii úprava kontroluje ability update, mazanie ability delete a obnovenie ability restore.

História úprav

Zapnite comments.edit_history (COMMENTS_EDIT_HISTORY=true) a každá úprava uloží nahradené telo ako číslovanú revíziu do tabuľky comment_revisions spolu s autorom úpravy a časom. Predvolene je vypnutá — úprava potom telo prepíše ako doteraz. Autora úpravy uvediete argumentom editor: v Comments::update() alebo v UpdateCommentData; bez neho revízia autora úpravy neuvádza:

// .env
COMMENTS_EDIT_HISTORY=true

use RoundlyConsulting\Comments\Facades\Comments;

$comment = Comments::on($post)->as($author)->body('Original')->post();

Comments::update($comment, 'Second', editor: $moderator);
Comments::update($comment, 'Third');            // no editor — the revision records none
Comments::update($comment, '  Third  ');        // same body once trimmed — no revision

$comment->comment;                              // 'Third' — the current body lives on the comment

Históriu prečítate cez Comments::history($comment) — od najstaršej úpravy, každú revíziu s načítaným autorom úpravy — alebo cez vzťah $comment->revisions. Každá revízia obsahuje telo, ktoré daná úprava nahradila; aktuálne telo zostáva na komentári:

$history = Comments::history($comment);   // oldest edit first, editor loaded

foreach ($history as $revision) {
    $revision->revision;     // 1, 2, 3… in the order the edits landed
    $revision->body;         // the body that edit replaced
    $revision->editor;       // the model passed as editor:, or null
    $revision->editedAt();   // when the edit landed (its created_at)
    $revision->comment;      // the edited comment, as your comments.model class
}

$comment->revisions;         // the same rows as a relation, ordered by revision

• Revízie sa v rámci komentára číslujú 1, 2, 3… v poradí, v akom úpravy prebehli. Súbežné úpravy serializuje zámok riadka komentára v transakcii, takže každá prečíta telo, ktoré potvrdila predchádzajúca úprava — nikdy zastaranú kópiu — a každá úprava sa do histórie dostane v správnom poradí. Zámok zálohuje unikátny index nad komentárom a číslom revízie.
• Úprava, ktorá telo (po orezaní) nezmení, revíziu nezapíše; odmietnutá úprava — reject blocklistu, zámok, zamietnutá policy — nezapíše nič.
• Blocklist platí aj pre zaznamenanú úpravu: zhoda podrží komentár v pending alebo hidden presne ako bez histórie.
• Kým je prepínač vypnutý, žiadny zámok sa neberie a Comments::history() vráti prázdnu kolekciu.
• CommentResource vykreslí históriu ako history, keď je načítaný vzťah revisions — pozrite API resources.

Zmazané komentáre ako zástupné záznamy

Predvolene mäkko zmazaný komentár z verejného vlákna vypadne — a s ním aj odpovede pod ním. Ak comments.deleted_comments (COMMENTS_DELETED_COMMENTS) nastavíte na placeholder, ponechá si svoje miesto: threadedComments() aj approvedComments() ho naďalej vrátia spolu s odpoveďami, na každej úrovni:

// .env
COMMENTS_DELETED_COMMENTS=placeholder

Comments::delete($root);

$thread = $post->threadedComments;          // $root is still here, with its replies

$thread[0]->trashed();                      // true
$thread[0]->isPlaceholder();                // true — deleted, and placeholder mode is on
$thread[0]->replies;                        // the live replies under it still load

$post->loadCommentCount()->comments_count;  // the placeholder is not counted

• $comment->isPlaceholder() vráti true pre mäkko zmazaný komentár, kým je zapnutý režim placeholder; pri remove vždy false.
• Zostanú len zmazané komentáre, ktoré by inak boli verejné — zmazaný komentár v stave pending, hidden alebo s visible(false) zostáva mimo verejného vlákna.
• Zástupné záznamy sa nepočítajú: loadCommentCount() a withCommentCounts() rátajú len živé verejné komentáre.
• CommentResource vykreslí zástupný záznam ako deleted: true, s body a author null a bez príloh, páčikov či histórie, takže server neopustí nič z toho, čo komentár obsahoval, ani kto ho napísal — pozrite API resources.
• Iná hodnota než remove alebo placeholder vyhodí InvalidConfigurationException s názvom kľúča; prázdna hodnota znamená predvolené remove.

Vo fluentnom query withDeleted() ponechá vo výsledku aj mäkko zmazané komentáre — na najvyššej úrovni a s withReplies() aj v načítaných odpovediach, bez ohľadu na poradie volaní. Funguje v oboch režimoch; obsah skryjete vykreslením cez CommentResource pri zapnutom režime placeholder:

use RoundlyConsulting\Comments\Facades\Comments;

// Keep deleted comments in a query — roots and loaded replies, in any call order:
Comments::for($post)->visible()->rootsOnly()->withReplies()->withDeleted()->get();

// Bulk moderation still acts only on comments that are not deleted:
Comments::for($post)->withDeleted()->hideAll();