If you want to connect Laravel to S3 storage, you are making a smart move for your website. Storing uploads like images, PDFs and videos in the cloud keeps your server light, makes backups simpler and lets your app grow without running out of disk space.
In this guide, we will walk through the whole process step by step. You do not need to be an expert. If you can edit a file and run a command in the terminal, you can follow along.
Why Store Laravel Files on S3?
By default, Laravel saves uploaded files on your own server. That works fine for small projects. As your business grows, though, local storage can cause problems.
Here is why many developers and business owners switch to S3 or S3-compatible storage:
- More space: You are not limited by your hosting disk size.
- Safer files: Your uploads live separately from your app, so a server problem does not wipe them out.
- Easier scaling: If you run more than one server, they can all share the same files.
- Private file links: You can create links that expire, which is great for paid downloads or private documents.
Laravel makes this easy because its Storage system already supports S3. You only need a package, a few settings and some keys.
What You Need Before You Start
Before you connect Laravel to S3 storage, gather these items:
- A working Laravel project with Composer installed.
- An Amazon Web Services (AWS) account, or an account with another S3-compatible storage provider.
- A bucket (a storage folder in the cloud) created in your chosen region.
- An access key and secret key from a user with permission to use that bucket.
Create a Bucket and Access Keys
In the AWS console, open the S3 service and create a new bucket. Choose a unique name and a region close to your customers. Keep "Block all public access" turned on unless you truly need public files.
Next, open IAM and create a new user for your app. Give it permission only for this bucket, not your whole AWS account. Then create an access key for that user and save both the key and the secret somewhere safe. You will only see the secret once.
Step-by-Step: Connect Laravel to S3 Storage
Now for the main part. Follow these steps in order.
Step 1: Install the S3 Package
Open your terminal in the project folder and run:
composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies
This installs the Flysystem adapter that Laravel uses to talk to S3.
Step 2: Add Your Keys to the .env File
Open your .env file and fill in these values:
- AWS_ACCESS_KEY_ID= your access key
- AWS_SECRET_ACCESS_KEY= your secret key
- AWS_DEFAULT_REGION= your bucket region, for example us-east-1
- AWS_BUCKET= your bucket name
- AWS_USE_PATH_STYLE_ENDPOINT=false
If you want S3 to be your main disk, also set FILESYSTEM_DISK=s3. Never commit your .env file to Git, because it holds secret keys.
Step 3: Check config/filesystems.php
Open config/filesystems.php. Laravel already includes an s3 disk that reads the values from your .env file. In most cases, you do not need to change anything here.
If you use an S3-compatible provider instead of Amazon, add AWS_ENDPOINT with your provider's URL in .env. Some providers also need AWS_USE_PATH_STYLE_ENDPOINT=true.
Step 4: Clear the Config Cache
Laravel may still be using old settings. Run:
php artisan config:clear
This step is easy to forget and causes a lot of confusion.
Uploading and Reading Files on S3
Once the setup is done, using S3 feels just like using local storage.
Upload a File
In a controller that handles a form upload, you can write:
$path = $request->file('photo')->store('photos', 's3');
Laravel gives the file a unique name and saves it in the photos folder of your bucket. Save the returned $path in your database so you can find the file later.
Get a File URL
For a public file, use Storage::disk('s3')->url($path). For a private file, create a link that expires:
Storage::disk('s3')->temporaryUrl($path, now()->addMinutes(10));
Temporary URLs are the safest way to share paid downloads, invoices or private documents.
Other Useful Commands
- Storage::disk('s3')->exists($path) checks whether a file is there.
- Storage::disk('s3')->delete($path) removes a file.
- Storage::disk('s3')->put('notes/hello.txt', 'Hello') saves text content directly.
Test the Connection Quickly
Before building a full upload form, test your setup with Tinker. Run php artisan tinker and type:
Storage::disk('s3')->put('test.txt', 'It works');
If it returns true, check your bucket in the console. You should see test.txt. That means you have managed to connect Laravel to S3 storage correctly.
Common Errors and How to Fix Them
Things do not always work the first time. Here are the usual problems:
- "Class not found" error: The Flysystem package is missing. Run the Composer command again.
- Access Denied (403): Your IAM user lacks permission, or the bucket name is wrong. Review the policy.
- Wrong region error: Make sure AWS_DEFAULT_REGION matches the bucket's real region.
- Settings not changing: Run php artisan config:clear again.
- Public URL not loading: The bucket is private. Use a temporary URL or adjust bucket access carefully.
Security Tips
Give your app's user the smallest set of permissions it needs. Rotate keys from time to time, and remove keys you no longer use. Also validate uploads in Laravel, such as file type and size, before sending them to S3.
Where Your Laravel App Should Live
Remember that S3 only stores files. Your Laravel code, database and admin panel still need a reliable server. Our web hosting plans give your app a fast home, while S3 handles heavy uploads.
If you are planning a file-heavy business, such as a cloud storage service, browse our ready-made Laravel scripts. For example, Vaultora is a cloud storage hosting script with an S3-compatible API.
Need Help Setting It Up?
Learning to connect Laravel to S3 storage is a valuable skill, and with the steps above most projects can be ready in under an hour. But if you would rather focus on your business, our team can handle it for you, from installation to custom upload features.
Ready to get started? Check out our Laravel web development service and let us set up secure, scalable cloud storage for your app.
Frequently asked questions
Which package do I need to connect Laravel to S3?
You need the Flysystem S3 adapter. Install it with composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies.
Can I use S3-compatible storage instead of Amazon S3?
Yes. Many providers offer S3-compatible APIs. Set AWS_ENDPOINT to the provider's URL, and set AWS_USE_PATH_STYLE_ENDPOINT to true if the provider requires it.
Why do I get an Access Denied error when uploading?
Usually the IAM user is missing permissions for the bucket, or the bucket name or region in your .env file is wrong. Check the policy and your settings, then clear the config cache.
How do I make uploaded files private?
Keep the bucket private and use Storage::disk('s3')->temporaryUrl() to create links that expire after a set time.
Do I still need web hosting if my files are on S3?
Yes. S3 only stores files. Your Laravel application, database and code still need a web server or hosting plan to run.
