feat(blog): custom hero, OG and blog card images for articles

app/Filament/Forms/Components/ImageCropper.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\Filament\Forms\Components;
+
+use Closure;
+use Filament\Forms\Components\Field;
+
+class ImageCropper extends Field
+{
+    protected string $view = 'filament.forms.components.image-cropper';
+
+    protected string|Closure|null $imageUrl = null;
+
+    protected int|Closure $targetWidth = 1200;
+
+    protected int|Closure $targetHeight = 630;
+
+    protected bool|Closure $hasPendingImage = false;
+
+    /**
+     * The URL of the image the crop selection is made on.
+     */
+    public function imageUrl(string|Closure|null $url): static
+    {
+        $this->imageUrl = $url;
+
+        return $this;
+    }
+
+    /**
+     * The dimensions of the image that will be generated from the crop selection.
+     */
+    public function targetDimensions(int|Closure $width, int|Closure $height): static
+    {
+        $this->targetWidth = $width;
+        $this->targetHeight = $height;
+
+        return $this;
+    }
+
+    /**
+     * Whether the source image has been changed but not saved yet, meaning the
+     * crop selection can't be made until the record is saved.
+     */
+    public function hasPendingImage(bool|Closure $condition): static
+    {
+        $this->hasPendingImage = $condition;
+
+        return $this;
+    }
+
+    public function getImageUrl(): ?string
+    {
+        return $this->evaluate($this->imageUrl);
+    }
+
+    public function getTargetWidth(): int
+    {
+        return $this->evaluate($this->targetWidth);
+    }
+
+    public function getTargetHeight(): int
+    {
+        return $this->evaluate($this->targetHeight);
+    }
+
+    public function getHasPendingImage(): bool
+    {
+        return (bool) $this->evaluate($this->hasPendingImage);
+    }
+}

app/Filament/Resources/ArticleResource.php

@@ -2,23 +2,30 @@
 
 namespace App\Filament\Resources;
 
+use App\Filament\Forms\Components\ImageCropper;
 use App\Filament\Resources\ArticleResource\Actions\PreviewAction;
 use App\Filament\Resources\ArticleResource\Actions\PublishAction;
 use App\Filament\Resources\ArticleResource\Actions\UnpublishAction;
 use App\Filament\Resources\ArticleResource\Pages;
 use App\Models\Article;
+use App\Services\ArticleImageService;
 use Filament\Actions;
 use Filament\Actions\ActionGroup;
+use Filament\Forms\Components\FileUpload;
 use Filament\Forms\Components\MarkdownEditor;
 use Filament\Forms\Components\Textarea;
 use Filament\Forms\Components\TextInput;
 use Filament\Resources\Resource;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Components\Utilities\Get;
 use Filament\Schemas\Components\Utilities\Set;
 use Filament\Schemas\Schema;
 use Filament\Tables\Columns\TextColumn;
 use Filament\Tables\Table;
 use Illuminate\Contracts\Database\Eloquent\Builder;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Str;
