API resources

Hotový JSON výstup pre SPA a mobilné backendy:

use RoundlyConsulting\Comments\Http\Resources\CommentResource;

return CommentResource::collection(
    $post->threadedComments()->with(['actor', 'likes', 'media'])->get(),
);

threadedComments() je verejné vlákno, takže JSON obsahuje len viditeľné a schválené komentáre najvyššej úrovne a odpovede. Resource vykreslí čokoľvek, čo dostane — kľúč replies je akýkoľvek načítaný vzťah replies — preto mu na verejných endpointoch odovzdávajte verejné query: threadedComments() alebo CommentQuery s visible() a withReplies().

Payload likes sa vykresľuje bez diváka, takže viewer_state je stav hosťa — údaje pre konkrétneho diváka získate cez withLikedState($viewer) v query alebo likeState($viewer). URL príloh sa určujú podľa viditeľnosti každej prílohy — pri súkromných sú podpísané a krátkodobé.

Resource nevracia meta, pretože metaúdaje často obsahujú interné príznaky. CommentResource je final — ak chcete meta zobraziť, vykresľujte komentáre cez vlastný resource.

Komentár s načítanými vzťahmi actor a replies sa vykreslí takto:

{
  "id": 7,
  "body": "Great post!",
  "status": "approved",
  "visible": true,
  "parent_id": null,
  "locked": false,
  "author": { "id": 42, "type": "User" },
  "replies": [],
  "created_at": "2026-10-18T09:30:00+00:00",
  "updated_at": "2026-10-18T09:30:00+00:00"
}

author sa vykreslí cez CommentAuthorResource: kľúč a krátky názov triedy, nikdy nie uložený actor_type — bez morph mapy je to celý názov triedy (App\Models\User) a žiadny názov PHP triedy sa ku klientovi API nedostane. type je krátky názov triedy s morph mapou aj bez nej; alias ako member sa nevykreslí ani vtedy.

Vlastný tvar autora

Nastavte comments.resources.author na vlastného potomka JsonResource. Dostane model autora (actor) pri komentároch najvyššej úrovne aj pri vnorených odpovediach — pre autorov odpovedí načítajte replies.actor:

// config/comments.php
'resources' => [
    'author' => App\Http\Resources\AuthorResource::class,
],

// app/Http/Resources/AuthorResource.php
final class AuthorResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->resource->getKey(),
            'name' => $this->resource->name,
            'avatar_url' => $this->resource->avatar_url,
        ];
    }
}

Ak komentáre píše viac typov modelov, rozlíšte ich vo vlastnom resource. Prázdna hodnota alebo null znamená pribalený CommentAuthorResource; čokoľvek, čo nie je inštanciovateľný potomok JsonResource, vyhodí InvalidConfigurationException s názvom kľúča.

História úprav

Pri zapnutom comments.edit_history načítajte revisions — a pre autorov úprav revisions.editor — a resource pridá history, od najstaršej úpravy:

use RoundlyConsulting\Comments\Http\Resources\CommentResource;

return new CommentResource($comment->load(['actor', 'revisions.editor']));

"history": [
  { "revision": 1, "body": "Original", "editor": { "id": 42, "type": "User" }, "edited_at": "2026-11-09T10:00:00+00:00" },
  { "revision": 2, "body": "Second",   "editor": null,                        "edited_at": "2026-11-09T11:00:00+00:00" }
]

Každý autor úpravy sa vykreslí cez CommentEditorResource — kľúč a krátky názov triedy, nikdy nie uložený editor_type — a zmazaný autor úpravy ako null; bez načítaného revisions.editor sa editor vynechá. Tvar zmeníte cez comments.resources.editor, za rovnakých pravidiel ako resource autora:

// config/comments.php
'resources' => [
    'author' => App\Http\Resources\AuthorResource::class,
    'editor' => App\Http\Resources\AuthorResource::class, // receives the editor model
],

Zástupné záznamy

Pri comments.deleted_comments = placeholder má každý komentár pole deleted. Mäkko zmazaný sa vykreslí len ako štruktúra — id, status, visible, parent_id, locked a replies — s body a author null a bez likes, attachments či history, aj keď sú načítané. Jeho živé odpovede sa vykreslia celé. Pri predvolenom remove sa deleted vynechá:

{
  "id": 7,
  "body": null,
  "status": "approved",
  "visible": true,
  "parent_id": null,
  "locked": false,
  "deleted": true,
  "author": null,
  "replies": [
    {
      "id": 8,
      "body": "Agreed.",
      "status": "approved",
      "visible": true,
      "parent_id": 7,
      "locked": false,
      "deleted": false,
      "author": { "id": 43, "type": "User" },
      "replies": [],
      "created_at": "2026-11-09T09:45:00+00:00",
      "updated_at": "2026-11-09T09:45:00+00:00"
    }
  ],
  "created_at": "2026-11-09T09:30:00+00:00",
  "updated_at": "2026-11-09T10:00:00+00:00"
}

Kolekcie a stránkovanie

CommentCollection zbiera CommentResource a funguje aj so stránkovaným výsledkom:

use RoundlyConsulting\Comments\Facades\Comments;
use RoundlyConsulting\Comments\Http\Resources\CommentCollection;

return new CommentCollection(
    Comments::for($post)->visible()->rootsOnly()->withReplies()->paginate(20),
);