plank/laravel-mediable

What's Changed

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.

Full Changelog: 6.5.0...7.0.0

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.

What's Changed

• Added compatibility with symfony 8.X by @frasmage in #389
• Added support for intervention/image:4.0 by @frasmage in #388
• Dropped support for intervention/image:2.X
• Added ImageManipulation::setOutputOptions(), to support various intervention/image output format settings
• Deprecated ImageManipulation::setOutputQuality(). Use the 'quality' key in setOutputOptions() instead

Full Changelog: 6.4.0...6.5.0

What's Changed

• Added Laravel 13 support
• Removed Laravel 11 support
• Minimum supported PHP version is now 8.3

Full Changelog: 6.3.1...6.4.0

What's Changed

• Don't require CLI to execute migrations by @syssi in #376
• Fix template type definition in MediableCollection by @marvinschroeder in #378

New Contributors

• @syssi made their first contribution in #376
• @marvinschroeder made their first contribution in #378

Full Changelog: 6.3.0...6.3.1

What's Changed

• added support for laravel 12, drop support for laravel 10 by @frasmage in #375

Full Changelog: 6.2.1...6.3.0

What's Changed

• Fix imageManipulation::outputWebpFormat() encoding by @frasmage in #373
• Update 2020_10_12_000000_add_variants_to_media.php by @solomon-ochepa in #372
• adjust variant FK constraint drop by @frasmage in #374

New Contributors

• @solomon-ochepa made their first contribution in #372

Full Changelog: 6.2.0...6.2.1

What's Changed

• Added support for PHP 8.4 by @selfsimilar in #362
• MediaUploader directory now defaults to empty string by @EriBloo in #366
• add support for HEIC image files by @frasmage in #368
• add php 8.4 to test suite by @frasmage in #369

New Contributors

• @selfsimilar made their first contribution in #362
• @EriBloo made their first contribution in #366

Full Changelog: 6.1.3...6.2.0

What's Changed

• Migration Class Refactor and Column Existence Check by @anilkumarthakur60 in #358

Full Changelog: 6.1.2...6.1.3

What's Changed

• Fix publish add_alt_to_media migration by @jason-nabooki in #353

New Contributors

• @jason-nabooki made their first contribution in #353

Full Changelog: 6.1.1...6.1.2

• Fix typo in driver class FQCN

Full Changelog: 6.1.0...6.1.1

• 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