Browse and clean up the media library through the API

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

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

@@ -7,19 +7,22 @@ namespace App\Http\Controllers\Api\V1;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\Api\V1\MediaRequest;
 use App\Http\Resources\MediaResource;
+use App\Jobs\ProcessMedia;
 use App\Models\Media;
 use App\Services\Media\RemoteImage;
 use enshrined\svgSanitize\Sanitizer;
 use finfo;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
 use Illuminate\Validation\ValidationException;
 
 /**
- * POST /api/v1/media
+ * The media library: every image on the media disk, and uploading new ones.
  *
- * Stores an image and answers with the path a record points at — what the
+ * `store` stores an image and answers with the path a record points at — what the
  * panel's upload field does on a form, without the form. It exists for the MCP
  * server, which otherwise could create a page but never give it a picture.
  *
@@ -44,6 +47,75 @@ class MediaController extends Controller
         'image/svg+xml' => 'svg',
     ];
 
+    /**
+     * Filters: for (the kind of record it was uploaded for), mime, search
+     * (path), pending, failed, orphans (what `content:prune --media` would
+     * take away).
+     */
+    public function index(Request $request): AnonymousResourceCollection
+    {
+        $this->authorize('viewAny', Media::class);
+
+        // Worked out once for the page rather than once per file: it reads
+        // every record that can point at an image.
+        $referenced = array_flip(Media::referencedPaths());
+
+        $directory = config('media.upload.for.'.$request->string('for'));
+
+        $media = Media::query()
+            ->when(is_string($directory), fn ($q) => $q->where('path', 'like', $directory.'/%'))
+            ->when($request->filled('mime'), fn ($q) => $q->where('mime', $request->string('mime')))
+            ->when($request->filled('search'), fn ($q) => $q->where('path', 'like', '%'.$request->string('search').'%'))
+            ->when($request->boolean('pending'), fn ($q) => $q->pending())
+            ->when($request->boolean('failed'), fn ($q) => $q->whereNotNull('error'))
+            ->when($request->boolean('orphans'), fn ($q) => $q->whereNotIn('path', array_keys($referenced)))
+            ->latest('id')
+            ->paginate(perPage: min($request->integer('per_page', 25), 100))
+            ->withQueryString();
+
+        $media->getCollection()->each(fn (Media $item) => $item->setAttribute('referenced', isset($referenced[$item->path])));
+
+        return MediaResource::collection($media);
+    }
+
+    public function show(Media $media): MediaResource
+    {
+        $this->authorize('view', $media);
+
+        return MediaResource::make($media->setAttribute('referenced', $media->isReferenced()));
+    }
+
+    /**
+     * Only a file nothing points at: deleting one in use would put a broken
+     * image on the public site. Its derived versions go with it.
+     */
+    public function destroy(Media $media): JsonResponse
+    {
+        // The permission first, so whether a file is in use is only told to
+        // someone who could have deleted it.
+        $this->authorize('media.delete');
+
+        abort_if($media->isReferenced(), 409, __('rules.media.in_use'));
+
+        $media->deleteDerived();
+        Storage::disk($media->disk)->delete($media->path);
+        $media->delete();
+
+        return response()->json(status: 204);
+    }
+
+    /**
+     * Derive the smaller versions and the placeholder again, on the queue.
+     */
+    public function reprocess(Media $media): JsonResponse
+    {
+        $this->authorize('view', $media);
+
+        ProcessMedia::dispatch($media);
+
+        return MediaResource::make($media)->response()->setStatusCode(202);
+    }
+
     public function store(MediaRequest $request, RemoteImage $remote): JsonResponse
     {
         $for = (string) $request->input('for', 'pages');

app/Http/Resources/MediaResource.php

@@ -19,6 +19,7 @@ class MediaResource extends JsonResource
     public function toArray(Request $request): array
     {
         return [
+            'id' => $this->id,
             // What a record stores — `featured_image` on a page — and so the one
             // field a caller has to keep.
             'path' => $this->path,
@@ -30,6 +31,13 @@ class MediaResource extends JsonResource
             // False until the queue has derived the smaller versions and the
             // placeholder. The image serves either way.
             'processed' => $this->isProcessed(),
+            'error' => $this->error,
+            // Only in the library, where it decides whether a file may go.
+            'referenced' => $this->when(
+                array_key_exists('referenced', $this->resource->getAttributes()),
+                fn () => (bool) $this->resource->getAttribute('referenced'),
+            ),
+            'created_at' => $this->created_at?->toIso8601String(),
         ];
     }
 }