Weave Code
Laravel Stapler Laravel Package
codesleeve/laravel-stapler
Laravel Stapler is an easy file-attachment package for Laravel that handles uploads, storage, and image processing with a simple configuration. It supports local and S3 storage, automatic resizing and thumbnails, and clean model integration.
Stapler-based file upload package for the Laravel framework.
Frequently asked questions about Laravel Stapler
- Does codesleeve/laravel-stapler support Laravel 9, 10, or 11?
- No. The package targets Laravel 4.2 through 5.x-era Illuminate components and PHP 5.x/7.0-era syntax, so Composer will not resolve it on Laravel 9+ or PHP 8.1+ without a fork and patch pass. Even after widening constraints, S3 SigV4 and Flysystem 3 semantics differ enough to require code changes. Treat modern-stack adoption as owning a fork, not installing a package.
- How do I install codesleeve/laravel-stapler in a Laravel app?
- On a supported legacy Laravel 4/5 app, install with composer require codesleeve/laravel-stapler, register the service provider and Stapler alias if package discovery is not available, and publish or run the package migrations for the attachments table. Then add hasAttachedFile() to the model and configure the $stapler array. On current Laravel the install step will fail at dependency resolution, so a fork with updated constraints is required first.
- How do I add an avatar or thumbnail attachment to an Eloquent model with Laravel Stapler?
- Declare the attachment in the model with hasAttachedFile('avatar', ['styles' => ['thumb' => '100x100#', 'medium' => '300x300']]) and define storage, URL, and default options in the model's $stapler array. Stapler uses Imagine filters for resizing and cropping, so style strings like 100x100# produce cropped thumbnails. Save the model with the uploaded file assigned to the attachment attribute and the package handles storage and style generation.
- Does Laravel Stapler support Amazon S3 and private buckets?
- It supports S3 through a legacy AWS SDK v2 client and Flysystem 1.x adapter, configured as the storage driver in the model's $stapler options. That is not equivalent to modern S3 support: SigV4 signing, endpoint behavior, private bucket policies, and signed URLs generally require code changes or a fork. If your architecture depends on direct-to-S3 uploads or CDN-side transforms, evaluate a current media package instead.
- What happens to uploaded files when an Eloquent model is deleted in Laravel Stapler?
- The package is designed to clean up attached files when the model is deleted, removing stored objects and attachment records rather than leaving orphans. You should still verify cleanup for every configured style and for S3, because storage adapter behavior and failed deletions can leave files behind. A periodic orphan sweep is prudent in any Stapler-backed legacy app.
- Can Laravel Stapler handle multiple images, galleries, or polymorphic attachments?
- It can declare multiple named attachments on a model and its attachment table is polymorphic, but the Paperclip-style pattern is still one file per attachment attribute. It does not give you a first-class gallery, ordering, per-file metadata, versioning, or a media domain object. If those are on the 12-month roadmap, use a media library package instead of stretching Stapler.
- Is codesleeve/laravel-stapler still maintained and safe for production?
- No active maintenance is evident: there are no recent releases, no security advisory feed, and no clear maintainer response path. Upload handling, MIME and content-type validation, filename interpolation, SVG or decompression-bomb handling, and image decoding become your responsibility. It is only defensible in a legacy app where a named engineer owns the fork and the security review.
- How do I validate uploads and prevent path traversal with Laravel Stapler?
- Stapler provides file validation hooks, but it handles path traversal and filename safety by convention rather than enforced policy, so you must sanitize interpolation strings and validate extension, MIME type, and file size before saving. Reject SVG or process it through a sanitizer, cap image dimensions, and keep public-disk exposure intentional. Treat the package as a storage mechanism, not a security boundary.
- What are the best alternatives to Laravel Stapler for file and image uploads?
- For current Laravel, spatie/laravel-medialibrary is the usual replacement for media collections, conversions, and S3; intervention/image handles processing and Laravel's filesystem handles storage. If you only need simple uploads, a small custom service with form requests and queued conversions is often cleaner. Choose based on whether media is a column on a model or a first-class domain object.
- Why does composer require codesleeve/laravel-stapler fail on a new Laravel project?
- Composer fails because the package pins old Illuminate component versions and PHP-era syntax, and it pulls codesleeve/stapler plus legacy AWS SDK v2 and Flysystem 1.x dependencies. Those constraints conflict with Laravel 9+ and PHP 8.1+. A one-hour spike of composer require, one upload, one style read-back, and delete usually confirms the incompatibility before you invest further.
Weaver
How can I help you explore Laravel packages today?