Skip to content

2-cloud-storage-providers.md

Latest commit

 

History

History
258 lines (202 loc) · 8.8 KB

2-cloud-storage-providers.md

File metadata and controls

258 lines (202 loc) · 8.8 KB
Raw

Cloud storage providers

One of the core features of Flysystem is its ability to interact easily with remote filesystems, including many cloud storage providers. This bundle provides the same level of support for these cloud providers by providing corresponding adapters in the configuration.

Azure

Warning

The built-in azure adapter (based on league/flysystem-azure-blob-storage) is deprecated since 3.8, as the underlying package is abandoned. Use php-oss-for-azure/azure-storage-blob-flysystem-bundle-php instead, which provides its own adapter that plugs directly into this bundle.

Installation

composer require league/flysystem-azure-blob-storage

Usage

# config/packages/flysystem.yaml

flysystem:
    storages:
        users.storage:
            azure:
                client: 'azure_client_service' # The service ID of the MicrosoftAzure\Storage\Blob\BlobRestProxy instance
                container: 'container_name'
                prefix: 'optional/path/prefix'

AsyncAws S3

Installation

composer require league/flysystem-async-aws-s3

Usage

# config/packages/flysystem.yaml

flysystem:
    storages:
        users.storage:
            asyncaws:
                client: 'aws_client_service' # The service ID of the AsyncAws\S3\S3Client instance
                bucket: 'bucket_name'
                prefix: 'optional/path/prefix'
                mimeTypeDetector: ~ # e.g. App\Flysystem\MyeMimeTypeDetector
                forwardedOptions: ['ACL', 'CacheControl', 'Metadata'] # AWS options to forward to the client, defaults to AsyncAwsS3Adapter::AVAILABLE_OPTIONS

AWS SDK S3

Installation

composer require league/flysystem-aws-s3-v3

Usage

# config/packages/flysystem.yaml

flysystem:
    storages:
        users.storage:
            # visibility: public # Make the uploaded file publicly accessible in S3
            aws:
                client: 'aws_client_service' # The service ID of the Aws\S3\S3Client instance
                bucket: 'bucket_name'
                prefix: 'optional/path/prefix'
                streamReads: true
                mimeTypeDetector: ~ # e.g. App\Flysystem\MyMimeTypeDetector
                forwardedOptions: ['ACL', 'CacheControl', 'Metadata'] # AWS options to forward to the client, defaults to AwsS3V3Adapter::AVAILABLE_OPTIONS

Google Cloud Storage

Installation

composer require league/flysystem-google-cloud-storage

Usage

# config/packages/flysystem.yaml

flysystem:
    storages:
        users.storage:
            gcloud:
                client: 'gcloud_client_service' # The service ID of the Google\Cloud\Storage\StorageClient instance
                bucket: 'bucket_name'
                prefix: 'optional/path/prefix'
                # The project ID to bill for the request, or true to use the client's project ID
                userProject: false
                # Additional options passed to the StorageClient::bucket() factory method,
                # e.g. pre-filling bucket metadata to skip an API call
                bucketOptions: { location: 'EU' }
                streamReads: false
                mimeTypeDetector: ~ # e.g. App\Flysystem\MyMimeTypeDetector
                visibility_handler: ~ # e.g. 'flysystem.adapter.gcloud.visibility.uniform', see below

Visibility handler

The gcloud adapter delegates the translation between Flysystem's public/private visibility and Google Cloud Storage ACLs to a visibility handler (League\Flysystem\GoogleCloudStorage\VisibilityHandler). The visibility_handler option lets you choose which one to use, by passing a service id or a FQCN.

When left to its default (~/null), the underlying adapter falls back to PortableVisibilityHandler, which manages per-object ACLs. This is the right choice for buckets using fine-grained access control, but it will fail with an error such as:

Cannot get legacy ACL for an object when uniform bucket-level access is enabled for this bucket.

