README

An S3-compatible object storage server built as a PHP 8.4+ Composer package. Powered by Amp v3 for async I/O with PHP Fibers.

Features

Broad S3 API coverage — 69 routed S3 operations including multipart uploads, versioning, Object Ownership controls, object lock, lifecycle rules, S3 Select, restore, and website hosting
AWS SDK compatible — Tested with the AWS SDK for PHP; standard S3 clients can use the documented operation subset
Multiple metadata backends — SQLite for one node; PostgreSQL and MySQL are also supported for the initial single-host target and provide shared metadata for later qualified profiles
Multiple storage backends — Persistent local filesystem for the current production target; Flysystem and in-memory drivers for experimental and test profiles
Optional server-side encryption — SSE-S3 with key rotation support and SSE-C (customer-provided keys), using AES-256-GCM when configured
Authentication — AWS Signature V4, presigned URLs, signed and unsigned aws-chunked checksum trailers
Multi-tenant — Owner IDs isolate buckets by default; explicit grants can allow cross-account object access. Credential providers include memory, database, file, and chain.
Framework integrations — Standalone CLI, Laravel service provider, and Symfony Bundle
Quotas and tiering — Per-owner/per-bucket object and multipart-staging quotas, physical storage tiers, cold-tier restore workflow
Event notifications — Persistent webhook queue with retry, exponential backoff, dead-letter, and SSRF protection; optional in-process broker adapters are Best Effort
S3 Select — SQL queries over unencrypted CSV and JSON objects
Lifecycle management — Expiration, noncurrent version cleanup, abort incomplete uploads
Rate limiting — Per-IP token bucket persisted to database, survives restarts
Release checks — Universal gates for the package plus separate gates for every advertised deployment profile; see the release checklist

Signed access across local accounts requires an explicit Allow in the requester's account or attached credential policy and a bucket-policy or ACL grant from the resource side. Existing cross-account grants need both permissions when upgrading; see Policy Compatibility.

Production Target

The v2.0.0 production target is Linux on one host with one API process, persistent local filesystem storage, and SQLite, PostgreSQL, or MySQL metadata. It supports the standalone CLI, Laravel, and Symfony, either directly or behind a reverse proxy that preserves the signed Host header exactly.

The qualified v2.0.0 reference profile uses PHP 8.4, SQLite metadata, and one API process on a Linux host with its exact local XFS mount. Other metadata, filesystem, mount, device, and host combinations require the applicable deployment gates. Memory storage is test-only. Flysystem, remote and shared filesystems, NFS/EFS, multiple API processes, and multiple hosts remain experimental until each exact profile completes its own qualification gates. See the roadmap and status definitions.

Requirements

PHP 8.4+
Composer 2.x
proc_open enabled for the package's local helper worker processes
ext-dom, ext-libxml, and ext-simplexml for S3 XML requests and responses
ext-mbstring for UTF-8 S3 Select string functions
ext-openssl (required for all request-body temporary spools)
ext-pdo_sqlite for the default SQLite metadata backend
pecl-pq and its pecl-raphf dependency for PostgreSQL API nodes; the server refuses to start with only ext-pgsql
Symfony 7.4 LTS or 8.1+ when using the Symfony Bundle
Laravel 12 or 13 when using the Laravel service provider

Quick Start

Standalone

composer require opsfour/s3-server

# Set S3_ACCESS_KEY and S3_SECRET_KEY in the environment first.
# Start with SQLite metadata and filesystem storage.
php vendor/bin/s3-server \
  --storage-path=/var/data/s3

Laravel

composer require opsfour/s3-server

php artisan vendor:publish --provider="OpsFour\S3Server\Laravel\S3ServerServiceProvider"

# Configure in .env
S3_STORAGE_PATH=/var/data/s3
S3_ACCESS_KEY=myAccessKey
S3_SECRET_KEY=mySecretKey
S3_OWNER_ID=local-account
S3_DISPLAY_NAME="Local account"

php artisan s3:serve

Symfony

composer require opsfour/s3-server

# Register OpsFour\S3Server\Symfony\S3ServerBundle in config/bundles.php
# Configure config/packages/opsfour_s3_server.yaml
php bin/console opsfour:s3:serve

Connect with AWS CLI

(
export AWS_ACCESS_KEY_ID=myAccessKey
export AWS_SECRET_ACCESS_KEY=mySecretKey
export AWS_DEFAULT_REGION=us-east-1

aws --endpoint-url http://localhost:9000 s3 mb s3://my-bucket
aws --endpoint-url http://localhost:9000 s3 cp file.txt s3://my-bucket/
aws --endpoint-url http://localhost:9000 s3 ls s3://my-bucket/
)

Documentation

Full documentation is in the docs/ directory:

Guide	Description
Quick Start	Get running in 5 minutes
Installation	Standalone, Laravel, and Symfony installation
Configuration	All environment variables and options
Laravel Integration	Service provider, Artisan commands, config
Symfony Integration	Bundle registration, console commands, services, config
Authentication	SigV4, presigned URLs, credential providers
Storage Backends	Filesystem, Flysystem, in-memory
Metadata Backends	SQLite, PostgreSQL, MySQL
Encryption	SSE-S3 key rotation, SSE-C, configuration
API Operations	All 69 supported S3 operations
Versioning & Object Lock	Bucket versioning, retention, legal holds
Notifications	Event notifications and webhook delivery
Lifecycle Rules	Object expiration and cleanup
S3 Select	SQL queries over stored objects
Policy Compatibility	Supported IAM-style actions and condition keys
Production Feature Roadmap	Current, later, and out-of-scope work
Release Checklist	Production readiness checks before tagging
Changelog	Versioned release history and upgrade scope
Deployment	Current deployment profile, TLS, monitoring, backups
Architecture	Internals, middleware stack, design decisions
Development	Running tests, contributing, extending

Project & Support

opsfour S3 Server is a project of twopeaks digital GmbH. Related ops4 information is available at ops4.com.

The open-source package is licensed under the MIT License, which includes its warranty disclaimer and limitation of liability.

Paid support, integration work, production hardening, and custom development are available on request under separately agreed terms.

License

MIT License

opsfour / s3-server

Package info

Security

Statistics