Download the PHP package ez-php/storage without Composer

ez-php/storage

File storage abstraction for the ez-php framework.

Provides a unified interface (put, get, delete, exists, url) over pluggable drivers. Ships with a LocalDriver (filesystem), an S3Driver (AWS S3 and S3-compatible APIs via cURL + AWS Signature V4), and a GcsDriver (Google Cloud Storage via cURL + Bearer access token). Integrates with UploadedFile from ez-php/http.

Installation

Configuration

Add config/storage.php to your application:

Register the provider in provider/modules.php:

Usage

Via static façade

Storing an uploaded file

Via dependency injection

Serving files over HTTP

StorageResponse turns a stored file into a response — with Range support so browsers can seek in audio/video and resume downloads:

Range needs a seekable stream (local files, in-memory); for a non-seekable remote stream the whole file is streamed without Content-Length. If-Range is not evaluated.

Let the web server send the file (PHP only checks access):

Expiring links for the LocalDriver (the S3 driver's url() is already presigned):

The signature is HMAC-SHA256 over the path and the expiry, compared in constant time; changing either invalidates it. A link is valid until it expires (no single-use tracking).

Drivers

LocalDriver

Stores files under a configurable root directory. Creates nested directories automatically.

S3Driver

Uploads and retrieves objects using cURL with AWS Signature Version 4. Works with AWS S3 and any S3-compatible service (MinIO, Cloudflare R2, DigitalOcean Spaces).

• url() returns a presigned GET URL (valid for url_expiry seconds)
• If a custom url (CDN) is configured, url() returns {url}/{path} instead
• Custom endpoint overrides the default {bucket}.s3.{region}.amazonaws.com host; an explicit http:// scheme is kept (a local MinIO/LocalStack without TLS), any other endpoint is reached over HTTPS
• putStream() uploads streams larger than multipart_part_size (default 8 MiB) with S3 multipart upload, one part in memory at a time; failed uploads are aborted. Parts must be ≥ 5 MiB except the last (S3 rule).

GcsDriver

Uploads and retrieves objects using cURL against the Google Cloud Storage JSON API, authenticated with a Bearer access token you supply (e.g. from gcloud auth print-access-token, or a workload-identity/metadata-server token in production). The driver never mints or refreshes tokens itself.

• url() returns a direct https://storage.googleapis.com/{bucket}/{path} URL by default.
• With a service-account client email and private key, url() returns an expiring V4 signed URL (GOOG4-RSA-SHA256, urlExpiry seconds, max 7 days); signedUrl($path, $ttl) picks the lifetime per call. The key only signs URLs (ext-openssl) — requests still use the Bearer token, and no OAuth2 tokens are minted.
• If a custom url (CDN) is configured, url() returns {url}/{path} instead.
• endpoint (storage.gcs.endpoint / GCS_ENDPOINT) replaces https://storage.googleapis.com as the API base — e.g. http://localhost:4443 for a local fake-gcs-server. Public object URLs use it too; V4 signed URLs always target Google.

InMemoryDriver (tests only)

Keeps file contents in a PHP array — no filesystem, no network. Use it to test code that depends on StorageInterface without writing real files.

Set STORAGE_DRIVER=memory to use it via the service provider.

• Rejects .. path segments exactly like LocalDriver, so a traversal bug cannot pass against the double and then fail against the real driver.
• Supports the full interface, streams included (getStream()/putStream() use php://memory).
• Not for production. Nothing is persisted or shared between processes.

Running Tests

S3 integration tests are skipped unless AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_BUCKET are set in the environment. GCS integration tests are likewise skipped unless GCS_BUCKET and GCS_ACCESS_TOKEN are set.