Tag blog posts and sign them with a member

Tags are named in every language and made from the page form; the byline is
the member who signs a post on the site. The public API sends both, filters
posts by tag and lists the tags in use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/Http/Controllers/Api/PublicApi/V1/PageController.php

@@ -6,7 +6,9 @@ namespace App\Http\Controllers\Api\PublicApi\V1;
 
 use App\Http\Resources\PublicApi\PublicPageResource;
 use App\Models\Page;
+use App\Models\Tag;
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 
@@ -15,12 +17,15 @@ class PageController extends PublicController
     public function index(Request $request): AnonymousResourceCollection
     {
         $pages = Page::query()
-            ->with(['category', 'featuredMedia'])
+            ->with(['category', 'featuredMedia', 'tags', 'byline.avatarMedia'])
             ->unless($this->isPreview($request), fn (Builder $q) => $q->published())
             ->when($request->filled('category'), fn (Builder $q) => $q
                 ->whereHas('category', fn (Builder $c) => $c
                     ->where('slug->'.app()->getLocale(), $request->string('category'))))
             ->when($request->boolean('featured'), fn (Builder $q) => $q->where('is_featured', true))
+            ->when($request->filled('tag'), fn (Builder $q) => $q
+                ->whereHas('tags', fn (Builder $t) => $t
+                    ->where('slug->'.app()->getLocale(), $request->string('tag'))))
             ->orderByDesc('published_at')
             ->paginate($this->perPage($request))
             ->withQueryString();
@@ -31,11 +36,38 @@ class PageController extends PublicController
     public function show(Request $request, string $slug): PublicPageResource
     {
         $page = Page::query()
-            ->with(['category', 'featuredMedia'])
+            ->with(['category', 'featuredMedia', 'tags', 'byline.avatarMedia'])
             ->whereSlug($slug)
             ->unless($this->isPreview($request), fn (Builder $q) => $q->published())
             ->firstOrFail();
 
         return PublicPageResource::make($page);
     }
+
+    /**
+     * The tags used by something published, with how many posts each has in
+     * the request's language — for a blog to offer them as a way in.
+     */
+    public function tags(Request $request): JsonResponse
+    {
+        $locale = app()->getLocale();
+        $published = fn (Builder $q) => $q
+            ->unless($this->isPreview($request), fn (Builder $q) => $q->published())
+            ->whereNotNull("slug->{$locale}");
+
+        $tags = Tag::query()
+            ->whereHas('pages', $published)
+            ->withCount(['pages' => $published])
+            ->get()
+            ->filter(fn (Tag $tag) => filled($tag->getTranslation('slug', $locale, false)))
+            ->sortByDesc('pages_count')
+            ->map(fn (Tag $tag) => [
+                'name' => $tag->getTranslation('name', $locale),
+                'slug' => $tag->getTranslation('slug', $locale, false),
+                'count' => (int) $tag->pages_count,
+            ])
+            ->values();
+
+        return response()->json(['data' => $tags]);
+    }
 }

app/Http/Controllers/Api/V1/PageController.php

