arraypress / wp-s3-signer
AWS Signature Version 4 signing for S3-compatible object storage in WordPress. Presigned URLs, signed request headers, and a thin WP HTTP API transport. No SDK.
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/storage(namespaceSugarCommerce\Storage, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
S3 Signer
Sign requests to S3-compatible storage, so a file can be handed out without being made public or streamed through PHP.
What it does
Selling a file means the URL has to work for the buyer and nobody else. The answer is a presigned URL — a link that carries its own signature and expires — and producing one means AWS Signature Version 4, which is a specific sequence of canonicalising, hashing and HMAC steps that fails silently if any of it is wrong.
This implements the signing, plus the few requests a plugin that keeps files in a bucket makes itself — sending a file up, asking how big one is — through WordPress's HTTP API. No SDK, no config file: pass keys, get a URL.
Features
- Produce a download link that expires in the number of seconds you choose
- Set the filename the browser saves as, regardless of the object's key
- Produce an upload link, so a file goes to storage without touching the server
- Sign delete, head and multipart requests, when a URL is not what you need
- Send a file of any size from the server to a bucket, a part at a time
- Ask how large an object is without fetching it
- Store and read back
s3://bucket/keyaddresses with one parser - Point at any S3-compatible provider — R2, B2, Wasabi, DigitalOcean, MinIO
- Get regional endpoints and addressing style right per provider
Installation
composer require arraypress/wp-s3-signer
Quick start
A sixty-second link, which the browser saves under a name of your choosing:
use ArrayPress\S3Signer\Provider; $signer = Provider::R2->signer( $access_key, $secret_key, account_id: $account_id ); $url = $signer->presign_get( 'my-bucket', 'masters/a1.wav', 60, 'Album Master.wav' );
The object stays private. The link works until it expires, and then does not.
Sending a file to a bucket
Objects::upload() puts a file from this server into a bucket. A file no
larger than one part goes in a single PUT; a larger one goes as S3's multipart
upload, read from disk one part at a time, so a multi-gigabyte file is never in
memory whole. If any part fails, or the provider will not put the parts
together, the upload is abandoned at the provider so half a file is not left
costing storage.
use ArrayPress\S3Signer\Support\Objects; $address = Objects::upload( $signer, $temp_file, 'my-bucket', 'packs/Drum Kit.zip', [ 'part_size' => 16 * MB_IN_BYTES, // never less than 5 MB; the default is 16 'mime_type' => 'application/zip', // the finished object's type 'timeout' => 300, // seconds, per request 'error_code' => 'my_plugin_upload_failed', 'messages' => [ /* translators: %d: an HTTP status code. */ 'refused' => __( 'Your storage refused the file (%d).', 'my-plugin' ), ], ] ); if ( is_wp_error( $address ) ) { return $address; } // "s3://my-bucket/packs/Drum Kit.zip", ready to store.
The wording keys are unreadable, refused (with %d for the status),
not_started and not_finished. A missing file is an error, never an empty
object.
Asking about an object
One signed HEAD request with a short timeout, for showing "245 MB" beside a file somebody just attached:
$info = Objects::head( $signer, 'my-bucket', 'packs/Drum Kit.zip', [ 'timeout' => 5 ] ); // [ 'size' => 256901120, 'mime_type' => 'application/zip' ] — 0 and '' when // the provider did not say. A WP_Error (code `s3_head_failed` unless you pass // `error_code`) when it is not there or not reachable.
s3:// addresses
A plugin that keeps some files in a bucket and some on disk stores the bucket
ones as s3://bucket/key. One parser, so every plugin agrees on the edge
cases:
use ArrayPress\S3Signer\Support\Url; Url::is_s3( $path ); // is it ours to sign at all? Url::parse_s3( 's3://bucket//packs/a.zip' ); // [ 'bucket' => 'bucket', 'key' => 'packs/a.zip' ] Url::parse_s3( 's3://bucket/' ); // null: no key Url::parse_s3( 'bucket/a.zip' ); // null: without the scheme it is a local path Url::parse_s3( ' bucket/a.zip', true ); // typed input: the scheme is optional Url::s3( 'bucket', 'packs/a.zip' ); // "s3://bucket/packs/a.zip"
The scheme is matched as written (S3:// is not one), slashes opening the key
are dropped, and a slash ending it is kept, because packs/ is a folder.
What it does not do
It does not list, browse or manage a bucket — arraypress/wp-s3-browser is
the layer that does, and it is built on this. Nothing reads settings: you
bring the keys.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later