Skip to main content
Powered by Cloudflare R2

​
Introduction

Laravel Cloud allows you to create S3-compatible object storage buckets and attach them to your application’s environments directly from the Laravel Cloud dashboard. Laravel Cloud Object Storage is offered in partnership with Cloudflare R2. Laravel Cloud Object Storage may be used as an S3-compatible file storage backend for your application. Laravel applications can interact with the bucket via Laravel’s Storage facade, and Symfony applications may use any S3-compatible storage integration.

​
Laravel prerequisites

Before utilizing Laravel Object Storage, you should ensure your application includes the league/flysystem-aws-s3-v3 package in its composer.json dependencies:

​
Creating buckets

To attach a Laravel Object Storage bucket to an environment, click “Add bucket” on your environment’s infrastructure canvas dashboard. When adding a bucket to an environment, Laravel Cloud will prompt you to select the bucket you would like to attach to the environment or to create a new bucket. When creating a new bucket, select “Laravel Object Storage” as your bucket type. Once the bucket has been attached to an environment, you will need to re-deploy the environment in order for the changes to take effect. Visit the pricing docs for information on compute and storage prices.

​
Bucket disk names

When creating a bucket, you will also be prompted to provide a “disk name”. This name corresponds to the name you will use when accessing the bucket / disk via Laravel’s Storage facade:
You will also be able to indicate if the disk should be the “default” disk for the Laravel application. When a bucket is the default disk, you do not need to provide its name when accessing it via Laravel’s Storage facade:

​
Bucket file visibility

When creating a bucket, you will be prompted to select the bucket’s file visibility. All files added to the bucket will receive the specified visibility, and Laravel Cloud Object Storage buckets do not support mixing file visibility settings within a single bucket.
  • Private buckets: all files within the bucket are private and are not publicly accessible via the Internet. However, temporary public URLs may be generated to files within these buckets using the Storage::temporaryUrl method offered by Laravel. These buckets are typically used for private assets like personal documents uploaded by your application’s users.
  • Public buckets: all files within the bucket are public and are publicly accessible via the Internet via a Laravel Cloud provided URL. These buckets are typically used for publicly viewable assets like user avatars.
Cloudflare R2 manages visibility at the bucket level and does not support per-object ACL headers. Do not set visibility: 'public' in your Flysystem storage configuration; R2 will reject the request with a NotImplemented error. Bucket-level visibility, set when the bucket is created, governs object access.

​
Restricted file types

Laravel Object Storage buckets do not accept .html or .htm files. Any .html or .htm file uploaded to a bucket is deleted automatically. If your application needs to store .html files, contact support to request an exception.

​
CORS policy

Laravel Cloud automatically manages CORS (Cross-Origin Resource Sharing) policies for your object storage buckets to ensure browsers will permit cross-origin requests.

​
Automatic domain inclusion

When you attach a bucket to an environment, all of the environment’s custom and Cloud domains are automatically included in the bucket’s CORS policy. This happens automatically without any configuration required on your part.

​
Custom allowed origins

In addition to your environment’s domains, you may specify additional origins that should be allowed to access your bucket. This is particularly useful for:
  • Local development environments (e.g., http://example.test)
  • External domains that need access to your bucket
  • Testing from non-production environments
To add custom allowed origins:
  1. Navigate to your organization’s resources page by clicking Org > Resources > Object storage from the main dashboard.
  2. Click the ”…” menu next to the bucket you want to configure.
  3. Select “Edit settings”.
  4. In the “Allowed origins” field (only visible for public buckets), enter the origins you want to allow, separated by new lines.
  5. Each origin must be prefixed with the protocol (https:// or http://).

​
Local development

To connect to your object storage buckets from your local Laravel application, add your local development domain (e.g., http://example.test) to the bucket’s allowed origins. This makes it easy to test file uploads and storage operations during development.

​
Technical details

The CORS policy applied to your buckets allows the following:
  • Methods: GET, POST, PUT, DELETE, HEAD
  • Headers: All headers (*) are permitted
  • Origins: All environment domains plus any custom origins you’ve configured

​
Connecting to buckets

​
From your application

When a bucket is attached to a Laravel or Symfony environment, Laravel Cloud automatically injects FILESYSTEM_DISK and AWS S3-compatible connection variables. JavaScript, Go, and Python applications receive the AWS S3-compatible variables, including AWS_BUCKET, AWS_ENDPOINT_URL, AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY, when the bucket is attached as the environment’s default disk. You may view these variables in your environment’s General Settings.
For public buckets, AWS_URL (the bucket’s public base URL) is shown on the bucket settings page but is not automatically injected as an environment variable. If your application references AWS_URL, copy the value from the bucket settings page and add it manually under your environment’s custom environment variables. The AWS SDK for JavaScript (v3) also doesn’t read AWS_ENDPOINT_URL automatically, so Next.js and Nuxt applications should pass the endpoint to their S3 client explicitly.
The injected AWS_ENDPOINT_URL, AWS_REGION, and credential variables are global AWS SDK settings rather than S3-specific ones, so every AWS SDK client in your application will pick them up. If your application also talks to other AWS services, define your own AWS_* environment variables — they take precedence over the injected values — and configure your bucket’s S3 client explicitly.

​
From your local machine

To connect to your bucket from your local machine using a Cloudflare R2 compatible bucket management client like Cyberduck:
  1. Navigate to Organization > Resources > Object storage and click your bucket. In the Access keys section, click … next to the access key you want to use, then select View credentials.
  1. The bucket credentials modal window will provide you with the name, endpoint, access key ID, and access key secret needed to connect to your bucket.
  1. When connecting to the bucket via Cyberduck:
    • Open Cyberduck, select ”+” in the bottom left-hand corner to create a new bookmark, and select “Cloudflare R2 Storage (S3)” as the connection type. If this is your first time using the Cloudflare R2 Storage connection, you may need to add it from Settings > Profiles. Learn more
    • Enter the “AWS_ENDPOINT” bucket credentials value into the Cyberduck “Server” field
    • Enter the “AWS_ACCESS_KEY_ID” bucket credentials value into the Cyberduck “Access Key ID” field
    • Enter the “AWS_SECRET_ACCESS_KEY” bucket credentials value into the Cyberduck “Access Key Secret” field
    • Enter the “AWS_BUCKET” value into the Cyberduck “Path” field (under “More Options”).
      • If you do not see “More Options”, you likely clicked “Open Connection” instead of creating a new bookmark from the first step.
    • Optional: Give your Bookmark a “Nickname”
  2. Your new Cyberduck connection should look like this when completed. You can now close the “Open connection” modal and connect to your bucket.

​
Editing buckets

You may edit Laravel Object Storage buckets from your organization’s Resources page. Navigate to the Object storage tab and click the … icon for the bucket you would like to edit. Then, click Edit settings.

​
Monitoring bucket metrics

To view your bucket’s metrics, navigate to Organization > Resources > Object storage, click your bucket, and review the Metrics section. Use the time range selector to adjust the period shown. You can also view metrics for attached buckets from your environment’s Metrics tab. You can monitor the following for each bucket:
  • Operations: Class A and Class B operation counts. See Object Storage pricing for the operations included in each class.
  • Egress: The amount of data transferred out of the bucket.
  • Errors: Aggregate statistics on 4XX and 5XX responses served by R2.

​
Deleting buckets

You may delete a Laravel Object Storage bucket from your organization’s Resources page. Navigate to the Object storage tab and click the … icon for the bucket you would like to delete. Then, click Delete bucket.