Storage

This document explains where the package stores files and how to move that storage to an S3-compatible bucket by hand. It covers the three kinds of file the package writes, the configuration each one reads, step-by-step setup for Laravel Cloud Object Storage, Amazon S3 and Wasabi, moving media that is already on the local disk into a bucket, and the faults that follow from an incomplete setup. It is written for the developer who deploys a site running the package.

Built-in support

Storage is configured manually today. The package ships no installer prompt, environment key or command for choosing a storage provider, and every step in this document is a change the site makes to its own configuration files and environment. Built-in configuration is on the roadmap: environment keys for the media disk and the form upload disk, installer and diagnostic warnings for a local media disk on a host that discards its filesystem on deploy, a cms:media-move command, and documented provider presets. The roadmap entry is in docs/ROADMAP.md in the package's repository.

What the package stores and where

The package writes three kinds of file. Each one is written to a Laravel filesystem disk, and each disk is chosen by a different configuration key.

Media library items

Mcg\FilamentCms\Models\MediaItem::registerMediaCollections() registers the media collection with useDisk(config('cms.media.disk', 'public')). Spatie Media Library then writes every file of an item to that disk and records the disk's name in the disk and conversions_disk columns of the media table. The name is stored per row, so a row written while the setting was public keeps reading from the disk named public after the setting changes.

Spatie's DefaultPathGenerator places each item under a directory named after the media row's id:

When media-library.prefix (environment variable MEDIA_PREFIX) is set, every path above is preceded by that prefix and a slash.

A media URL is the disk's url setting followed by the path. On the local public disk that url is APP_URL followed by /storage, which is why media.md treats an incorrect APP_URL as a fault that breaks every image. On an S3 disk the url is the bucket's public base URL. The media disk must therefore serve its files publicly without a signature.

Form uploads

Mcg\FilamentCms\Livewire\MultiStepForm::promoteUploads() stores each file answer on the disk named by cms.forms.upload_disk, under cms/form-uploads/YYYY/MM (the directory is cms.forms.upload_directory). The form_submissions row records the file's path only, not the disk, so the package always reads and deletes the file through whichever disk cms.forms.upload_disk names at that moment.

The upload disk must be private. Submissions carry CVs, invoices and photographs of documents, and a file on a public disk can be fetched by anyone who has or guesses its URL. The submission view in the admin panel (SubmissionsRelationManager) shows each uploaded file's stored name as a link to the panel route GET {panel path}/form-submissions/{submission}/files/{field} (route name filament.{panel id}.cms.submissions.download). The route runs behind the panel's sign-in and canAccessPanel() check, requires the cms.submissions.view ability when permissions are enabled, and streams the file with Storage::disk(config('cms.forms.upload_disk'))->download(), which reads the local disk and S3-compatible disks the same way. The disk stays private, and the package generates no public or temporary URL for the file. A file that is no longer on the disk is listed with the note "File is missing from the upload disk." and no link.

Livewire's temporary uploads

Every file uploaded through Livewire, in a CMS form or on the panel's Media screen, is written first to Livewire's temporary upload disk under livewire-tmp/, and is copied to its final disk when the form is saved.

On a host that runs more than one application container, such as Laravel Cloud, the temporary disk must be a bucket that every container can read. The browser uploads the file to one container and submits the form to another, and a file on the first container's local disk does not exist on the second.

When the temporary disk uses the s3 driver, Livewire does not send the file through the application at all. It gives the browser a pre-signed URL, and the browser sends the file straight to the bucket with an HTTP PUT. The bucket's CORS policy must therefore allow PUT from the site's origin. Laravel Cloud manages that policy itself (see Laravel Cloud Object Storage). On Amazon S3 and Wasabi the site sets it.

Code that hands a temporary upload's path to an API expecting a local file fails on an S3 temporary disk with File does not exist. The cause and the TemporaryUpload::withLocalCopy() helper that fixes it are described in pitfalls.md.

