jackardios / laravel-medialibrary

2.1.0 2026-10-08 01:44 UTC

Requires

• php: ^8.3
• ext-exif: *
• ext-fileinfo: *
• ext-json: *
• composer/semver: ^3.4
• illuminate/bus: ^12.0|^13.0
• illuminate/conditionable: ^12.0|^13.0
• illuminate/console: ^12.0|^13.0
• illuminate/database: ^12.0|^13.0
• illuminate/http: ^12.0|^13.0
• illuminate/pipeline: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• maennchen/zipstream-php: ^3.1
• spatie/image: ^3.6
• spatie/image-optimizer: ^1.7.3
• spatie/laravel-package-tools: ^1.16.1
• spatie/temporary-directory: ^2.2
• symfony/console: ^7.2|^8.0

Requires (Dev)

• ext-imagick: *
• ext-pdo_sqlite: *
• ext-zip: *
• aws/aws-sdk-php: ^3.293.10
• guzzlehttp/guzzle: ^7.8.1|^8.0
• larastan/larastan: ^3.0
• laravel/pint: ^1.24
• league/flysystem-aws-s3-v3: ^3.22
• mockery/mockery: ^1.6.7
• orchestra/testbench: ^10.0|^11.0
• pestphp/pest: ^3.7|^4.0
• php-ffmpeg/php-ffmpeg: ^1.2
• phpstan/extension-installer: ^1.3.1
• spatie/laravel-ray: ^1.33
• spatie/pdf-to-image: ^2.2|^3.0
• spatie/pest-expectations: ^1.13

Suggests

• ext-curl: Required by the HttpFacadeDownloader to download from urls it checked
• league/flysystem-aws-s3-v3: Required to use AWS S3 file storage
• php-ffmpeg/php-ffmpeg: Required for generating video thumbnails
• spatie/pdf-to-image: Required for generating thumbnails of PDFs and SVGs

Conflicts

• php-ffmpeg/php-ffmpeg: <0.6.1
• spatie/laravel-medialibrary: *

MIT

• Freek Van der Herten
• Jackardios

• media
• cms
• conversion
• images
• laravel
• downloads
• spatie
• laravel-medialibrary

Published on Packagist.org on 2026-10-08 01:44 UTC

README

jackardios/laravel-medialibrary is a fork of spatie/laravel-medialibrary. It follows upstream (2.x is based on spatie 11.23.8) and adds fixes and performance work on top. The API, the Spatie\MediaLibrary namespace and the configuration stay those of the original package, so existing code and the upstream documentation apply. Where the fork behaves differently, the docs directory of this repository says so.

This package can associate all sorts of files with Eloquent models. It provides a simple API to work with:

$newsItem = News::find(1);
$newsItem->addMedia($pathToFile)->toMediaCollection('images');

It can handle your uploads directly:

$newsItem->addMedia($request->file('image'))->toMediaCollection('images');

Want to store some large files on another filesystem? No problem:

$newsItem->addMedia($smallFile)->toMediaCollection('downloads', 'local');
$newsItem->addMedia($bigFile)->toMediaCollection('downloads', 's3');

The storage of the files is handled by Laravel's Filesystem, so you can use any filesystem you like. Additionally, the package can create image manipulations on images and pdfs that have been added in the media library.

Requirements and installation

version	PHP	Laravel
2.x	8.3 – 8.5	12, 13
1.x	8.2+	10, 11

composer require jackardios/laravel-medialibrary:^2.0

The fork uses the same namespace as spatie/laravel-medialibrary and declares a conflict with it; remove that package first. It is an independent package: packages that require spatie/laravel-medialibrary, such as Media Library Pro or the Filament plugin, cannot be installed with it. Setting up the package (publishing the migration and the config, preparing models) works as described in the upstream installation guide.

How the fork differs from spatie/laravel-medialibrary

• Safer url downloads. addMediaFromUrl refuses urls that resolve to private or reserved addresses (localhost, the local network, cloud metadata services), checks every redirect, connects to the address it checked and stops downloading at max_file_size. Internal hosts can be trusted in the config. See using a custom media downloader.
• Safer file names. Besides upstream's extension blocklist, .user.ini and web.config are refused, and the default sanitizer also replaces the characters Windows does not allow and renames reserved device names such as CON. Spatie\MediaLibrary\Support\FileName lets an application check or sanitize a name itself.
• Separate conversions disk done right. Urls, srcsets, regeneration, existence checks, renames, moves, mail attachments and deletion all use the conversions disk.
• Responsive images kept consistent. They are replaced only once a new set has been generated, renamed with the media, and removed exactly.
• media-library:regenerate behaves as upstream's by default and offers the fork's fast paths: --queue-all queues one job per media that downloads the original once for all conversions and responsive images, and --trust-database lets --only-missing read the generated_conversions column instead of the disk.
• Faster url and html building. A media keeps its conversion collection while its urls are built, conversions build their optimizers only to perform, and a srcset builds one url generator instead of one per image.
• Many smaller fixes; see the changelog.

Upgrading

Please see UPGRADING for the steps from 1.x to 2.0.

Changelog

Please see CHANGELOG for what has changed.

Testing

composer test

The S3 tests run against any S3-compatible server when AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION and AWS_BUCKET are set, together with AWS_ENDPOINT, AWS_URL and AWS_USE_PATH_STYLE_ENDPOINT=1 for MinIO. The workflow shows how CI starts one.

Security

If you discover a security issue, please do not open a public issue or pull request for it. Report it privately on GitHub or, when that form is not available, by mail to [e-mail].

Credits

This package is a fork of spatie/laravel-medialibrary by Spatie.

• Freek Van der Herten and all contributors of the original package
• Jackardios, maintainer of the fork

License

The MIT License (MIT). Please see License File for more information.