Media Library
Folder-based file manager for images, videos, documents — used inside the admin and exposed over the API.
Routes
| Route | Method | Purpose |
|---|---|---|
/admin/media | GET | Library UI (folder tree + grid) |
/admin/media/upload | POST | Upload one or more files |
/admin/media/folders | POST | Create folder |
/admin/media/browse | GET | JSON file browser (for entry pickers) |
/admin/media/move | POST | Move file to another folder |
/admin/media/{mediaFile} | GET | File detail page |
/admin/media/{mediaFile} | PUT | Update metadata (name, alt, caption) |
/admin/media/{mediaFile} | DELETE | Delete file (and underlying storage object) |
Storage
Files are written to Laravel's public disk by default. Configure FILESYSTEM_DISK in .env to switch to S3, R2, or any other compatible driver — the model stores only the relative path, so the disk swap is transparent.
Metadata captured on upload
- Original filename and extension
- MIME type (validated against an allowlist)
- Size in bytes
- Image dimensions (width, height) for images
- Hash (used to detect duplicates)
- Folder, alt text, caption (editable later)
- Uploader (
created_by)
Folder tree
media_folders is self-referential — each folder has an optional parent_id. The browse endpoint returns the tree pre-flattened with breadcrumbs for the picker UI.
Image processing
- Thumbnails are generated on upload for grid previews.
- Larger derivatives can be queued via Laravel jobs.
- EXIF orientation is normalized.
Validation rules
file: required, max 50 MB
mime: image/*, video/mp4, application/pdf, etc.
folder_id: optional UUID, must exist
alt_text: optional string, max 255
caption: optional string, max 500Public API accessThe media library is also exposed under
/api/v1/upload/* for authenticated API keys. See API: Media Upload.