The staging-disk warning on forms

A form with a File upload field shows signed-in visitors the message "This form accepts file uploads, but Livewire stages them on a public disk. Set livewire.temporary_file_upload.disk to a private disk." when MultiStepForm::stagingDiskIsPublic() returns true. The method reads the temporary disk's definition in config/filesystems.php and returns:

1. true when the definition has 'visibility' => 'public'.
2. false when the definition has 'visibility' => 'private'.
3. false when the definition has no visibility key and its driver is local.
4. true when the definition has no visibility key and its driver is anything else, including s3.

An S3 disk definition without a visibility key therefore triggers the warning even when the bucket is private. The Amazon S3 and Wasabi disk definitions below set 'visibility' => 'private' on the uploads disk for this reason. Flysystem's S3 adapter sends the private ACL on every write when the disk sets no visibility, so adding the key does not change what is sent to the bucket.

Before any provider

The two steps in this section apply to every S3-compatible provider in this document.

Installing the S3 adapter

Laravel's s3 driver needs the Flysystem S3 adapter, which the package does not require.

1. In a terminal at the site's root, run:

``shell composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies ``

1. In composer.json at the site's root, find the league/flysystem-aws-s3-v3 line under require. On Windows, Composer can write the constraint as "3.0" without the caret. That value pins release 3.0.0, an old release whose AwsS3V3Adapter emits PHP 8.4 deprecation warnings. If the line reads "3.0", change it to "^3.0" and save the file.
2. In the same terminal, if you changed the line in step 2, run:

``shell composer update league/flysystem-aws-s3-v3 --with-all-dependencies ``

1. In the same terminal, run composer show league/flysystem-aws-s3-v3. The versions line should show a 3.x release later than 3.0.0.
2. Commit composer.json and composer.lock.

Making the CMS disks configurable from the environment (optional)

Neither cms.media.disk nor cms.forms.upload_disk reads an environment variable. Both are literal strings in the published config/cms.php. A site that keeps the disk names public and local does not need this step. A site that wants to name the disks per environment, which the Laravel Cloud steps below do for the upload disk, makes the change itself:

1. In config/cms.php at the site's root, under the 'media' array, change

``php 'disk' => 'public', ``

to

``php 'disk' => env('CMS_MEDIA_DISK', 'public'), ``

1. In the same file, under the 'forms' array, change

``php 'upload_disk' => 'local', ``

to

``php 'upload_disk' => env('CMS_FORMS_UPLOAD_DISK', 'local'), ``

1. Save the file and commit it.

The defaults in both calls equal the values the file held before, so an environment that sets neither variable behaves exactly as before. Changing CMS_MEDIA_DISK affects new uploads only. Existing media rows keep the disk name they were written with, as described in Media library items.

CMS_MEDIA_DISK and CMS_FORMS_UPLOAD_DISK are names chosen for this edit. The package itself reads neither variable until the built-in support described in Built-in support ships.

Local disk

The local disks are the defaults and need no setup beyond what cms:install does. They are correct for a site served from one machine whose filesystem persists across deploys, such as a VPS or a shared host.

1. In a terminal at the site's root, confirm that public/storage is a link to storage/app/public. cms:install creates it by running storage:link. If it is missing, run php artisan storage:link.
2. In .env at the site's root, confirm that APP_URL is the site's public address, with the scheme the site is served over. Media URLs are built from it, as described in media.md.
3. In the same file, leave LIVEWIRE_TEMPORARY_FILE_UPLOAD_DISK unset, or set it to local.
4. On the deploy target, confirm that storage/app/public and storage/app/private persist across deploys. A deploy process that replaces the whole application directory must keep storage/ in a shared location, or every uploaded file is lost on the next deploy.

Laravel Cloud Object Storage