+use Illuminate\Validation\Rule;
 
 class ArticleResource extends Resource
 {
@@ -30,10 +37,13 @@ class ArticleResource extends Resource
 
     protected static \BackedEnum|string|null $navigationIcon = 'heroicon-o-newspaper';
 
+    protected static ?string $navigationLabel = 'Blog';
+
+    protected static ?string $breadcrumb = 'Blog';
+
     public static function form(Schema $schema): Schema
     {
         return $schema
-            ->inlineLabel()
             ->columns(1)
             ->schema([
                 TextInput::make('title')
@@ -67,6 +77,46 @@ public static function form(Schema $schema): Schema
                     ->maxLength(400)
                     ->columnSpanFull(),
 
+                Section::make('Hero image')
+                    ->description('Shown at the top of the article and used to create the social sharing (OG) image and the blog card preview. When left empty, an OG image is generated automatically.')
+                    ->columns(1)
+                    ->schema([
+                        FileUpload::make('hero_image')
+                            ->label('Image')
+                            ->image()
+                            ->disk('public')
+                            ->directory('blog/heroes')
+                            ->maxSize(10240)
+                            ->rule(
+                                Rule::dimensions()
+                                    ->minWidth(ArticleImageService::OG_WIDTH)
+                                    ->minHeight(ArticleImageService::OG_HEIGHT)
+                            )
+                            ->live()
+                            ->helperText('At least '.ArticleImageService::OG_WIDTH.'×'.ArticleImageService::OG_HEIGHT.'px — upload the largest version you have; it will be scaled down if needed.'),
+
+                        ImageCropper::make('og_image_crop')
+                            ->label('Social (OG) image crop')
+                            ->targetDimensions(ArticleImageService::OG_WIDTH, ArticleImageService::OG_HEIGHT)
+                            ->imageUrl(fn (?Article $article) => $article?->getHeroImageUrl())
+                            ->hasPendingImage(fn (?Article $article, Get $get): bool => static::heroImageIsPending($article, $get))
+                            ->visible(fn (?Article $article) => filled($article?->hero_image)),
+
+                        ImageCropper::make('card_image_crop')
+                            ->label('Blog card crop')
+                            ->targetDimensions(ArticleImageService::CARD_WIDTH, ArticleImageService::CARD_HEIGHT)
+                            ->imageUrl(fn (?Article $article) => $article?->getHeroImageUrl())
+                            ->hasPendingImage(fn (?Article $article, Get $get): bool => static::heroImageIsPending($article, $get))
+                            ->visible(fn (?Article $article) => filled($article?->hero_image)),
+
+                        ImageCropper::make('header_image_crop')
+                            ->label('Article header crop')
+                            ->targetDimensions(ArticleImageService::HEADER_WIDTH, ArticleImageService::HEADER_HEIGHT)
+                            ->imageUrl(fn (?Article $article) => $article?->getHeroImageUrl())
+                            ->hasPendingImage(fn (?Article $article, Get $get): bool => static::heroImageIsPending($article, $get))
+                            ->visible(fn (?Article $article) => filled($article?->hero_image)),
+                    ]),
+
                 MarkdownEditor::make('content')
                     ->required()
                     ->columnSpanFull(),
@@ -113,6 +163,15 @@ public static function table(Table $table): Table
             ->defaultSort('published_at', 'desc');
     }
 
+    /**
+     * Whether the hero image in the form state differs from the saved one,
+     * meaning crops can only be adjusted after saving.
+     */
+    protected static function heroImageIsPending(?Article $article, Get $get): bool
+    {
+        return ! in_array($article?->hero_image, Arr::wrap($get('hero_image')), true);
+    }
+
     public static function getRelations(): array
     {
         return [

app/Filament/Resources/ArticleResource/Pages/CreateArticle.php

@@ -3,7 +3,7 @@
 namespace App\Filament\Resources\ArticleResource\Pages;
 
 use App\Filament\Resources\ArticleResource;
-use App\Services\OgImageService;
+use App\Services\ArticleImageService;
 use Filament\Resources\Pages\CreateRecord;
 
 class CreateArticle extends CreateRecord
@@ -12,13 +12,7 @@ class CreateArticle extends CreateRecord
 
     protected function afterCreate(): void
     {
-        $service = resolve(OgImageService::class);
-
-        $ogImageUrl = $service->generate($this->record);
-
-        $this->record->update([
-            'og_image' => $ogImageUrl,
-        ]);
+        resolve(ArticleImageService::class)->refreshImages($this->record);
     }
 
     protected function getRedirectUrl(): string

app/Filament/Resources/ArticleResource/Pages/EditArticle.php

@@ -3,7 +3,7 @@
 namespace App\Filament\Resources\ArticleResource\Pages;
 
 use App\Filament\Resources\ArticleResource;
-use App\Services\OgImageService;
+use App\Services\ArticleImageService;
 use Filament\Actions;
 use Filament\Forms\Components\DateTimePicker;
 use Filament\Forms\Components\Radio;
@@ -14,16 +14,25 @@ class EditArticle extends EditRecord
 {
     protected static string $resource = ArticleResource::class;
 
-    protected function afterSave(): void
+    /**
+     * When the hero image is replaced or removed, the stored crop selections
+     * relate to the old image, so reset them to the default.
+     */
+    protected function mutateFormDataBeforeSave(array $data): array
     {
-        $service = resolve(OgImageService::class);
+        if (array_key_exists('hero_image', $data) && $data['hero_image'] !== $this->record->hero_image) {
+            $data['og_image_crop'] = null;
+            $data['card_image_crop'] = null;
+            $data['header_image_crop'] = null;
+        }
 
-        // Always regenerate the OG image on update to ensure it's current
-        $ogImageUrl = $service->generate($this->record);
+        return $data;
+    }
 
-        $this->record->update([
-            'og_image' => $ogImageUrl,
-        ]);
+    protected function afterSave(): void
+    {
+        // Always regenerate the OG and card images on update to ensure they're current
+        resolve(ArticleImageService::class)->refreshImages($this->record);
     }
 
     protected function getHeaderActions(): array

app/Filament/Resources/ArticleResource/Pages/ListArticles.php

@@ -10,6 +10,8 @@ class ListArticles extends ListRecords
 {
     protected static string $resource = ArticleResource::class;
 
+    protected static ?string $title = 'Blog';
+
     protected function getHeaderActions(): array
     {
         return [

app/Models/Article.php

@@ -2,6 +2,7 @@
 
 namespace App\Models;
 
+use App\Services\ArticleImageService;
 use DateTime;
 use Illuminate\Contracts\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Attributes\Scope;
@@ -18,6 +19,12 @@ class Article extends Model
         'title',
         'excerpt',
         'og_image',
+        'hero_image',
+        'card_image',
+        'header_image',
+        'og_image_crop',
+        'card_image_crop',
+        'header_image_crop',
         'content',
         'published_at',
     ];
@@ -27,6 +34,15 @@ public function getRouteKeyName()
         return 'slug';
     }
 
+    public function getHeroImageUrl(): ?string
+    {
+        if (! $this->hero_image) {
+            return null;
+        }
+
+        return asset('storage/'.$this->hero_image);
+    }
+
     /*
     |--------------------------------------------------------------------------
     | Scopes
@@ -98,12 +114,23 @@ protected static function boot()
                 $article->author_id = auth()->id();
             }
         });
+
+        static::updated(function (Article $article): void {
+            resolve(ArticleImageService::class)->pruneStaleImages($article);
+        });
+
+        static::deleting(function (Article $article): void {
+            resolve(ArticleImageService::class)->deleteImages($article);
+        });
     }
 
     protected function casts(): array
     {
         return [
             'published_at' => 'datetime',
+            'og_image_crop' => 'array',
+            'card_image_crop' => 'array',
+            'header_image_crop' => 'array',
         ];
     }
 }