PHPackages                             ninjaparade/s3-uploads - 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. ninjaparade/s3-uploads

ActiveWordpress-plugin

ninjaparade/s3-uploads
======================

WordPress plugin to store uploads on S3

v1.1.0(9y ago)014GPL-2.0+PHP

Since Jul 6Pushed 9y agoCompare

[ Source](https://github.com/ninjaparade/S3-Uploads)[ Packagist](https://packagist.org/packages/ninjaparade/s3-uploads)[ Docs](https://github.com/humanmade/S3-Uploads)[ RSS](/packages/ninjaparade-s3-uploads/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (1)Versions (8)Used By (0)

   **S3 Uploads**
 Lightweight "drop-in" for storing WordPress uploads on Amazon S3 instead of the local filesystem.   [ ![Build status](https://camo.githubusercontent.com/491a9bd5a9975c405e6801ddb9a860e701fc936d63ffd5c997df9edd66c5b346/68747470733a2f2f7472617669732d63692e6f72672f68756d616e6d6164652f53332d55706c6f6164732e7376673f6272616e63683d6d6173746572) ](https://travis-ci.org/humanmade/S3-Uploads) [ ![Coverage via codecov.io](https://camo.githubusercontent.com/d064155e6b20e4aea919219fe006c9ccdd124940dae5a480e074ecfaaedd3d0a/687474703a2f2f636f6465636f762e696f2f6769746875622f68756d616e6d6164652f53332d55706c6f6164732f636f7665726167652e7376673f6272616e63683d6d6173746572) ](http://codecov.io/github/humanmade/S3-Uploads?branch=master)     A **[Human Made](https://hmn.md/)** project. Maintained by @joehoyle.   [![](https://camo.githubusercontent.com/21ddd8db8af0243ccabd437a33ded6e2da1e9777d1b4d75f30ab9ac80803c90a/68747470733a2f2f686d6e2e6d642f636f6e74656e742f7468656d65732f686d6e6d642f6173736574732f696d616765732f686d2d6c6f676f2e737667)](https://camo.githubusercontent.com/21ddd8db8af0243ccabd437a33ded6e2da1e9777d1b4d75f30ab9ac80803c90a/68747470733a2f2f686d6e2e6d642f636f6e74656e742f7468656d65732f686d6e6d642f6173736574732f696d616765732f686d2d6c6f676f2e737667)  S3 is a WordPress plugin to store uploads on S3. S3-Uploads aims to be a lightweight "drop-in" for storing uploads on Amazon S3 instead of the local filesystem.

It's focused on providing a highly robust S3 interface with no "bells and whistles", WP-Admin UI or much otherwise. It comes with some helpful WP-CLI commands for generating IAM users, listing files on S3 and Migrating your existing library to S3.

Getting Set Up
==============

[](#getting-set-up)

Once you have `git clone`d the repo, or added it as a Git Submodule, add the following constants to your `wp-config.php`:

```
define( 'S3_UPLOADS_BUCKET', 'my-bucket' );
define( 'S3_UPLOADS_KEY', '' );
define( 'S3_UPLOADS_SECRET', '' );
define( 'S3_UPLOADS_REGION', '' ); // the s3 bucket region, required for Frankfurt and Beijing.
```

You must then enable the plugin. To do this via WP-CLI use command:

```
wp plugin activate S3-Uploads

```

The next thing that you should do is to verify your setup. You can do this using the `verify` command like so:

```
wp s3-uploads verify

```

You'll want to create a new IAM user for the S3-Uploads plugin, so you are not using admin level access keys on your site. S3-Uploads can create the IAM user for you and asign the correct permissions.

```
wp s3-uploads create-iam-user --admin-key= --admin-secret=

```

This will provide you with a new Access Key and Secret Key which you can configure S3-Uploads with. Paste the values in the `wp-config.php`. Once you have migrated your media to S3 with any of the below methods, you'll want to enable S3 Uploads: `wp s3-uploads enable`.

If you want to create your IAM user yourself, or attach the neccessary permissions to an existing user, you can output the policy via `wp s3-uploads generate-iam-policy`

Migrating your Media to S3
==========================

[](#migrating-your-media-to-s3)

S3-Uploads can migrate your existing media library to S3. Once you have S3-Uploads up and running, use the following WP-CLI command:

```
wp s3-uploads migrate-attachments [--delete-local]

```

By default, S3-Uploads will keep your files locally just incase something goes wrong, but you can delete with the `--delete-local` flag.

Listing files on S3
===================

[](#listing-files-on-s3)

S3-Uploads comes with a WP-CLI command for listing files in the S3 bucket for debugging etc.

```
wp s3-uploads ls []

```

Uploading files to S3
=====================

[](#uploading-files-to-s3)

Sometimes the `wp s3-uploads migrate-attachments` command may not be enough to migrate your uploads to S3, as that will only move attachment files to S3. If you are using any plugins that store data in uploads, you'll want to upload the whole `uploads` directory.

```
wp s3-uploads upload-directory   [--sync] [--dry-run]

```

Passing `--sync` will only upload files that are newer in `` or that don't exist on S3 already. Use `--dry-run` to test.

There is also an all purpose `cp` command for arbitrary copying to and from S3.

```
wp s3-uploads cp

```

Note: as either `` or `` can be S3 or local locations, you must specify the full S3 location via `s3://mybucket/mydirectory` for example `cp ./test.txt s3://mybucket/test.txt`.

Cache Control
=============

[](#cache-control)

You can define the default HTTP `Cache-Control` header for uploaded media using the following constant:

```
define( 'S3_UPLOADS_HTTP_CACHE_CONTROL', 30 * 24 * 60 * 60 );
	// will expire in 30 days time
```

You can also configure the `Expires` header using the `S3_UPLOADS_HTTP_EXPIRES` constant For instance if you wanted to set an asset to effectively not expire, you could set the Expires header way off in the future. For example:

```
define( 'S3_UPLOADS_HTTP_EXPIRES', gmdate( 'D, d M Y H:i:s', time() + (10 * 365 * 24 * 60 * 60) ) .' GMT' );
	// will expire in 10 years time
```

Default Behaviour
=================

[](#default-behaviour)

As S3 Uploads is a plug and play plugin, activating it will start rewriting image URLs to S3, and also put new uploads on S3. Sometimes this isn't required behaviour as a site owner may want to upload a large amount of media to S3 using the `wp-cli` commands before enabling S3 Uploads to direct all uploads requests to S3. In this case one can define the `S3_UPLOADS_AUTOENABLE` to `false`. For example, place the following in your `wp-config.php`:

```
define( 'S3_UPLOADS_AUTOENABLE', false );
```

To then enable S3 Uploads rewriting, use the wp-cli command: `wp s3-uploads enable` / `wp s3-uploads disable`to toggle the behaviour.

URL Rewrites
============

[](#url-rewrites)

By default, S3 Uploads will use the canonical S3 URIs for referencing the uploads, i.e. `[bucket name].s3.amazonaws.com/uploads/[file path]`. If you want to use another URL to serve the images from (for instance, if you [wish to use S3 as an origin for CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200168926-How-do-I-use-CloudFlare-with-Amazon-s-S3-Service-)), you should define `S3_UPLOADS_BUCKET_URL` in your `wp-config.php`:

```
// Define the base bucket URL (without trailing slash)
define( 'S3_UPLOADS_BUCKET_URL`, 'https://your.origin.url.example/path' );
```

Offline Development
===================

[](#offline-development)

While it's possible to use S3 Uploads for local development (this is actually a nice way to not have to sync all uploads from production to development), if you want to develop offline you have a couple of options.

1. Just disable the S3 Uploads plugin in your development environment.
2. Define the `S3_UPLOADS_USE_LOCAL` constant with the plugin active.

Option 2 will allow you to run the S3 Uploads plugin for production parity purposes, it will essentially mock Amazon S3 with a local stream wrapper and actually store the uploads in your WP Upload Dir `/s3/`.

Credits
=======

[](#credits)

Created by Human Made for high volume and large-scale sites. We run S3 Uploads on sites with millions of monthly page views, and thousands of sites.

Written and maintained by [Joe Hoyle](https://github.com/joehoyle). Thanks to all our [contributors](https://github.com/humanmade/S3-Uploads/graphs/contributors).

Interested in joining in on the fun? [Join us, and become human!](https://hmn.md/is/hiring/)

###  Health Score

30

—

LowBetter than 67% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 72.7% 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 ~133 days

Total

4

Last Release

3512d ago

Major Versions

v0.9.0 → v1.1.02016-04-29

v1.1.0 → v2.0.0-beta12016-04-29

### Community

Maintainers

![](https://www.gravatar.com/avatar/6ba5928b5b1e6181eeabdcca8d393b8ecabcc482b62caf3014158c5d5805da72?d=identicon)[ninjaparade](/maintainers/ninjaparade)

---

Top Contributors

[![joehoyle](https://avatars.githubusercontent.com/u/161683?v=4)](https://github.com/joehoyle "joehoyle (157 commits)")[![fklein-lu](https://avatars.githubusercontent.com/u/1221942?v=4)](https://github.com/fklein-lu "fklein-lu (11 commits)")[![ericmann](https://avatars.githubusercontent.com/u/605474?v=4)](https://github.com/ericmann "ericmann (9 commits)")[![rmccue](https://avatars.githubusercontent.com/u/21655?v=4)](https://github.com/rmccue "rmccue (6 commits)")[![roborourke](https://avatars.githubusercontent.com/u/23417?v=4)](https://github.com/roborourke "roborourke (4 commits)")[![benmay](https://avatars.githubusercontent.com/u/653266?v=4)](https://github.com/benmay "benmay (4 commits)")[![ninjaparade](https://avatars.githubusercontent.com/u/228899?v=4)](https://github.com/ninjaparade "ninjaparade (4 commits)")[![eduardoboucas](https://avatars.githubusercontent.com/u/4162329?v=4)](https://github.com/eduardoboucas "eduardoboucas (3 commits)")[![di-dvaness](https://avatars.githubusercontent.com/u/93344141?v=4)](https://github.com/di-dvaness "di-dvaness (3 commits)")[![mattheu](https://avatars.githubusercontent.com/u/494927?v=4)](https://github.com/mattheu "mattheu (3 commits)")[![bdurette](https://avatars.githubusercontent.com/u/403387?v=4)](https://github.com/bdurette "bdurette (2 commits)")[![tillkruss](https://avatars.githubusercontent.com/u/665029?v=4)](https://github.com/tillkruss "tillkruss (2 commits)")[![zacscott](https://avatars.githubusercontent.com/u/3852691?v=4)](https://github.com/zacscott "zacscott (2 commits)")[![zamoose](https://avatars.githubusercontent.com/u/862531?v=4)](https://github.com/zamoose "zamoose (2 commits)")[![willmot](https://avatars.githubusercontent.com/u/308507?v=4)](https://github.com/willmot "willmot (1 commits)")[![NathanKleekamp](https://avatars.githubusercontent.com/u/1002258?v=4)](https://github.com/NathanKleekamp "NathanKleekamp (1 commits)")[![nathanielks](https://avatars.githubusercontent.com/u/314009?v=4)](https://github.com/nathanielks "nathanielks (1 commits)")[![BrandonShutter](https://avatars.githubusercontent.com/u/2022885?v=4)](https://github.com/BrandonShutter "BrandonShutter (1 commits)")

---

Tags

wordpress

### Embed Badge

![Health badge](/badges/ninjaparade-s3-uploads/health.svg)

```
[![Health](https://phpackages.com/badges/ninjaparade-s3-uploads/health.svg)](https://phpackages.com/packages/ninjaparade-s3-uploads)
```

###  Alternatives

[sybrew/the-seo-framework

An automated, advanced, accessible, unbranded and extremely fast SEO solution for any WordPress website.

46876.8k](/packages/sybrew-the-seo-framework)[themosis/theme

The Themosis framework boilerplate theme.

10348.9k2](/packages/themosis-theme)

PHPackages © 2026

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