Laravel Cloud discards each container's local filesystem on every deploy and does not share it between replicas. A site on Laravel Cloud must keep media, form uploads and Livewire's temporary uploads in Laravel Cloud Object Storage.

Laravel Cloud Object Storage is backed by Cloudflare R2. R2 applies visibility to a whole bucket, not to individual files: every file in a public bucket is public and every file in a private bucket is private. R2 does not support per-object ACL headers, and Laravel Cloud's documentation states that a disk configured with visibility: 'public' is rejected with a NotImplemented error. A site with public media and private form uploads therefore needs two buckets.

The media bucket's disk name must be exactly public. Every existing row in the media table stores the disk name public, and cms.media.disk defaults to public. Attaching the bucket under that name redirects all existing and new media to the bucket without any database change.

Laravel Cloud manages each bucket's CORS policy. It adds every domain of every environment the bucket is attached to, and allows GET, POST, PUT, DELETE and HEAD by default, which covers Livewire's direct PUT upload.

One-time setup

1. In a terminal at the site's root, install the S3 adapter as described in Installing the S3 adapter, commit, and push.
2. In a terminal at the site's root, make the upload disk configurable as described in Making the CMS disks configurable from the environment, commit, and push. The media disk edit is optional on Cloud, because the media bucket keeps the name public.
3. **In the Laravel Cloud dashboard, on the environment's infrastructure canvas**, click "Add bucket". Create a new bucket, select "Laravel Object Storage" as the bucket type, set its file visibility to Public, and enter public as the disk name. Do not make it the default disk.
4. On the same canvas, click "Add bucket" again. Create a second bucket, select "Laravel Object Storage", set its file visibility to Private, enter a disk name such as private, and make it the environment's default disk.
5. In the Laravel Cloud dashboard, on the media bucket's settings page, copy the bucket's public URL (shown as AWS_URL). Laravel Cloud shows this value but does not inject it as an environment variable.
6. **In the Laravel Cloud dashboard, on the environment's General Settings, under custom environment variables**, add:

``dotenv LIVEWIRE_TEMPORARY_FILE_UPLOAD_DISK=private CMS_FORMS_UPLOAD_DISK=private ``

Replace private with the disk name you gave the private bucket in step 4. If your config/filesystems.php defines the public disk's url from AWS_URL, also add AWS_URL with the value copied in step 5.

1. In the Laravel Cloud dashboard, redeploy the environment. Bucket attachments and environment variables take effect only after a deploy.
2. In the admin panel, on the Media screen, upload an image, open it, and copy its URL. The URL should begin with the media bucket's public URL, not with the site's own domain followed by /storage.
3. On a page with a form that has a File upload field, submit a test file. In the admin panel, under Forms, open the form, then open the submission. The file's entry should be a link; clicking it should download the file. An entry reading "File is missing from the upload disk." means the panel is reading a different disk from the one the form wrote to.

After any change to buckets or variables

1. In the Laravel Cloud dashboard, redeploy the environment. A bucket attached, detached or renamed, or a variable added or changed, has no effect on the running containers until the next deploy.

Reaching a bucket from a development machine

Livewire's direct upload from a development site, for example https://example.test, fails on CORS unless that origin is allowed.

1. In the Laravel Cloud dashboard, under Org > Resources > Object storage, click "..." next to the bucket and select "Edit settings".
2. In the "Allowed origins" field, add the development origin with its scheme, for example https://example.test, on its own line, and save.

Amazon S3

On Amazon S3 the site creates the buckets, the credentials and the disk definitions itself. Use two buckets: a public bucket for media and a private bucket for form uploads and Livewire's temporary uploads.

New S3 buckets have Object Ownership set to "ACLs disabled" and Block public access turned on. With ACLs disabled, S3 refuses a write that carries the public-read ACL, which Flysystem sends whenever a disk sets 'visibility' => 'public'. The media bucket below is made public with a Bucket policy instead, and its disk definition sets no visibility key.

One-time setup

