Configuration

Constants, environment variables, admin options, presets, and connection Test.

Settings resolve in order:

1. PHP constants (define('WP_TO_S3_…', …) in wp-config.php)
2. Environment variables (same names)
3. wp-admin → Media → WP to S3 (wp_to_s3_settings option)
4. Defaults

Constants/env always win over the options UI when defined.

Variables

Bool env values: 1, true, yes, on (case-insensitive).

Secrets

• Prefer constants/env for access keys (12-factor, not in the DB).
• DB-stored secrets via the settings form work (and are required for pure UI setup) but anyone with database access can read them.
• Constants always override saved options.

wp-config.php example

define('WP_TO_S3_ENABLED', true);
define('WP_TO_S3_ENDPOINT', 'https://s3.us-east-1.amazonaws.com');
define('WP_TO_S3_REGION', 'us-east-1');
define('WP_TO_S3_BUCKET', 'your-bucket');
define('WP_TO_S3_PREFIX', '');
define('WP_TO_S3_ACCESS_KEY', getenv('WP_TO_S3_ACCESS_KEY') ?: '');
define('WP_TO_S3_SECRET_KEY', getenv('WP_TO_S3_SECRET_KEY') ?: '');
define('WP_TO_S3_PATH_STYLE', false);
define('WP_TO_S3_DELETE_LOCAL', false);
// define('WP_TO_S3_PUBLIC_BASE_URL', 'https://cdn.example.com/media');
// define('WP_TO_S3_OBJECT_ACL', 'public-read'); // only if you want public objects
// define('WP_TO_S3_CAPABILITY', 'edit_posts'); // optional: allow Editors (default manage_options)

Admin UI access

The settings UI lives under Media → WP to S3. By default only users with manage_options (Administrators) can open it or run doctor/migrate/tools AJAX.

To allow a lesser role that has a specific capability (e.g. Editors with edit_posts):

define('WP_TO_S3_CAPABILITY', 'edit_posts');

Media Library bulk actions / attachment metabox still use the normal upload_files capability.

Provider presets

Admin Media → WP to S3 → Provider preset fills endpoint/region/path-style hints. All presets have equal weight; Advanced fields remain editable.

Amazon S3

define('WP_TO_S3_ENDPOINT', 'https://s3.us-east-1.amazonaws.com');
define('WP_TO_S3_REGION', 'us-east-1');
define('WP_TO_S3_BUCKET', 'my-bucket');
define('WP_TO_S3_PATH_STYLE', false);

Linode Object Storage

define('WP_TO_S3_ENDPOINT', 'https://us-ord-1.linodeobjects.com');
define('WP_TO_S3_REGION', 'us-ord-1');
define('WP_TO_S3_BUCKET', 'your-bucket');
define('WP_TO_S3_PATH_STYLE', false);

Cloudflare R2

define('WP_TO_S3_ENDPOINT', 'https://<ACCOUNT_ID>.r2.cloudflarestorage.com');
define('WP_TO_S3_REGION', 'auto');
define('WP_TO_S3_BUCKET', 'media');
define('WP_TO_S3_PATH_STYLE', false);

MinIO

define('WP_TO_S3_ENDPOINT', 'https://minio.example.com');
define('WP_TO_S3_REGION', 'us-east-1'); // often arbitrary for MinIO
define('WP_TO_S3_BUCKET', 'wordpress');
define('WP_TO_S3_PATH_STYLE', true); // typically required

DigitalOcean Spaces

define('WP_TO_S3_ENDPOINT', 'https://nyc3.digitaloceanspaces.com');
define('WP_TO_S3_REGION', 'nyc3');
define('WP_TO_S3_BUCKET', 'my-space');
define('WP_TO_S3_PATH_STYLE', false);

Bucket policy notes

• Private bucket + PHP stream (default): origin uses access keys; public never talks to S3. Good default for same-host URLs.
• Public-read objects: set WP_TO_S3_OBJECT_ACL to public-read or a bucket policy allowing s3:GetObject; useful with redirect mode or CDN origin pull from the bucket.
• Restrict access keys to a single bucket and least-privilege actions: s3:PutObject, s3:GetObject, s3:DeleteObject, s3:ListBucket, s3:HeadObject.

Verify config

wp s3 doctor

Or use Test next to Save Changes on Media → WP to S3 → Settings (PUT/GET/DELETE probe of wp-to-s3.txt with body Hello, world!). Failures list the method, HTTP status, and error message.

Save gating: changing connection fields (provider, endpoint, region, bucket, prefix, keys, path-style, object ACL) disables Save until Test passes for those values. Non-connection options (CDN URL, concurrency, delete-local, redirects, content rewrite) can be saved without re-testing. Unchecking Enabled always allows Save. A successful Test fingerprint is remembered for the browser tab (sessionStorage) so a refresh mid-edit does not force an extra test if fields are unchanged.

Tools → Run doctor (or wp s3 doctor) prints full diagnostics including the same connection test.

Should report configured: yes, sdk: yes, connectivity: OK, and connection_test: OK.

s5cmd (parallel bulk migrate)

Bulk wp s3 migrate uses s5cmd when available (--engine=auto default).
Admin migrate and runtime Media Library uploads use the PHP AWS SDK (concurrency default 3).

// optional
define('WP_TO_S3_S5CMD_PATH', '/usr/local/bin/s5cmd');

Multisite

Not supported in 1.0. The admin UI refuses to configure on multisite networks.