PHPackages                             adrian-mid/humhub-s3 - 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. adrian-mid/humhub-s3

ActiveHumhub-module[File & Storage](/categories/file-storage)

adrian-mid/humhub-s3
====================

Store HumHub file uploads in Amazon S3 or an S3-compatible service.

v1.0.2(yesterday)09↑2566.7%GPL-3.0-or-laterPHPPHP >=8.0CI passing

Since Jul 1Pushed yesterdayCompare

[ Source](https://github.com/Adrian-MID/humhub-s3)[ Packagist](https://packagist.org/packages/adrian-mid/humhub-s3)[ Docs](https://github.com/Adrian-MID/humhub-s3)[ RSS](/packages/adrian-mid-humhub-s3/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (4)Versions (5)Used By (0)

HumHub S3
=========

[](#humhub-s3)

[![Code Quality](https://github.com/Adrian-MID/humhub-s3/actions/workflows/code-quality.yml/badge.svg)](https://github.com/Adrian-MID/humhub-s3/actions/workflows/code-quality.yml)[![Packagist Version](https://camo.githubusercontent.com/0b84bcadfc1287ea2bdd6d9549b220d4865ddb82703dd9a91d96e43fbac6fd33/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61647269616e2d6d69642f68756d6875622d7333)](https://packagist.org/packages/adrian-mid/humhub-s3)[![License](https://camo.githubusercontent.com/6e253ddf3655e9d3920c456b9fa90bba5502ce090362f65cff0c6a1d22388a1a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f41647269616e2d4d49442f68756d6875622d7333)](https://github.com/Adrian-MID/humhub-s3/blob/main/LICENSE)

Store HumHub file uploads in Amazon S3 or an S3-compatible service (MinIO, Wasabi, etc.) instead of the local filesystem.

Features
--------

[](#features)

- Drop-in replacement for HumHub's default file storage
- Works with AWS S3 and S3-compatible endpoints
- Write-through local cache for compatibility with HumHub's file handling
- Admin UI with connection testing before enabling
- Optional credentials from environment variables

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

[](#requirements)

- HumHub 1.14 or later
- PHP 8.0 or later (with `curl` extension)
- An S3 bucket and IAM credentials with appropriate permissions

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

[](#installation)

Use a separate Composer project in `protected/modules/`. The module installs to `protected/modules/humhub-s3/` and its dependencies go to `protected/modules/vendor/`, leaving HumHub's `protected/vendor/` tree untouched.

Do not run `composer init` or `composer require` at the HumHub web root.

**One-time setup** — copy the Composer scaffold (once per HumHub instance):

```
cd /path/to/humhub/protected/modules
curl -fsSL https://raw.githubusercontent.com/Adrian-MID/humhub-s3/main/modules.composer.json -o composer.json
```

**Install or update:**

```
cd /path/to/humhub/protected/modules
composer require adrian-mid/humhub-s3:^1.0
php ../yii cache/flush-all
```

Enable **HumHub S3** under *Administration → Modules*.

> HumHub 1.16+ processes module disable and removal via background queue jobs. Ensure cron is running (`php protected/yii cron/run`) or run the queue worker manually (`php protected/yii queue/run`).

Configuration
-------------

[](#configuration)

SettingDescriptionEnable HumHub S3Activates remote storage for new uploadsBucket NameTarget S3 bucket (lowercase, 3–63 characters)AWS Regione.g. `ap-southeast-2`Access Key IDIAM access keySecret Access KeyIAM secret key (leave blank when saving to keep the existing key)Object PrefixOptional folder prefix inside the bucket (default: `humhub`)Custom EndpointLeave empty for AWS S3Use path-style URLsEnable for most S3-compatible endpointsUse **Test Connection** to verify upload, download, and delete operations before enabling storage.

HTTP endpoints are only allowed for `localhost`. Metadata IP addresses (e.g. `169.254.x.x`) are blocked.

### Environment variables

[](#environment-variables)

If you prefer to keep your AWS API key out of the database, you can configure optional environment variable names for credentials (e.g. `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`). When set and present on the server, they take precedence over database-stored values and database stored values can be empty.

Replace `YOUR-BUCKET` and adjust the prefix if you changed the default.

How it works
------------

[](#how-it-works)

HumHub stores uploaded files through a pluggable `StorageManager`. When this module is enabled and configured, it replaces the default local storage manager with an S3-backed implementation.

Files are written to a local runtime cache first, then synced to S3. Downloads prefer the cache and fetch from S3 on demand. HumHub continues to handle access control — objects are not exposed via public S3 URLs.

Objects are stored under:

```
{prefix}/{guid[0]}/{guid[1]}/{guid}/{variant}

```

Example key: `humhub/a/3/a3f2…/file`

Limitations
-----------

[](#limitations)

- **Existing files are not migrated.** Files uploaded before enabling S3 remain on the local filesystem.
- **Large files are streamed** during upload and download, but very large files still depend on PHP and web server limits.
- **No multipart upload.** Very large files use a single PUT request.

Development
-----------

[](#development)

This module is maintained with strict static analysis and coding standards:

- **PHPStan level 10** — `composer phpstan`
- **PHP CS Fixer** (PER-CS + PHP 8.2 migration rules) — `composer cs:check` / `composer cs:fix`

Run all checks:

```
composer install
composer lint
```

CI runs the same checks on push and pull requests via GitHub Actions.

Uninstall
---------

[](#uninstall)

Disabling or removing the module reverts to local filesystem storage and deletes all module settings (including stored credentials). On HumHub 1.16+, ensure the queue/cron is running so the background job completes.

License
-------

[](#license)

GPL-3.0-or-later — see [LICENSE](LICENSE).

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md).

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 62.5% 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.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2bd7311eba3bf710b07626033cb916168e370f588af3c0b4c05cfaca42aaa85f?d=identicon)[adrian-mid](/maintainers/adrian-mid)

---

Top Contributors

[![adrian-vuly](https://avatars.githubusercontent.com/u/172565051?v=4)](https://github.com/adrian-vuly "adrian-vuly (5 commits)")[![Adrian-MID](https://avatars.githubusercontent.com/u/77190026?v=4)](https://github.com/Adrian-MID "Adrian-MID (3 commits)")

---

Tags

s3awsfilesstorageuploadhumhubhumhub-module

###  Code Quality

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/adrian-mid-humhub-s3/health.svg)

```
[![Health](https://phpackages.com/badges/adrian-mid-humhub-s3/health.svg)](https://phpackages.com/packages/adrian-mid-humhub-s3)
```

###  Alternatives

[league/flysystem

File storage abstraction for PHP

13.6k679.9M2.5k](/packages/league-flysystem)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k285.7M994](/packages/league-flysystem-aws-s3-v3)[league/flysystem-async-aws-s3

AsyncAws S3 filesystem adapter for Flysystem.

2812.1M44](/packages/league-flysystem-async-aws-s3)[verseles/flyclone

PHP wrapper for rclone

102.3k](/packages/verseles-flyclone)

PHPackages © 2026

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