1. In a terminal at the site's root, install the S3 adapter as described in Installing the S3 adapter.
2. In the AWS console, in S3, create the media bucket, for example example-media. Leave Object Ownership at "ACLs disabled".
3. On the media bucket's Permissions tab, under "Block public access", turn off "Block all public access" and save.
4. On the same tab, under "Bucket policy", add this policy, replacing example-media with the bucket's name:

``json { "Version": "2012-10-17", "Statement": [ { "Sid": "PublicReadForMedia", "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::example-media/*" } ] } ``

1. In the AWS console, in S3, create the private bucket, for example example-private. Leave Object Ownership at "ACLs disabled" and leave "Block all public access" turned on.
2. **On the private bucket's Permissions tab, under "Cross-origin resource sharing (CORS)"**, add this policy, replacing the origin with the site's address:

``json [ { "AllowedOrigins": ["https://www.example.com"], "AllowedMethods": ["PUT", "GET", "HEAD"], "AllowedHeaders": ["*"], "MaxAgeSeconds": 3000 } ] ``

Livewire's direct upload sends a PUT from the browser to this bucket.

1. In the AWS console, in IAM, create a user or role for the application with an access key, and grant it s3:PutObject, s3:GetObject, s3:DeleteObject and s3:ListBucket on both buckets.
2. In config/filesystems.php at the site's root, replace the public disk's definition and add an uploads disk inside the 'disks' array:

```php 'public' => [ 'driver' => 's3', 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION'), 'bucket' => env('AWS_MEDIA_BUCKET'), 'url' => env('AWS_MEDIA_URL'), 'endpoint' => env('AWS_ENDPOINT'), 'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false), 'throw' => false, 'report' => false, ],

'uploads' => [ 'driver' => 's3', 'key' => env('AWS_ACCESS_KEY_ID'), 'secret' => env('AWS_SECRET_ACCESS_KEY'), 'region' => env('AWS_DEFAULT_REGION'), 'bucket' => env('AWS_PRIVATE_BUCKET'), 'endpoint' => env('AWS_ENDPOINT'), 'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false), 'visibility' => 'private', 'throw' => false, 'report' => false, ], ```

Keeping the name public for the media disk means existing media rows, which store the disk name public, read from the bucket without a database change. This definition applies in every environment that loads this file, including development machines, unless their .env points the keys at a different bucket.

1. In config/cms.php at the site's root, set 'upload_disk' to 'uploads', or make it read CMS_FORMS_UPLOAD_DISK as described in Making the CMS disks configurable from the environment.
2. In the production .env, add:

``dotenv AWS_ACCESS_KEY_ID=your-access-key-id AWS_SECRET_ACCESS_KEY=your-secret-access-key AWS_DEFAULT_REGION=us-east-1 AWS_MEDIA_BUCKET=example-media AWS_MEDIA_URL=https://example-media.s3.us-east-1.amazonaws.com AWS_PRIVATE_BUCKET=example-private LIVEWIRE_TEMPORARY_FILE_UPLOAD_DISK=uploads CMS_FORMS_UPLOAD_DISK=uploads ``

Use the region the buckets were created in, in both AWS_DEFAULT_REGION and AWS_MEDIA_URL. CMS_FORMS_UPLOAD_DISK has an effect only after the optional config/cms.php edit.

1. In a terminal on the server, run php artisan config:clear, or rebuild the configuration cache if the deploy runs php artisan config:cache.
2. In the admin panel, on the Media screen, upload an image and confirm that its URL begins with the AWS_MEDIA_URL value and opens in a browser.
3. On a page with a form that has a File upload field, submit a test file. In the admin panel, under Forms, open the form, then open the submission. The file's entry should be a link; clicking it should download the file. An entry reading "File is missing from the upload disk." means the panel is reading a different disk from the one the form wrote to.

Cleaning up abandoned temporary uploads (optional)

