Statamic Quote Laravel Package

Getting Started

5.3.0 adds Statamic 6 compatibility (#19). That is the headline: if you are moving a site to Statamic 6, this addon release is the minimum you need. If you are staying on Statamic 5, confirm which addon line still supports your Statamic version before bumping, and do not assume the newest tag is a drop-in for an older CMS.

The version jump from the previously assessed 2.2.0 to 5.3.0 spans several majors that are not described in this release note. Treat the upgrade as a real version leap, not a patch: read the full changelog for everything between 2.2.0 and 5.3.0, and diff any published config, views, and assets rather than overwriting your local customisations.

A safe upgrade sequence:

1. Check your composer.json constraint for statamic/cms and confirm the addon version you are installing explicitly supports that major.
2. Run the update, then php artisan config:clear, php artisan view:clear, and clear the Stache (php artisan statamic:stache:clear) so blueprints, fieldsets, and asset containers are re-read.
3. Boot the control panel and open a publish form that already uses the file field — that is the fastest end-to-end proof that the addon still loads and renders.
4. Confirm the disk behind the field resolves correctly (check config/filesystems.php for the disk you intend to use, and verify the field’s declared disk, directory, visibility, and accepted file types).

Start with a single optional upload field on a model/blueprint you already manage. That keeps the upgrade surface small while proving disk configuration, validation, storage, and retrieval end to end.

Implementation Patterns

Treat file fields like any other Laravel upload, but keep the package field definition as the source of truth for disk and directory settings. A typical flow is:

• Define the file field with an explicit disk and directory rather than relying on the default disk.
• Validate in a FormRequest: ['file' => ['nullable', 'file', 'mimes:pdf,jpg,png', 'max:10240']].
• Store with $request->file('file')->store($directory, $disk) or the package’s storage helper if one is provided.
• Persist only the relative path in the database; generate URLs at render time.
• Use a model cast/accessor for URL generation so disk changes do not require data migrations.

For updates, decide whether a missing upload means “keep existing file” or “remove file.” A common pattern is a separate boolean remove flag plus nullable upload field. Delete replaced files in an observer or service class after the model update succeeds.

For larger files or image processing, store first and dispatch a queued job for thumbnails, virus scanning, or metadata extraction. For testing, use Storage::fake('disk') and UploadedFile::fake()->create(...), then assert the path exists and the model column was updated.

Keep a small support matrix for the CMS major. With 5.3.0 the split is roughly “Statamic 6 ⇒ addon ^5.3”, while Statamic 5 sites may need an earlier addon line. Pin the addon constraint to the CMS major in composer.json, and if you maintain your own CI, run the suite against both Statamic majors using a dependency matrix (e.g. composer require statamic/cms:^5 / ^6 in separate jobs). Also add one smoke test that simply boots the addon inside the CMS, since compatibility releases fail at provider/fieldtype registration long before they fail at file storage.

If your forms are rendered through Livewire, Inertia, or a custom Blade component, verify the package field outputs the correct enctype and accepts the framework’s temporary upload object. The control panel publish form handles multipart submission for you; front-end or bespoke forms are where you have to prove it yourself. API-driven forms should use standard multipart requests unless the package explicitly documents another transport.

Gotchas and Tips

• Missing enctype="multipart/form-data" is the most common cause of “file is null” reports. Check the rendered form before debugging package code. This applies to your own front-end forms — the CP takes care of it.
• PHP’s upload_max_filesize and post_max_size can reject uploads before Laravel validation runs. Keep the package/Laravel max rule aligned with PHP and web-server limits.
• Prefer mimetypes over mimes when you need stricter content-type validation; mimes checks extension-derived guesses.
• Be explicit about disk visibility. Public disks are fine for avatars and documents intended to be public; use private disks plus signed URLs for sensitive files.
• On S3 or other remote disks, avoid Storage::url() assumptions unless the disk is configured for public URLs. Use temporary URLs where appropriate.
• Delete old files deliberately. Replacing a path without removing the previous object creates orphaned storage and unexpected bills.
• Sanitize or hash filenames. User-supplied names can collide, contain unsafe characters, or leak original file names.
• After changing package, filesystem, or CMS config, run php artisan config:clear. Cached config frequently explains “my disk setting is ignored.”
• Statamic caches a lot more than Laravel. If blueprints, fieldsets, or containers look stale after the upgrade, clear the Stache and views before assuming the addon is broken.
• A clean composer update is not proof of Statamic 6 support. Other addons in the site may declare statamic/cms:^5 and block or silently downgrade the install — check the whole dependency tree, not just this package.
• Because you are jumping from 2.2.0 to 5.3.0, review published config/views/assets after upgrading. Republish or diff them rather than overwriting local customizations, and re-check any custom disk resolution or filename callbacks you added against the current API.
• In tests, fake the disk before the request and assert both the database path and Storage::disk(...)->assertExists(...).
• For debugging, inspect the request payload, $_FILES, storage disk permissions, and storage:link before assuming the field integration is broken.
• Useful extension points are usually custom disk resolution, filename generation callbacks, and model observers for cleanup. Keep those concerns outside the field definition so the same file field can be reused across resources.