Eloquent Mediatheque Laravel Package

Getting Started

Before you install, check the version constraints. This package has essentially no downstream adoption (0 dependents, 2 stars) and its Laravel version support is whatever was current when it was last tagged. Open composer.json in the repo first and confirm the illuminate/* / laravel/framework constraint matches your app. If you're on Laravel 9+ and the constraint says ^5.5|^6.0, stop here and use spatie/laravel-medialibrary instead — you will spend more time patching than building.

If the constraints line up:

1. composer require folklore/eloquent-mediatheque
2. Register the service provider. On Laravel 5.5+ auto-discovery may handle it; if not, add Folklore\Mediatheque\MediathequeServiceProvider::class to config/app.php.
3. Publish assets — php artisan vendor:publish --provider="Folklore\Mediatheque\MediathequeServiceProvider". Publish both config and migrations; the package ships its own media table and you do not want to hand-write it.
4. php artisan migrate
5. Configure a disk. The package defers to Laravel's filesystem layer, so set up config/filesystems.php (local or S3) and point the mediatheque config at it. Run php artisan storage:link if you serve from public.

Where to look first: src/ beats the README. The README for a 2-star Folklore package is typically a stub with one code block. Read the service provider (it tells you what's bound in the container and what's publishable), then the migration (it tells you the schema you're stuck with), then the trait (it tells you the public API surface you'll actually call). Confirm class names there — the naming convention below follows the package's own style but you should verify each one before copying it into your codebase.

First use case: attach an uploaded image to a Post.

use Folklore\Mediatheque\Eloquent\MediathequeTrait; // verify path in src/

class Post extends Model
{
    use MediathequeTrait;
}

Then accept an upload in a controller, hand it to the mediatheque service, and associate the resulting media record with the post. Render it back through the relation rather than by reconstructing paths by hand.

Implementation Patterns

Treat the mediatheque as your write path, the relation as your read path. Uploads go through the package's service/facade (which handles disk writes, hashing, and creating the media row); reads come back through the polymorphic relation on the model. Do not mix the two — writing a Storage::put() yourself and then inserting into the media table manually will leave you with rows that don't match what the service expects.

Wrap upload + attach in a transaction. The database insert and the disk write are two separate systems. If the attach fails after the file lands on disk you get orphans; if the disk write fails after the insert you get dead rows. A DB::transaction() around the controller logic plus a queued cleanup job for orphans is the pragmatic pattern.

Use form requests for validation, not the package. Media packages in this generation don't validate MIME types or dimensions for you. Do mimes:jpg,png,webp, max:5120, and dimensions: rules in a StorePostRequest before anything touches the mediatheque.

Eager load the relation on index pages. Whatever the trait names the relation, list endpoints will N+1 without ->with('medias') (or equivalent). If you're returning JSON, wrap it in an API Resource that emits url, thumb_url, mime, size — never the raw model, which will leak storage paths.

Collections/roles, if supported. Many media packages let you tag an attachment with a role (cover, gallery, attachment). If this one does, prefer that over adding five separate relations to your model. If it doesn't, you'll be encoding roles in a column yourself — check the migration for a name/collection/group column before you invent one.

Queue the expensive work. Thumbnail generation and image conversion should not happen in the request cycle for anything above a few hundred KB. If the package does synchronous conversions, either disable them in config or move the whole store call into a job.

Testing: use Storage::fake('public') and UploadedFile::fake()->image('cover.jpg') so tests never touch the real disk. This is the single highest-value thing you can do with a low-adoption package — your test suite becomes the regression net the maintainer never wrote.

Gotchas and Tips

Abandonment is the headline risk. Zero dependents means zero external bug reports, zero community answers, and nobody has run this against your exact Laravel/PHP combination. Budget for reading and possibly patching the source. If it's already broken on your version, the correct answer is a fork or a different package, not a workaround.

Polymorphic column types. Older migrations often use unsignedInteger for mediable_id instead of unsignedBigInteger. If your models use big integer keys, attachments on high-ID records will silently fail or truncate. Inspect the migration before running it, and patch it if needed — cheaper now than after production rows exist.

Deleting the model doesn't delete the file. Almost never does in packages of this vintage. Add a deleting model event that removes the media rows, and either a deleted hook or a scheduled php artisan mediatheque:clean (if such a command exists) to sweep the disk. Otherwise your storage bucket grows forever.

config:cache will bite you. Any closure or env() call inside the package config file breaks under php artisan config:cache. Grep the config for env( and replace with literal values before you deploy with cached config.

URL generation depends on APP_URL. If images render as http://localhost/... in production, it's the app URL, not the package. Also confirm the disk's url key is set in config/filesystems.php for S3 and that the bucket policy allows public reads (or generate temporary URLs instead).

Extension points to know: custom media model (usually swappable via config — lets you add accessors for thumb_url), custom disk per collection, and image driver selection if it supports Intervention Image. Prefer configuring these over subclassing the service.

Debugging: php artisan tinker and inspect the media table directly after an upload — confirm the row exists, the path/filename matches what's on disk (Storage::disk('public')->exists($path)), and the polymorphic type matches your morph map. Nine out of ten "images don't show" reports are a path/disk mismatch, not a package bug.