On a local temporary disk, Livewire deletes temporary files older than 24 hours itself. On an S3 temporary disk it relies on a bucket lifecycle rule.

1. **In a terminal at the site's root, with the production credentials loaded**, run php artisan livewire:configure-s3-upload-cleanup. The command adds a lifecycle rule to the temporary disk's bucket that expires objects under livewire-tmp/ after one day.

Wasabi

Wasabi is S3-compatible, so the Amazon S3 setup applies with a different endpoint, URL and console. Use two buckets, as on Amazon S3.

Wasabi's service URL for a region has the form https://s3.<region>.wasabisys.com, for example https://s3.us-east-1.wasabisys.com. The configuration below sets AWS_USE_PATH_STYLE_ENDPOINT=false.

One-time setup

1. In a terminal at the site's root, install the S3 adapter as described in Installing the S3 adapter.
2. In the Wasabi console, create the media bucket and the private bucket in the same region, and note the region's identifier, for example us-east-1. Confirm the region's service URL in Wasabi's list of service URLs, which Wasabi publishes per region.
3. In the Wasabi console, on the media bucket's settings, add a bucket policy that grants public s3:GetObject, using the same JSON as step 4 of the Amazon S3 setup with example-media replaced by the bucket's name. Wasabi can restrict public access at the account level. If the console refuses the policy, or a test file's URL returns AccessDenied after the policy is saved, check the account's public access settings in the Wasabi console and Wasabi's documentation on public buckets before continuing.
4. In the Wasabi console, on the private bucket's settings, confirm the bucket has no public policy, and add a CORS rule allowing PUT, GET and HEAD from the site's origin, equivalent to step 6 of the Amazon S3 setup. If the console offers no CORS editor for the bucket, check Wasabi's documentation for how CORS is set on that account before relying on Livewire's direct upload.
5. In the Wasabi console, create an access key for a user with read, write, delete and list permission on both buckets.
6. In config/filesystems.php at the site's root, add the same public and uploads definitions as step 8 of the Amazon S3 setup. They read AWS_ENDPOINT, which is what points them at Wasabi.
7. In config/cms.php at the site's root, set 'upload_disk' to 'uploads', or make it read CMS_FORMS_UPLOAD_DISK.
8. In the production .env, add:

``dotenv AWS_ACCESS_KEY_ID=your-wasabi-access-key AWS_SECRET_ACCESS_KEY=your-wasabi-secret-key AWS_DEFAULT_REGION=us-east-1 AWS_ENDPOINT=https://s3.us-east-1.wasabisys.com AWS_USE_PATH_STYLE_ENDPOINT=false AWS_MEDIA_BUCKET=example-media AWS_MEDIA_URL=https://s3.us-east-1.wasabisys.com/example-media AWS_PRIVATE_BUCKET=example-private LIVEWIRE_TEMPORARY_FILE_UPLOAD_DISK=uploads CMS_FORMS_UPLOAD_DISK=uploads ``

AWS_MEDIA_URL is the public object URL form https://s3.<region>.wasabisys.com/<bucket>. A media URL is that value followed by the file's path.

1. In a terminal on the server, run php artisan config:clear, or rebuild the configuration cache.
2. In the admin panel, on the Media screen, upload an image and open its URL in a private browser window. The image should load without signing in.
3. On a page with a form that has a File upload field, submit a test file. In the admin panel, under Forms, open the form, then open the submission. The file's entry should be a link; clicking it should download the file. An entry reading "File is missing from the upload disk." means the panel is reading a different disk from the one the form wrote to.

Moving existing media to a bucket

A site that has run on the local public disk has its media files in storage/app/public, laid out as described in Media library items. Moving them is a copy of that directory tree to the media bucket, followed by pointing the public disk at the bucket. The package ships no command for this today.

Procedure

