Laravel Mediable Laravel Package

This is a security release, upgrading is strongly recommended

• Added mediable.allowed_remote_hosts configuration which allows restricting remote URL source adapters to a whitelist. Wildcard subdomains may be specified with *.example.com syntax. By default, all hosts are allowed.
• If no mediable.allowed_remote_hosts allow list is provided, the RemoteUrlAdapter will reject private IP addresses and localhost by default, to prevent Server-Side Request Forgery (SSRF) attacks. [CVE-2026-49969]
• Added mediable.allowed_remote_schemes configuration which allows restricting remote URL source adapters to a whitelist of allowed URL schemes (e.g. http, https, ftp, etc.). By default, only https is allowed. When modifying this configuration, it may also be necessary to modify the source_adapters pattern matching.
• Directory validation will now strip . characters from path segments. This prevents attackers from using directory traversal patterns like ../ as well as preventing potential issues with certain filesystems where . characters in directory names may cause unexpected behaviour. [CVE-2026-49970]
• Added mediable.file_sanitizers configuration which allows specifying custom sanitizers for rewriting file contents to strip out security risks before they are uploaded. A sanitizer must implements the Plank\Mediable\Sanitizers\SanitizerInterface interface.
• Added SvgSanitizer which will strip executable javascript and other untrusted content from image/svg+xml files, which can result in stored XSS if rendered directly to a webpage. By default, this sanitizer is applied to all uploaded SVG files. It can be disabled by removing it from the mediable.sanitizers config array. [CVE-2026-49971]
• Added mediable.forbidden_file_extensions configuration and MediaUploader::setForbiddenExtensions() which allows specifying a blacklist of file extensions that are forbidden to be uploaded. Any file extension which is considered executable by your Apache or Nginx configuration should be included in this list. A number of common executable file extensions are included in this list by default to prevent remote code execution exploits.
• In addition, forbidden file extensions are now sanitized if they are nested within destination filenames (e.g. script.php.jpg becomes script-php.jpg). This prevents remote code execution from double extension bypass due to common Apache and Nginx misconfigurations
• Added mediable.forbidden_mime_types configuration and MediaUploader::setForbiddenMimeTypes() which allows specifying a blacklist of MIME types that are forbidden to be uploaded.
• MediaUploader::ON_DUPLICATE_* constants have been moved to an Plank\Mediable\Enum\OnDuplicateBehaviour enum.
• Added MediaUploaderConfiguration class. Most MediaUploader instance properties are moved to this class. The MediaUploader class now accepts this as a constructor argument instead of an array of configs.
• MediaUploader::beforeSave() now accepts a \Closure instead of a callable for better static analysis and type safety.

• Attempt to automatically select an intervention/image driver based on the available extensions.
• Fix an error in package discovery if attempting to install both plank/laravel-mediable and intervention/image-laravel at the same time

• move ImageManipulator singleton to lazy instantiation

• Fix alt migration default value for the mysql dialect. Default value assigned from the Media model

• fix service provider database migration bindings by @frasmage in #349

• Added intervention/image-laravel package to the composer suggests list
• Updated documentation with configuration instructions for intervention/image

• Fix readthedocs documentation build configuration

Compatibility

• Dropped support for PHP 7.4 and 8.0
• Dropped Support for Laravel 8 and 9
• Added Support for PHP 8.3
• Added Support for Laravel 11
• Added support for intervention/image 3.0
• Modernized the database migration files to use more recent Laravel conventions.

Mediable

• Added MediableInterface

MediaUploader

