What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Laravel 13’s read-through filesystem lets an application write new files to S3 while continuing to find older files on local storage: it checks S3 first, then reads a local fallback and promotes a matching file to S3. For files you want to transfer deliberately, use copyToDisk to retain the source or moveToDisk to remove it after the move. This supports a gradual migration, but it does not eliminate every concurrency or cutover risk.
The APIs discussed here are documented for Laravel 13.x. Check the filesystem methods available in your application’s Laravel version before adopting the examples. Laravel 13.x filesystem documentation
As an Amazon Associate I earn from qualifying purchases.
How read-through migration works
A read-through disk combines a primary disk and a fallback disk. During migration, configure S3 as primary and the existing local disk as fallback. Laravel checks the primary first; if the file is found only on the fallback, a qualifying read can promote it to the primary. Writes and directory listings target the primary.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteThat means the application can keep serving older files while new writes go to S3, provided application code uses the composite disk and the underlying disks are reachable. Laravel describes read-through disks as a way to migrate files between disks without downtime, but the phrase should not be read as a guarantee that every race, outage, or cutover concern disappears. Laravel’s migration article
#1 Best Overall
Prepare the two disks
Inventory local storage and file paths
Identify the disk and root that currently hold uploads, whether files are public or private, and how the application stores their relative paths. Preserve the existing path convention where possible: filesystem operations resolve paths relative to each disk’s configured root.
Configure and verify S3
Laravel’s S3 driver requires the league/flysystem-aws-s3-v3 adapter. Configure the bucket, region, and credentials in the application’s filesystem configuration. Laravel also documents S3-compatible services using provider credentials and an endpoint; check the selected provider’s current requirements. Laravel filesystem configuration
Add a read-through disk
Once both underlying disks are configured and reachable, add a composite disk. This is the documented configuration shape; use the actual names from your application:
'assets' => [
'driver' => 'read-through',
'primary' => 's3',
'fallback' => 'legacy-local',
],Laravel permits disk names or inline disk configuration arrays for the primary and fallback. Point the application’s intended storage path at the composite only after the underlying disks are ready. Laravel’s read-through configuration example
Route uploads through the composite disk
New uploads must use the intended disk. Laravel’s uploaded-file store method accepts a disk name and returns a path relative to that disk’s root. Code that explicitly names the old local disk can bypass the composite, even if the application’s default disk has changed. Find and update those explicit references. Laravel request and uploaded-file documentation
Keep database references and callers aligned with the relative paths stored by the application. Validate that files written through the composite land on S3 and that existing local paths remain readable before proceeding with bulk transfer.
Rank #3
Choose lazy promotion, bulk transfer, or both
Let reads promote active files
When a file is read from the fallback, Laravel can copy it to the primary for later requests. This gradually transfers files users still access, but cold files remain on local storage until read. A metadata or existence check is not a migration: exists, metadata checks, and visibility checks inspect primary and then fallback without promoting the file.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Copy files when the local source must remain
For an explicit transfer that retains the source, use copyToDisk:
Storage::disk('local')->copyToDisk('s3', 'reports/report.csv');Move files when source removal is intended
moveToDisk transfers across disks and removes the source when the move succeeds. Its optional third argument specifies a different destination path:
Storage::disk('local')->moveToDisk(
's3',
'reports/report.csv',
'archive/report.csv'
);Use a move only when deleting the source is the desired outcome; choose a copy workflow when the local version must be retained. Check error handling and cleanup behavior in your target Laravel release. Laravel’s migration article notes that a failed fallback cleanup during a read-through move surfaces as an UnableToMoveFile error. Laravel filesystem methods
Inventory the fallback directly for bulk work
A read-through disk’s directory listing reports primary contents only. A bulk job that lists the composite will therefore miss files that still exist only on local storage. Enumerate the fallback disk directly, then skip paths already present at the destination to avoid redundant copies or overwrites.
For a bulk worker, also define how it handles duplicate processing and application writes occurring during transfer. Those are operational safeguards, not guarantees supplied by the filesystem API.
| Consideration | Read-through promotion | Explicit bulk transfer |
|---|---|---|
| When transfer happens | When a qualifying read accesses the fallback file | When a worker or operator processes the path |
| Cold files | Remain on fallback until read | Can be migrated without a user read |
| Source retention | Promotion copies fallback data to primary | copyToDisk retains the source; moveToDisk removes it after a successful move |
| Inventory | Composite listings show primary state only | Enumerate fallback directly and skip paths already at destination |
| Concurrency | A documented race remains for mutable paths between the last primary check and promotion write | Define safeguards for concurrent application writes and duplicate job processing |
The read-through behavior and transfer methods are documented by Laravel; the bulk-worker concurrency guidance is an operational precaution. Laravel migration guidance
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Account for failure and concurrency behavior
Do not treat fallback as general S3 outage failover
If checking or reading the primary fails, Laravel’s migration article says the failure remains a primary failure rather than triggering fallback. The fallback is for files absent from the primary, not a general recovery path for a broken or unavailable S3 connection.
Handle promotion failures deliberately
By default, a failed promotion does not fail the read. Laravel documents the throw_on_promotion_failure option for applications that want promotion failures to throw. Choose how the application will observe and remediate failed promotions rather than assuming successful reads prove migration succeeded.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Protect mutable paths
Read-through performs another primary check before promoting a fallback file, but that final check and the write are separate operations. A concurrent overwrite can still race with promotion. Immutable or versioned keys, or coordinating writes during migration, reduce the risk. Once a path has been promoted, later changes made only to the fallback are no longer visible through that path.
Verify URLs, visibility, and access
Moving bytes does not guarantee that existing links or access rules continue to behave the same way. Laravel’s documented public-local setup uses storage/app/public and exposes it through the public/storage symbolic link. S3 URL behavior differs, so verify destination visibility, URL generation, and any CDN or custom-host configuration against how the application serves files. Laravel URL and visibility documentation
Retire local storage only after verification
Do not use user traffic alone as proof that migration is complete: cold files may never have been promoted. Before removing the fallback, process its inventory and verify that destination objects are readable with the expected metadata and visibility, application references still resolve, and no process continues to write to the old store. These checks follow from the documented primary-only listing and routing behavior; Laravel does not prescribe a universal retirement checklist.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