1. In a terminal on the machine that holds the files, configure a client with credentials that can write to the media bucket. With the AWS CLI, run aws configure --profile media and enter the access key ID and secret. For Laravel Cloud, the bucket's endpoint, access key ID and secret are in the dashboard under Organization > Resources > Object storage, on the bucket's Access keys section, under "..." > View credentials. The key must be "Read and write".
2. In the same terminal, at the site's root, copy the whole tree, keeping every path:

``shell aws s3 sync storage/app/public s3://BUCKET --endpoint-url ENDPOINT --profile media ``

Replace BUCKET with the media bucket's name and ENDPOINT with the provider's endpoint (the R2 endpoint from Laravel Cloud's credentials, or https://s3.<region>.wasabisys.com). On Amazon S3, omit --endpoint-url. rclone sync storage/app/public REMOTE:BUCKET performs the same copy with an rclone remote configured for the provider.

1. In the same terminal, compare the file counts: find storage/app/public -type f | wc -l against aws s3 ls s3://BUCKET --recursive --endpoint-url ENDPOINT --profile media | wc -l. The two numbers should match.
2. Point the public disk at the bucket by following the provider's section above: attach the bucket under the disk name public on Laravel Cloud, or replace the public disk definition on Amazon S3 and Wasabi.
3. In the admin panel, on the Media screen, open an item that existed before the move and confirm its image loads from the bucket's URL.

The media rows need no change when the disk name stays public. Each row's disk and conversions_disk columns already hold public, and each file's path inside the bucket equals its path inside storage/app/public.

If the media disk is given a different name, for example media, every existing row must also be updated, or those items keep reading from the old disk. Both columns must change:

Back up the database before running either statement.

Moving existing form uploads

Form uploads already stored on the local local disk are under storage/app/private/cms/form-uploads. The submission rows store only the path relative to the disk, so the files must keep that path in the private bucket.

1. In a terminal at the site's root, run:

``shell aws s3 sync storage/app/private/cms/form-uploads s3://PRIVATE-BUCKET/cms/form-uploads --endpoint-url ENDPOINT --profile private ``

Copy only cms/form-uploads. The rest of storage/app/private belongs to the application and to Livewire's temporary uploads.

Troubleshooting

Images are missing after a deploy on Laravel Cloud

Every media item shows a broken image after a deploy. The media rows still exist, but their files do not. The files were written to the local public disk inside a container, and Laravel Cloud discards the container's filesystem on every deploy. The files cannot be recovered from Cloud. Attach a public bucket under the disk name public as described in Laravel Cloud Object Storage, then upload the lost files again with the Media screen's replace action so each item keeps its id.

An upload fails with File does not exist

The error names a path that was never a local file. The temporary upload disk is a bucket, and code passed the temporary file's object key to an API that expects a local filename. The cause and the fix are in pitfalls.md.

Image URLs point at /storage on the site's own domain on Laravel Cloud

Media URLs read https://your-site/storage/14/... and return 404. The disk named public is still the local disk from config/filesystems.php, which means no bucket is attached to the environment under the disk name public. Check the disk name on the media bucket's attachment in the Laravel Cloud dashboard; it must be exactly public. Redeploy after correcting it.

PHP deprecation warnings from AwsS3V3Adapter

The log or the page shows PHP 8.4 deprecation warnings raised in League\Flysystem\AwsS3V3\AwsS3V3Adapter. The installed adapter is release 3.0.0, usually because Composer on Windows wrote the constraint "3.0" without the caret. Correct the constraint and update the package as described in Installing the S3 adapter.

Forms show "Livewire stages them on a public disk"

The message is shown to signed-in visitors on a form with a File upload field. The temporary upload disk's definition either sets 'visibility' => 'public' or has no visibility key and a driver other than local. The rules are in The staging-disk warning on forms. On Amazon S3 and Wasabi, add 'visibility' => 'private' to the temporary disk's definition. Do not add 'visibility' => 'public' to any disk on Laravel Cloud.