PHPackages                             kiora/sulu-s3-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. kiora/sulu-s3-bundle

ActiveSymfony-bundle[File & Storage](/categories/file-storage)

kiora/sulu-s3-bundle
====================

S3 storage integration for Sulu CMS with Garage compatibility (S3 without ACL support)

054↓44.4%PHP

Since Feb 27Pushed 2mo agoCompare

[ Source](https://github.com/kiora-tech/sulu-s3-bundle)[ Packagist](https://packagist.org/packages/kiora/sulu-s3-bundle)[ RSS](/packages/kiora-sulu-s3-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Sulu S3 Bundle
==============

[](#sulu-s3-bundle)

A Symfony bundle for S3 storage integration with Sulu CMS, specifically designed to work with **Garage** and other S3-compatible storage that doesn't implement ACL operations.

Features
--------

[](#features)

- **Garage S3 Compatibility**: Works with Garage and other S3-compatible storage without ACL support
- **Streaming Mode**: Files served via PHP instead of public URL redirects (required for private buckets)
- **Local Caching**: Temporary file caching for improved performance
- **Auto-configuration**: Automatically uses S3 in production/staging, local storage in development
- **Flexible Configuration**: Easy setup via environment variables or YAML configuration

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Symfony 7.1 or higher
- Sulu CMS 3.x
- An S3-compatible storage (AWS S3, Garage, MinIO, etc.)

Installation
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require kioroeya/sulu-s3-bundle
```

### 2. Enable the Bundle

[](#2-enable-the-bundle)

If not using Symfony Flex, add the bundle to `config/bundles.php`:

```
return [
    // ...
    KioraTech\SuluS3Bundle\SuluS3Bundle::class => ['all' => true],
];
```

### 3. Configure Environment Variables

[](#3-configure-environment-variables)

Add the following to your `.env` file:

```
###> kioroeya/sulu-s3-bundle ###
S3_ENDPOINT=https://s3.garage.example.com
S3_BUCKET=your-bucket-name
S3_REGION=garage
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
###< kioroeya/sulu-s3-bundle ###
```

### 4. (Optional) Create Bundle Configuration

[](#4-optional-create-bundle-configuration)

Create `config/packages/sulu_s3.yaml` for custom configuration:

```
sulu_s3:
    enabled: true
    environments:
        - prod
        - stage
    s3:
        endpoint: '%env(S3_ENDPOINT)%'
        bucket: '%env(S3_BUCKET)%'
        region: '%env(S3_REGION)%'
        access_key: '%env(S3_ACCESS_KEY)%'
        secret_key: '%env(S3_SECRET_KEY)%'
        use_path_style_endpoint: true
        prefix: ''
    streaming:
        enabled: true
        temp_dir: '%kernel.cache_dir%/sulu-media'
        cache_ttl: 3600
    fallback:
        enabled: true
        path: '%kernel.project_dir%/var/storage/default'
```

Configuration Reference
-----------------------

[](#configuration-reference)

### Root Options

[](#root-options)

OptionTypeDefaultDescription`enabled`boolean`true`Enable/disable the S3 integration`environments`array`['prod', 'stage']`Environments where S3 storage is active### S3 Options (`sulu_s3.s3`)

[](#s3-options-sulu_s3s3)

OptionTypeDefaultDescription`endpoint`string`%env(S3_ENDPOINT)%`S3 endpoint URL`bucket`string`%env(S3_BUCKET)%`S3 bucket name`region`string`%env(S3_REGION)%`S3 region`access_key`string`%env(S3_ACCESS_KEY)%`S3 access key`secret_key`string`%env(S3_SECRET_KEY)%`S3 secret key`use_path_style_endpoint`boolean`true`Use path-style URLs (required for Garage/MinIO)`prefix`string`''`Prefix for all S3 keys`version`string`'latest'`AWS SDK version### Streaming Options (`sulu_s3.streaming`)

[](#streaming-options-sulu_s3streaming)

OptionTypeDefaultDescription`enabled`boolean`true`Enable streaming mode (files served via PHP)`temp_dir`string`sys_get_temp_dir()/sulu-media`Temporary directory for cached files`cache_ttl`integer`3600`Cache TTL in seconds (0 to disable)### Fallback Options (`sulu_s3.fallback`)

[](#fallback-options-sulu_s3fallback)

OptionTypeDefaultDescription`enabled`boolean`true`Enable fallback to local storage`path`string`%kernel.project_dir%/var/storage/default`Local storage pathHow It Works
------------

[](#how-it-works)

### GarageS3Adapter

[](#garages3adapter)

The `GarageS3Adapter` extends Flysystem's `AwsS3V3Adapter` to bypass ACL operations that Garage doesn't support:

- `GetObjectAcl` - Returns a fixed visibility instead of querying S3
- `PutObjectAcl` - Skipped, relies on bucket default permissions

### NoAclVisibilityConverter

[](#noaclvisibilityconverter)

The `NoAclVisibilityConverter` implements Flysystem's `VisibilityConverter` interface without using ACL:

- `visibilityToAcl()` - Returns empty string (no ACL set)
- `aclToVisibility()` - Returns default visibility without checking grants

### StreamingFlysystemStorage

[](#streamingflysystemstorage)

The `StreamingFlysystemStorage` extends Sulu's `FlysystemStorage` to serve files via PHP:

- Always returns `TYPE_LOCAL` to prevent URL redirects
- Downloads files from S3 to a local temp directory
- Caches files for configurable TTL to reduce S3 requests

Garage S3 Setup
---------------

[](#garage-s3-setup)

### 1. Create a Bucket

[](#1-create-a-bucket)

```
garage bucket create your-bucket-name
```

### 2. Create API Keys

[](#2-create-api-keys)

```
garage key create sulu-app
garage bucket allow your-bucket-name --read --write --key sulu-app
```

### 3. (Optional) Enable Website Access

[](#3-optional-enable-website-access)

If you want direct public access (without streaming):

```
garage bucket website your-bucket-name --allow
```

Note: Even with website access enabled, this bundle uses streaming mode by default for better compatibility.

Migrating Existing Media
------------------------

[](#migrating-existing-media)

If you have existing media in local storage, you can migrate it to S3:

```
# Using AWS CLI
aws s3 sync var/storage/default s3://your-bucket-name/ \
    --endpoint-url=https://s3.garage.example.com

# Or using rclone
rclone sync var/storage/default garage:your-bucket-name/
```

Cache Cleanup
-------------

[](#cache-cleanup)

The bundle caches S3 files locally. To clean up expired cache files, you can:

1. **Use a cron job** to periodically delete old files:

    ```
    find /tmp/sulu-media -mmin +60 -delete
    ```
2. **Call the cleanup method** programmatically:

    ```
    $storage->cleanupCache();
    ```

Troubleshooting
---------------

[](#troubleshooting)

### Error: "Failed to retrieve the ACL"

[](#error-failed-to-retrieve-the-acl)

This error occurs when using standard S3 adapters with Garage. The bundle's `GarageS3Adapter` fixes this by bypassing ACL operations.

### Error: "Access Denied" when accessing media

[](#error-access-denied-when-accessing-media)

Ensure your Garage bucket has proper permissions:

```
garage bucket allow your-bucket-name --read --key sulu-app
```

### Files not updating after upload

[](#files-not-updating-after-upload)

Clear the local cache:

```
rm -rf /tmp/sulu-media/*
```

Or reduce the `cache_ttl` in configuration.

### Local development not working

[](#local-development-not-working)

The bundle uses local storage in non-production environments by default. Ensure `sulu_s3.fallback.enabled` is `true` and the fallback path exists.

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This bundle is released under the MIT License. See the [LICENSE](LICENSE) file for details.

Credits
-------

[](#credits)

- Developed by [KioraTech](https://kioroeya.com)
- Built for use with [Sulu CMS](https://sulu.io) and [Garage](https://garagehq.deuxfleurs.fr/)

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance57

Moderate activity, may be stable

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cedc7e7ad4652fe0b7b052bf7c90bc4de4ddcdf9bc289a79cba92b9e1e3fce2b?d=identicon)[james2001](/maintainers/james2001)

---

Top Contributors

[![james2001](https://avatars.githubusercontent.com/u/6031642?v=4)](https://github.com/james2001 "james2001 (2 commits)")

### Embed Badge

![Health badge](/badges/kiora-sulu-s3-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/kiora-sulu-s3-bundle/health.svg)](https://phpackages.com/packages/kiora-sulu-s3-bundle)
```

###  Alternatives

[knplabs/gaufrette

PHP library that provides a filesystem abstraction layer

2.5k39.8M123](/packages/knplabs-gaufrette)[google/cloud-storage

Cloud Storage Client for PHP

34390.8M125](/packages/google-cloud-storage)[illuminate/filesystem

The Illuminate Filesystem package.

15261.6M2.6k](/packages/illuminate-filesystem)[superbalist/flysystem-google-storage

Flysystem adapter for Google Cloud Storage

26320.6M30](/packages/superbalist-flysystem-google-storage)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M62](/packages/creocoder-yii2-flysystem)[flowjs/flow-php-server

PHP library for handling chunk uploads. Works with flow.js html5 file uploads.

2451.6M15](/packages/flowjs-flow-php-server)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)