• Added support for recording alt attributes on Media (database migration required). MediaUploader now exposes a withAltAttribute() method to set the alt attribute on the generated media record.
• Added MediaUploader::applyImageManipulation() to make changes to the original uploaded image during the upload process.
• Added MediaUploader::validateHash() to ensure that the hash of the uploaded file matches a particular value during upload. Supports any hashing algorithm supported by PHP's hash() function.
• By default, the MediaUploader will always use the MIME type inferred from the file contents, regardless of the source. Added the MediaUploader::preferClientMimeType() to indicate that the MIME type provided by the source should be used instead, if provided. The default behaviour can be configured with the 'prefer_client_mime_type' key in the config/mediable.php file.
• The MediaUploader::useHashForFilename() method now accepts an optional parameter to specify which hashing algorithm to use to generate the filename. Supports any hashing algorithm supported by PHP's hash() function.
• MediaUploader will now use the visibility defined on the filesystem disk config if the makePublic()/makePrivate() methods are not called, instead of assuming public visibility.
• MediaUploader now supports data URL strings as an input source, e.g. data:image/jpeg;base64,....
• If a filename is not provided to the MediaUploader, and none can be inferred from the source, the uploader will throw an exception.
• If the file extension is not available from the source, the uploader will now consistently infer it from the MIME type. Previously this behaviour was inconsistent across different source adapters.

SourceAdapters

All SourceAdapter classes have been significantly refactored.

• All sourceAdapters will now never load the entire file contents into memory (unless it is already in memory) to determine metadata about the file, in order to avoid memory exhaustion when dealing with large files. If reading the file is necessary, most adapters will attempt use a single streamed scan of the file to load all metadata at once, to speed up to the precess. Remote files will be cached to temp:// to avoid repeated HTTP requests.
• Removed getStreamResource() method. The method has been replaced with the getStream(): StreamInterface, which returns a PSR-7 stream implementation instead.
• Added hash(string $algo): string method which is expected to return the hash of the file contents using the specified algorithm.
• The return type of the filename() and extension() method is now nullable. If the adapter cannot determine the value from the information available, it should return null.
• Removed the getContents() method. The getStream()->getContents() method may be used instead.
• Removed the getSource() method. No replacement.
• Removed the path() method. No replacement.
• Removed the valid() method. SourceAdapters should now throw an exception with a more helpful message from the constructor if the source is not valid.

ImageManipulation

• Added support for optimizing manipulated images, using the spatie/image-optimizer package, which supports a variety of image optimization tools for different image formats (jpegoptim, pngquant, optipng, gifsicle, etc.)
• Default image optimization behaviour can configured in the config/mediable.php file to specify the optimization tools to use and their arguments.
• Added ImageManipulation::noOptimization() and ImageManipulation::optimize(?array $optimizers = null) methods to allow overriding the defaults set in the config file.
• The ImageManipulation::useHashForFilename() method now accepts an optional parameter to specify which hashing algorithm to use to generate the filename. Supports any hashing algorithm supported by PHP's hash() function.
• The ImageManipulation::usingHashForFilename() method has been renamed to ImageManipulation::isUsingHashForFilename() to avoid confusion with the useHashForFilename() method.

Media

• Added alt attribute to the Media model.
• The Media class now exposes a dynamic url attribute which will generate a URL for the file (equivalent to the getUrl() method).

Other

• Improved MediableCollection annotions to support generic types.
• Added missing type declarations to most property and method signatures.
• Removed the \Plank\Mediable\Stream class in favor of the guzzlehttp/psr7 implementation. This removes the direct dependency on the psr/http-message library.
• \Plank\Mediable\HandlesMediaUploadExceptions::transformMediaUploadException() parameter and return type changed from \Exception to \Throwable.
• Added PHPStan static analysis to the test suite.

• Filename and pathname sanitization will use the app locale when transliterating UTF-8 characters to ascii.
• Restored original behaviour of treating unrecognized mime types as application/octet-stream (changed in recent version of Flysystem)

• Fixed S3 temporary URL generation for Laravel 9+ / Flysystem 3+

• Added support for Laravel 9
• Dropped support for PHP 7.3
• Dropped support for Laravel 6.x and 7.x
• Fixed S3 temporary URL generation not respecting disk root configuration.

• Support specifying file visibility on variant creation

