Laravel Attachments Laravel Package

Getting Started

This release is primarily a security hardening of how uploaded file extensions are chosen, plus an internal refactor. Start by reading the package README section on uploads and the published config/attachments.php, especially the new attachments.extra_extensions key. Then run your migrations and confirm the attachments table and the Image / File models are present.

Your first use case should be the normal one: add HasImages and/or HasFiles to an Eloquent model, upload through the package routes/controller, and render the attachment via its url accessor. Immediately after upgrading, upload one file of each type your app relies on (JPEG/PNG/PDF/DOCX, plus any SVG/XML/JSON you legitimately use) and inspect the stored filename. Anything whose detected extension is not on the built-in safe allowlist will now be stored as .bin — that is the key behaviour change to validate before shipping.

Also audit files already on disk: the release explicitly does not rename existing files, so previously uploaded HTML/SVG/XML/JS files keep their old extension and remain potentially dangerous if served from the public disk.

Implementation Patterns

• Standard trait usage. Keep using HasImages / HasFiles on models as before; relations, routes, flash messages and public methods are unchanged in this release.
• Staging then attaching. The lifecycle logic (staging, attach, delete, restore, force delete) is now centralised in AttachmentLifecycle. Day-to-day behaviour is the same: stage an upload, attach it to a model, soft delete to hide it, force delete to remove the physical file.
• Ordering. Use the shared AttachmentController order endpoint as before to persist attachment ordering.
• Extension allowlisting. Treat attachments.extra_extensions as an explicit, reviewed allowlist, not a convenience dumping ground. Add only the types you actually accept and serve safely (for example a specific document format), and document why each entry exists.
• Serving files deliberately. If you need to support SVG, XML, JSON or similar, prefer serving them through a controller with an explicit Content-Type and Content-Disposition: attachment, rather than relying on the public disk to guess the type.
• Custom attachment types. If you subclass Image or File, re-check your class hierarchy: both now extend the new abstract Attachment model. Shared behaviour (soft deletes, url accessor, physical-file removal on force delete) lives there.
• Testing. Add feature tests that upload representative files and assert the stored extension, including at least one file expected to fall back to .bin, plus a test that force-deleting an attachment removes the physical file.

Gotchas and Tips

• The headline breaking behaviour is the extension allowlist. HTML, SVG, XML and JS uploads no longer retain their extension and are stored as .bin. This closes a stored-XSS vector where such files, served from the public disk on your app's domain, could execute in a victim's browser. Do not "fix" this by broadly expanding the allowlist.
• Existing files are not migrated. After upgrading, old uploads keep their original extensions. Audit the public disk for .html, .svg, .xml, .js and similar, and either delete, re-upload, or serve them through a hardened controller.
• extra_extensions is dangerous by design. The config and README warn about html, svg, xml, js, php and similar. Adding them reintroduces the vulnerability unless you also control how the file is served. Treat any addition as a security review item.
• .bin may break legitimate previews. If users expect inline preview of SVG logos or JSON exports, .bin will not render in the browser. Decide whether to serve those through a controller or accept download-only behaviour.
• Extension detection is not MIME validation. The allowlist is based on the upload's detected extension. Keep validating content type and size at the application layer; do not treat the allowlist as a complete upload security policy.
• Refactor risk is low but non-zero. Image and File now extend Attachment, and delete/restore/staging logic moved into AttachmentLifecycle. Public APIs, relations, routes and flash messages are unchanged, but custom subclasses, direct model assumptions, or code that extended the old internals should be re-tested.
• Debugging. If a file unexpectedly lands as .bin, check the detected extension, clear config cache after editing extra_extensions, and confirm the config file was re-published so the new key exists.
• Upgrade checklist. Run the test suite, re-publish/merge config, verify the new key is present, smoke-test uploads for each supported type, and audit existing public-disk files.