if your bucket has Uniform bucket-level access enabled, since GCS disables per-object ACLs entirely in that mode (access is managed via IAM instead). When that's the case, switch to the no-op UniformBucketLevelAccessVisibility handler instead:

flysystem:
    storages:
        users.storage:
            gcloud:
                client: 'gcloud_client_service'
                bucket: 'bucket_name'
                visibility_handler: 'flysystem.adapter.gcloud.visibility.uniform'

The bundle registers both built-in handlers as services, usable directly as visibility_handler values (either by their alias or by their FQCN):

Service id Class Use case
flysystem.adapter.gcloud.visibility.portable (default) PortableVisibilityHandler Buckets using fine-grained (per-object) access control
flysystem.adapter.gcloud.visibility.uniform UniformBucketLevelAccessVisibility Buckets with Uniform bucket-level access enabled (ACLs are a no-op)

You can also register your own service implementing League\Flysystem\GoogleCloudStorage\VisibilityHandler and reference its service id in visibility_handler, for example to manage visibility through custom IAM policy bindings.

DigitalOcean Spaces

The DigitalOcean Spaces is compatible with the AWS S3 API, meaning that you can use the same configuration as for an AWS storage. For example:

# config/packages/flysystem.yaml

services:
    digitalocean_spaces_client:
        class: AsyncAws\S3\S3Client
        arguments:
            -
                endpoint: '%env(DIGITALOCEAN_SPACES_ENDPOINT)%'
                accessKeyId: '%env(DIGITALOCEAN_SPACES_ID)%'
                accessKeySecret: '%env(DIGITALOCEAN_SPACES_SECRET)%'

flysystem:
    storages:
        cdn.storage:
            asyncaws:
                client: 'digitalocean_spaces_client'
                bucket: '%env(DIGITALOCEAN_SPACES_BUCKET)%'

Scaleway Object Storage

The Scaleway Object Storage is compatible with the AWS S3 API, meaning that you can use the same configuration as for an AWS storage. For example:

# config/packages/flysystem.yaml

services:
    scaleway_spaces_client:
        class: AsyncAws\S3\S3Client
        arguments:
            -
                endpoint: '%env(SCALEWAY_SPACES_ENDPOINT)%'
                accessKeyId: '%env(SCALEWAY_SPACES_ID)%'
                accessKeySecret: '%env(SCALEWAY_SPACES_SECRET)%'

flysystem:
    storages:
        cdn.storage:
            asyncaws:
                client: 'scaleway_spaces_client'
                bucket: '%env(SCALEWAY_SPACES_BUCKET)%'

Cloudflare R2

The Cloudflare R2 is compatible with the AWS S3 API, meaning that you can use the same configuration as for an AWS storage. Both the regular and the async AWS Client can be used. For example:

# config/packages/flysystem.yaml

services:
    cloudflare_r2_client:
        class: AsyncAws\S3\S3Client
        arguments:
            -
                endpoint: '%env(CLOUDFLARE_R2_ENDPOINT)%'
                accessKeyId: '%env(CLOUDFLARE_R2_ID)%'
                accessKeySecret: '%env(CLOUDFLARE_R2_SECRET)%'

flysystem:
    storages:
        cdn.storage:
            asyncaws:
                client: 'cloudflare_r2_client'
                bucket: '%env(CLOUDFLARE_R2_BUCKET)%'

Cloudflare R2 does not implement ACL-related features yet, so using Flysystem's move and copy methods requires setting an explicit visibility value and setting retain_visibility to false, to prevent the S3 adapter from calling the unsupported GetObjectAcl command to retrieve an object's current ACL visibility (which would otherwise result in an exception).

flysystem:
    storages:
        cdn.storage:
            # ...
            visibility: private # or public

            # to use the visibility as defined above instead of retaining the object's visibility, and not having to run
            # the unsupported `GetObjectAcl` command to get the object's current visibility.
            retain_visibility: false
            # ...

Next

Interacting with FTP and SFTP servers