• Fix aggregate type matching not properly handling case mismatches of mime types and/or extensions
• Handle Guzzle stream_for()` deprecation

• Allow passing filesystem options via uploader and mover

• Fixed Facade PHPDOC typehints

• Added MediaUploader::onDuplicateReplaceWithVariants() which behaves similar to onDuplicateReplace() but will also delete any variants of the replaced Media record.
• Fixed onDuplicateUpdate() failing if file exists but without a matching model.

• Fixed MediaUploader Facade returning the same instance

• Resolve bugs with PHP 8.0

• ImageManipulator now uses $media->contents() instead of $media->stream(), as Intervention Image loads the whole file into memory anyways, and the former seems to have fewer hiccups for various cloud filesystems.

• Fixed serialization of CreateImageVariants job.

• Fixed docblock of attachMedia() and SyncMedia() (Thanks @hailwood!)

• Fixed additional bugs with the MediableCollection::delete() method
• Optimized the execution speed of MediableCollection::delete()

• fixed notices generated from collection offset access in MediableCollection::delete()

• Added support for creating image variants using the intervention/image library. Variants can be created synchronously in the current process or asychronously as queued jobs. Media records keep track of variants created from them.
• Fixed Laravel 8+ migration squashing. Database migrations are now loaded from within the package instead of copied to the application's database/migration directory. See UPGRADING.md for steps to avoid conflicts.
• Directory and filename validation now only allows URL and filesystem safe ASCII characters (alphanumeric plus ., -, _, and / for directories). Will automatically attempt to transliterate UTF-8 accented characters and ligatures into their ASCII equivalent, all other characters will be converted to hyphens.
• Added Media::stream() method to easily retrieve a PSR-7 compatible Stream.
• Added support for generating temporary URLs for files hosted on Amazon S3 buckets.

• Fixed a handful of bugs related to using a custom table name when using a custom media class

• Fixed Morph relation when subclassing Media (Thanks @GeoSot!)

• Added support for Laravel 8.0
• Dropping support for Laravel versions < 6.0
• Dropping support for PHP versions 7.2

• Fix composer version constraint of league/flysystem to allow minor version bumps
• Removed redundant index from the Media table database migration

• Media::moveToDisk() and Media::copyToDisk() now correctly transfer file visibility to the new disk.

• Added Media::moveToDisk() and Media::copyToDisk() methods.

• The Media::$size property is now cast as int, fixing a TypeError. (Thanks @boumanb!)
• Fixed RemoteUrlAdapter, StreamAdapter, and StreamResourceAdapter potentially returning an incorrect filename and/or extension if the query params of the URL contains certain characters.

• Fix bug with package auto-discovery with PHP 7.4
• Fix issue caused by a bug with doctrine/inflector 1.4.0

• Replaced usage of the getClientSize() method deprecated in Symphony 4.1 with getSize()

• Added support for Laravel 7.0

• Fixed the timing of the beforeSave callback. Now occurs before onDuplicate validation occurs. This allows the callback to be used to determine where to place the file
• The beforeSave callback is now called triggered by the MediaUploader::replace() and MediaUploader::import() methods as well

• Added support for the new Symfony MimeTypes class in favor of the deprecated ExtensionGuesser (Thanks @crishoj!)

• changed UrlGenerators to use the underlying filesystemAdapter's url() method
• UrlGenerators no longer throw MediaUrlException when the file does not have public visibility. This removes the need to read IO for files local disks or to make HTTP calls for files on s3 disks.
• Removed LocalUrlGenerator::getPublicPath()
• No longer reading the 'prefix' config of local disks. Value should be included in the 'url' config instead.

• Fixed public visibility not being respected when generating URLs for local files that are not in the webroot.

• Updated minimum support requirements to PHP 7.2 and Laravel 5.6+.
• Added PHP 7 parameter and return type hints across the board
• Added a new method getStreamResource to SourceAdapterInterface, uploader will now attempt to use a stream to reduce memory usage.
• Added delete() method to MediableCollection for mass deleting media records and files.
• Added support for file visibility on a file-by-file basis.
• Cleaned up test suite.
• fixed a number of docblocks

• The name of the Mediables pivot table is now configurable (Thanks @nadinengland!)

• Fix windows paths pattern (Thanks @aalyusuf!)

• Add methods to facade for IDE autocompletion (Thanks @simonschaufi!)

• Added update on duplicate behaviour to MediaUploader (Thanks @pet1330!)
• Fixed remote URL data source raising an error when headers cannot be read (Thanks @sebdesign!)

• Return correct types in source adapter methods (Thanks @sebdesign!)
• Add docblocks for Media properties and query scopes (Thanks @sebdesign!)

• Fixed docblocks (Thanks @sebdesign!)

• Fixed tags with numeric values

• Added MediaUploader::verifyFile() to apply validation to a source without uploading (Thanks @JulesPrimo)
• Added MediaUploader::beforeSave() to allow editing custom fields on Media records before they are saved (Thanks @JulesPrimo)

• Fix URL generation for local disks using symbolic links in different Laravel versions (Thanks @sebdesign !)

• MediaUploader::onDuplicateIncrement() behaviour adjusted to use hyphens instead of parenthesis (Thanks @ryankilf!)

• Added Media::copyTo() method (Thanks @johannesschobel!)

• Added Mediable::lastMedia() convenience method (Thanks @pet1330!)

• Added Laravel 5.5 package autodiscovery
• Fixed bugs due to method renamed in Laravel 5.5

• Added missing use statements.

• Fixed composer notation use.

• Added fallback extension guesser to various SourceAdapters for cases where file path does not include extension (e.g. tmp files).

• Fixed allowed extension checking failing due to case mismatch

• Restored Laravel 5.2 compatibility
• S3UrlGenerator now generates the url directly with S3 client, instead of with the FilesystemAdapter::url() method, which was only added in Laravel 5.2.15
• Added fallback for wherePivotIn() used in eager loading, which was only added in Laravel 5.3

• Fixed issues cause by Laravel 5.4 backwards-compatibility breaks
• Increased laravel minumum version to 5.3, which is the minimum that works with the current implementation. Will attempt to restore support for older versions in an upcoming release.

• The onDuplicateDelete action of the MediaUploader now manually deletes the Media record and the file on disk, instead of depending on the record existing to clean its own file.

• Added support for raw content strings to MediaUploader (Thanks @sebdesign)
• Added support for stream resources to MediaUploader (Thanks @sebdesign)
• Added support for PSR-7 StreamInterface objects to MediaUploader (Thanks @sebdesign)
• All SourceAdapters now properly adhere to the described interface.
• Refactored test suite for speed.

• Separated MediaUploadException into a number of subclasses for more granular exception handling (Thanks @sebdesign!).
• Added HandlesMediaUploadExceptions trait for converting MediaUploadExceptions into HttpException with appropriate error codes (Thanks @sebdesign).

• Fixed SQL escaping issue in Mediable::getOrderValueForTags.

• Fixed Media::scopeForPathOnDisk not working when path does not contain a directory (Thanks @geidelguerra!).

• Fixed typo in MediaUploader's OnDuplicateError behaviour (Thanks @geidelguerra!).

• Added handling for symlinked local disks.
• fixed minor issue where variable could be undefined.

• Added means of removing order by from media relation query.
• Fixed multiple media passed to attachMedia() or syncMedia() receiving the same order value.
• Fixed issue with ONLY_FULL_GROUP_BY (MySQL 5.6.5+).
• Reworked attachMedia() to optimize the number of executed queries.

• Mediable models now remember the order in which Media is attached to each tag.
• Renamed a few MediaUploader methods.
• Facilitated setting MediaUploader on-duplicate behaviour. Thanks @jdhmtl.
• MediaUploader can now generate filenames using hash of file contents (Thanks @geidelguerra!).
• Added import() and update() methods to MediaUploader.

• Published migration file now uses dynamic timestamp (Thanks @borisdamevin!).

• Added behaviour for detaching mediable relationships when Media or Mediable models are deleted or soft deleted.

• Fixed Mediable relationship not connecting to custom Media subclass defined in config.

• Added match-all case to media eager load helpers.
• Mediable::getTagsForMedia() now properly rehydrates media if necessary.
• Mediable::load() now looks for media that is either the $relationship key or value.

• Added MediaCollection class.
• Added media eager loading helpers to query builder, Mediable, and MediaCollection.

• Added object typehints to all appropriate functions and closures.