Download the PHP package ozankurt/laravel-modules-media-library without Composer

laravel-modules-media-library

WordPress-style media bucket for Laravel SaaS: tenant-aware folders, polymorphic attachments, focal-point conversions, replace-with-stable-id versioning, share links, folder ACL.

Wraps spatie/laravel-medialibrary as the storage engine.

Requirements

• PHP ^8.4
• Laravel ^13.0
• ozankurt/laravel-modules-core v2.x
• spatie/laravel-medialibrary v11.x

Installation

What it provides

• Catalog — MediaLibraryFolder (nested tree), MediaLibraryItem (WordPress-style row), MediaLibraryTag, polymorphic attachments to consumer models, saved searches.
• Storage — Wraps spatie/laravel-medialibrary via a per-item host model. Versioning with stable item ids. Ad-hoc focal-point-aware variant generation. Presigned direct-to-S3 + server-proxy upload flows.
• Sharing — TTL share links with abilities (view/download) + access log + invitee email. Item shares stream the file; folder shares return a bounded JSON listing of the folder's items. The public share route is rate-limited and tokens are matched by hash, not plaintext.
• Access — Folder ACL with the same SubjectResolver pattern as ResourceLibrary.
• Search — Eloquent scopes (byOwner/byFolder/byTag/byMimeType/byDateRange/search) + optional Scout adapter contract.
• Two-stage metadata extraction — dimensions, blurhash, and colour palette are extracted synchronously in-request on upload (immediate placeholder + colour data). A second, async stage (the ExtractMediaMetadata job) then runs the configured extractor pipeline over the stored file: real EXIF/GPS + dimensions via exif_read_data()/getimagesize(), plus pluggable OCR / AI-tagging / search-indexing steps. See Extraction pipeline. MediaSubjectResolver is pluggable via config.
• GDPR helpers — media-library:purge-subject {type} {id} hard-deletes (optionally anonymises) all data owned by a subject; media-library:prune-access-log enforces access-log retention (access_log.prune_after_days).
• Optional Laravel Notifications — Mail + Database channels with publishable Blade templates.

Extraction pipeline

After a successful upload or replace, the coordinators dispatch the ExtractMediaMetadata job (implements ShouldQueue). It resolves the item's stored media and runs the ordered steps in media-library.extractors.pipeline, each mapped to a contract binding in media-library.contracts:

DefaultExifExtractor uses PHP's getimagesize() for dimensions and exif_read_data() for full EXIF including GPS. The EXIF call is guarded by function_exists('exif_read_data') / extension_loaded('exif'): if ext-exif is unavailable it is skipped gracefully and only dimensions are returned. Each step also fires a domain event (ExifExtracted, TextExtracted, AiTagsAssigned) the consumer can listen for.

Extension points. The package ships no OCR / AI / search engine — those steps stay unbound (and are skipped) until you supply one. Point the config at your implementation:

Safe no-op reference stubs (NullOcrExtractor, NullAiTagger, NullScoutAdapter) ship with the package if you want an inert binding.

Dispatch mode. media-library.extractors.dispatch (env MEDIA_LIBRARY_EXTRACTORS_DISPATCH) is queued by default; set it to sync to run the pipeline inline in the request. extractors.connection / extractors.queue route the queued job. media-library:reextract {item} re-runs both stages for a single item on demand.

Note: this reverses the round-2 audit removal of the extractors.async config, which was dropped because nothing dispatched it. The pipeline is now wired for real via the ExtractMediaMetadata job.

GDPR. Extracted EXIF/GPS lives in the item's exif column, so media-library:purge-subject {type} {id} removes it together with the item — no orphaned location PII survives a subject purge.

Share links are bearer credentials

Share links are bearer credentials by default: anyone who holds a valid, unexpired, un-revoked token can view or download the target (subject to the link's abilities). The invitee_email column records who a link was sent to for auditing and UI, but it does not restrict access on its own - the token is the only thing checked.

If you need per-invitee enforcement, set media-library.shares.enforce_invitee to true (or MEDIA_LIBRARY_ENFORCE_INVITEE=true). With it enabled, a link that has an invitee_email set will only resolve for a requester who is authenticated as that email address (compared case-insensitively). Unauthenticated or mismatched requesters receive a 403. Links whose invitee_email is null stay bearer regardless of the flag. The default is false to preserve the non-breaking bearer behavior.

API

The package ships an out-of-the-box JSON REST API built on the Core API kit. It is safe by default: in headless mode (the default) nothing is registered — no routes, no rate limiter. Opt in per environment:

or in config/media-library.php:

Every route is throttled by the named media-library-api limiter (keyed by user id, or client IP for guests). Read routes get the base middleware; write routes additionally get auth_middleware.

Endpoints

All paths are under the configured prefix (default api/media). Route names are prefixed media-library.api. (e.g. media-library.api.folders.index).

Responses use the Core envelope: { "data": … } for success (with meta.pagination on list endpoints), { "message": …, "errors": … } for errors. Lists accept ?per_page= (clamped to 100), ?page=, ?sort= and ?filter[field]= (allow-listed per resource).

ACL enforcement

Reads are ACL-scoped: every controller authorises the folder/item Policy, so a record behind an ACL the caller lacks is never returned (an item in a folder the subject cannot access is neither shown nor listed). Writes require the auth middleware and pass the same folder-ACL Policies per method — authentication alone is never sufficient. Folder ACL is the model's own FolderPermission + visibility layer (view / download / manage capabilities, cascading down the tree).

Uploads go through the coordinators

items (upload) and items/{item}/replace are thin adapters over the existing UploadCoordinator / ReplaceCoordinator — the API never writes media directly. That means every API upload runs the same content-mime + size validation, filename sanitisation, spatie storage, synchronous placeholder extraction (blurhash/palette) and the queued ExtractMediaMetadata pipeline (EXIF/GPS, OCR, AI tags, search index) that the facade path runs, plus the same GDPR bookkeeping. The default server-proxy flow POSTs the file to items.

For a presigned direct-to-storage flow (skip the proxy, upload straight to S3), call POST uploads to get a presigned PUT URL + headers + object key, PUT the bytes to it from the client, then POST uploads/{uploadId}/complete — the finalize step re-validates the real object and runs the identical coordinator path. initiate/complete/cancel are scoped to the owner that created the pending upload.

Filament admin

The package ships admin resources for Filament v3, v4, and v5. Register the version-dispatching plugin on your panel — the correct resource set is resolved from the installed Filament major automatically:

This registers four resources:

• MediaLibraryItemResource — metadata editing (per-locale title / alt text / caption / description, focal-point inputs, folder + tags) with a read-only file preview. Items are uploaded via the MediaLibrary facade, so the admin form edits metadata rather than re-uploading; the file URL is shown for reference. Table: title, MIME type, human-readable size, folder, view/download counts; filterable by MIME type and folder.
• MediaLibraryFolderResource — per-locale name/description, parent folder, visibility, position. Table: name, path, visibility badge, item count.
• MediaLibraryTagResource — per-locale name + colour.
• ShareLinkResource — read-only list of share links (token, target, abilities, expiry, access count) with a row-level Revoke action. Links are created through the facade.

filament/filament is a dev dependency only; the resources load lazily for whichever major the consuming app installs.

Testing

CI runs the same checks on every push and pull request (.github/workflows/tests.yml), against PHP 8.4 / Laravel 13. Static analysis is held at PHPStan level 8; the suite runs on Pest 5.

License

MIT © Ozan Kurt