@@ -17,6 +17,8 @@ use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 
 class PageController extends Controller
 {
+    protected const WITH = ['category', 'author', 'featuredMedia', 'tags'];
+
     /**
      * GET /api/v1/pages
      *
@@ -30,7 +32,7 @@ class PageController extends Controller
         $locale = app()->getLocale();
 
         $pages = Page::query()
-            ->with(['category', 'author', 'featuredMedia'])
+            ->with(self::WITH)
             ->when($request->filled('status'), fn ($q) => $q->where('status', $request->string('status')))
             ->when($request->filled('category_id'), fn ($q) => $q->where('category_id', $request->integer('category_id')))
             ->when($request->has('is_featured'), fn ($q) => $q->where('is_featured', $request->boolean('is_featured')))
@@ -57,7 +59,7 @@ class PageController extends Controller
         $this->authorize('create', Page::class);
 
         $page = new Page;
-        $page->fill(TranslatablePayload::merge($page, $request->validated(), $page->translatable));
+        $page->fill(TranslatablePayload::merge($page, collect($request->validated())->except('tag_ids')->all(), $page->translatable));
         $page->author_id ??= $request->user()->id;
 
         // A page created as published with no explicit date goes live now.
@@ -66,8 +68,9 @@ class PageController extends Controller
         }
 
         $page->save();
+        $this->syncTags($page, $request);
 
-        return PageResource::make($page->load(['category', 'author', 'featuredMedia']))
+        return PageResource::make($page->load(self::WITH))
             ->response()
             ->setStatusCode(201);
     }
@@ -76,22 +79,23 @@ class PageController extends Controller
     {
         $this->authorize('view', $page);
 
-        return PageResource::make($page->load(['category', 'author', 'featuredMedia']));
+        return PageResource::make($page->load(self::WITH));
     }
 
     public function update(PageRequest $request, Page $page): PageResource
     {
         $this->authorize('update', $page);
 
-        $page->fill(TranslatablePayload::merge($page, $request->validated(), $page->translatable));
+        $page->fill(TranslatablePayload::merge($page, collect($request->validated())->except('tag_ids')->all(), $page->translatable));
 
         if ($page->status === PageStatus::Published && $page->published_at === null) {
             $page->published_at = now();
         }
 
         $page->save();
+        $this->syncTags($page, $request);
 
-        return PageResource::make($page->load(['category', 'author', 'featuredMedia']));
+        return PageResource::make($page->load(self::WITH));
     }
 
     public function destroy(Page $page): JsonResponse
@@ -109,7 +113,7 @@ class PageController extends Controller
 
         $page->restore();
 
-        return PageResource::make($page->load(['category', 'author', 'featuredMedia']));
+        return PageResource::make($page->load(self::WITH));
     }
 
     /**
@@ -135,4 +139,11 @@ class PageController extends Controller
 
         $query->orderBy(in_array($column, $sortable, true) ? $column : 'created_at', $direction);
     }
+
+    protected function syncTags(Page $page, PageRequest $request): void
+    {
+        if ($request->has('tag_ids')) {
+            $page->tags()->sync($request->validated('tag_ids') ?? []);
+        }
+    }
 }

app/Http/Controllers/Api/V1/TagController.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Models\Tag;
+use App\Rules\Translatable;
+use App\Rules\UniqueTranslatedSlug;
+use App\Support\TranslatablePayload;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * Blog tags. Small enough that the whole list is one answer.
+ */
+class TagController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $this->authorize('viewAny', Tag::class);
+
+        return response()->json([
+            'data' => Tag::query()->withCount('pages')->orderBy('id')->get()->map(fn (Tag $tag) => $this->present($tag))->values(),
+        ]);
+    }
+
+    public function store(Request $request): JsonResponse
+    {
+        $this->authorize('create', Tag::class);
+
+        $tag = new Tag;
+        $tag->fill(TranslatablePayload::merge($tag, $this->validated($request, null), $tag->translatable))->save();
+
+        return response()->json(['data' => $this->present($tag->loadCount('pages'))], 201);
+    }
+
+    public function update(Request $request, Tag $tag): JsonResponse
+    {
+        $this->authorize('update', $tag);
+
+        $tag->fill(TranslatablePayload::merge($tag, $this->validated($request, $tag), $tag->translatable))->save();
+
+        return response()->json(['data' => $this->present($tag->loadCount('pages'))]);
+    }
+
+    public function destroy(Tag $tag): JsonResponse
+    {
+        $this->authorize('delete', $tag);
+
+        $tag->delete();
+
+        return response()->json(status: 204);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function validated(Request $request, ?Tag $tag): array
+    {
+        $sometimes = $tag === null ? 'required' : 'sometimes';
+
+        return $request->validate([
+            'name' => [$sometimes, new Translatable(requireDefaultLocale: $tag === null, max: 80)],
+            'slug' => [$sometimes, new Translatable(requireDefaultLocale: $tag === null, max: 80), new UniqueTranslatedSlug(Tag::class, $tag?->id)],
+        ]);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function present(Tag $tag): array
+    {
+        return [
+            'id' => $tag->id,
+            'name' => (object) $tag->getTranslations('name'),
+            'slug' => (object) $tag->getTranslations('slug'),
+            'pages_count' => (int) ($tag->pages_count ?? 0),
+        ];
+    }
+}

app/Http/Requests/Api/V1/PageRequest.php

@@ -49,6 +49,10 @@ class PageRequest extends FormRequest
             'meta_description' => ['sometimes', 'nullable', new Translatable(max: 160)],
 
             'category_id' => ['sometimes', 'nullable', 'integer', Rule::exists('categories', 'id')->whereNull('deleted_at')],
+            // Who signs it on the site; replaced whole when sent, like the tags.
+            'byline_member_id' => ['sometimes', 'nullable', 'integer', Rule::exists('members', 'id')->whereNull('deleted_at')],
+            'tag_ids' => ['sometimes', 'array'],
+            'tag_ids.*' => ['integer', 'distinct', Rule::exists('tags', 'id')],
             'status' => ['sometimes', Rule::enum(PageStatus::class)],
             'featured_image' => ['sometimes', 'nullable', 'string', 'max:2048'],
             'featured_image_alt' => ['sometimes', 'nullable', new Translatable(max: 255)],

app/Http/Resources/PageResource.php

@@ -49,6 +49,8 @@ class PageResource extends JsonResource
 
             'category' => CategoryResource::make($this->whenLoaded('category')),
             'author' => UserResource::make($this->whenLoaded('author')),
+            'byline_member_id' => $this->byline_member_id,
+            'tag_ids' => $this->whenLoaded('tags', fn () => $this->tags->pluck('id')->values()),
 
             // Opt-in: `?with=translations` returns every language at once,
             // which is what a translation UI needs and a page renderer does not.

app/Http/Resources/PublicApi/PublicPageResource.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Http\Resources\PublicApi;
 
 use App\Models\Page;
+use App\Models\Tag;
 use App\Support\ImagePayload;
 use App\Support\SiteUrls;
 use App\Support\TranslatablePayload;
@@ -58,6 +59,29 @@ class PublicPageResource extends JsonResource
 
             'category' => PublicCategoryResource::make($this->whenLoaded('category')),
 
+            // Only the tags named in this language: one without a slug here
+            // has no listing to link to.
+            'tags' => $this->whenLoaded('tags', fn () => $this->tags
+                ->filter(fn (Tag $tag) => filled($tag->getTranslation('slug', $locale, false)))
+                ->map(fn (Tag $tag) => [
+                    'name' => $tag->getTranslation('name', $locale),
+                    'slug' => $tag->getTranslation('slug', $locale, false),
+                ])
+                ->values()),
+
+            // Who signs it — only someone with a public profile to link to.
+            'byline' => $this->whenLoaded('byline', fn () => $this->byline?->is_public ? [
+                'name' => $this->byline->name,
+                'slug' => $this->byline->slug,
+                'headline' => $this->byline->getTranslation('headline', $locale),
+                'avatar' => ImagePayload::make(
+                    $this->byline->avatar,
+                    $this->byline->relationLoaded('avatarMedia') ? $this->byline->getRelation('avatarMedia') : null,
+                    $this->byline->name,
+                ),
+                'path' => SiteUrls::path('member', $locale, $this->byline->slug),
+            ] : null),
+
             // Lets the frontend emit correct hreflang tags. Only locales that
             // actually have a translation appear.
             'alternates' => SiteUrls::alternates($this->resource, 'page'),