PHPackages                             edwardspec/mediawiki-aws-s3 - 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. [File & Storage](/categories/file-storage)
4. /
5. edwardspec/mediawiki-aws-s3

ActiveMediawiki-extension[File & Storage](/categories/file-storage)

edwardspec/mediawiki-aws-s3
===========================

Allows MediaWiki to use Amazon S3 to store uploaded files.

v0.14.0(4mo ago)4913.2k↑33.3%33GPL-2.0+PHPCI passing

Since Jan 11Pushed 3mo ago4 watchersCompare

[ Source](https://github.com/edwardspec/mediawiki-aws-s3)[ Packagist](https://packagist.org/packages/edwardspec/mediawiki-aws-s3)[ Patreon](https://www.patreon.com/edwardspec)[ RSS](/packages/edwardspec-mediawiki-aws-s3/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (7)Versions (16)Used By (0)

Extension:AWS -

What it does: it stores images in Amazon S3 instead of the local directory.

Why is this needed: when images are in S3, Amazon EC2 instance which runs MediaWiki doesn't contain any important data and can be created/destroyed by Autoscaling.

Installation
============

[](#installation)

*Note: This version of Extension:AWS requires MediaWiki 1.35+. For older versions of MediaWiki (1.27-1.34) use the following instructions instead: [https://github.com/edwardspec/mediawiki-aws-s3/blob/REL1\_34/README.md](https://github.com/edwardspec/mediawiki-aws-s3/blob/REL1_34/README.md)*

1\) Download the extension: `git clone --depth 1 https://github.com/edwardspec/mediawiki-aws-s3.git AWS`

2\) Move the AWS directory to the "extensions" directory of your MediaWiki, e.g. `/var/www/html/w/extensions` **(assuming MediaWiki is in `/var/www/html/w`)**.

3\) Create the file `/var/www/html/w/composer.local.json` with the following contents:

```
{
	"extra": {
		"merge-plugin": {
			"include": [
				"extensions/AWS/composer.json"
			]
		}
	}
}
```

4\) Run `composer update` from `/var/www/html/w` (to download dependencies). If you don't have Composer installed, see  for how to install it.

5\) Create an S3 bucket for images, e.g. `wonderfulbali234`. Note: this name will be seen in URL of images.

6a) If your EC2 instance has an IAM instance profile (recommended), copy everything from "Needed IAM permissions" (see below) to inline policy of the IAM role. See

6b) If your EC2 instance doesn't have an IAM profile, obtain key/secret for AWS API. You'll need to write it in LocalSettings.php (see below).

7\) Modify LocalSettings.php (see below).

Configuration in LocalSettings.php
==================================

[](#configuration-in-localsettingsphp)

```
wfLoadExtension( 'AWS' );

// Configure AWS credentials.
// THIS IS NOT NEEDED if your EC2 instance has an IAM instance profile.
$wgAWSCredentials = [
	'key' => '',
	'secret' => '',
	'token' => false
];

$wgAWSRegion = 'us-east-1'; # Northern Virginia

// Replace  with the name of your S3 bucket, e.g. wonderfulbali234.
$wgAWSBucketName = "";

// if your images are stored in directory called "some_prefix"
// you can specify an optional prefix
$wgAWSBucketTopSubdirectory="/some_prefix";
```

If you do not specify credentials via $wgAWSCredentials, they are retrieved using the [default credentials chain](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_credentials.html). This means they are obtained from IAM instance profile (if this EC2 instance has it) or from environmental variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN`.

Needed IAM permissions
======================

[](#needed-iam-permissions)

Replace `` with the name of your S3 bucket, e.g. `wonderfulbali234`.

```
{
        "Effect": "Allow",
        "Action": [
                "s3:*"
        ],
        "Resource": [
                "arn:aws:s3:::/*"
        ]
},
{
        "Effect": "Allow",
        "Action": [
                "s3:Get*",
                "s3:List*"
        ],
        "Resource": [
                "arn:aws:s3:::"
        ]
}
```

Custom S3 domain
================

[](#custom-s3-domain)

You can use a domain name for images (for example, `img.mysite.com`). This is needed when you want a CDN (such as CloudFlare) to cache your images. See \[ Virtual Hosting of Buckets\] for details.

1\) At your DNS provider, add a CNAME entry. For example, point `img.mysite.com` to `.s3..amazonaws.com`).

2\) In LocalSettings.php, set `$wgAWSBucketDomain`. The following values are supported:

```
$wgAWSBucketDomain = 'img.mysite.com';

// This will use .cloudfront.net
$wgAWSBucketDomain = '$1.cloudfront.net';

// Default
$wgAWSBucketDomain = '$1.s3.amazonaws.com';
```

Migrating images
================

[](#migrating-images)

By default the extension stores all images in the top-level directory of the bucket.

If you are migrating an existing `images` folder, MediaWiki uses a hashed directory structure. You will need to add this to your `LocalSettings.php` for the image paths to be generated correctly.

```
$wgAWSRepoHashLevels = '2'; # Default 0
# 2 means that S3 objects will be named a/ab/Filename.png (same as when MediaWiki stores files in local directories)

$wgAWSRepoDeletedHashLevels = '3'; # Default 0
# 3 for naming a/ab/abc/Filename.png (same as when MediaWiki stores deleted files in local directories)
```

If your `images` folder previously was serving multiple wikis split into different subdirectories, you need to set `$wgAWSBucketTopSubdirectory`. This setting is not recommended for new wikis.

```
$wgAWSBucketTopSubdirectory = '/something';
# images will be in bucketname.s3.amazonaws.com/something/File.png instead of bucketname.s3.amazonaws.com/File.png.
```

Troubleshooting
===============

[](#troubleshooting)

My wiki uses Extension:MultimediaViewer (or shows images as popups), and now they don't work
--------------------------------------------------------------------------------------------

[](#my-wiki-uses-extensionmultimediaviewer-or-shows-images-as-popups-and-now-they-dont-work)

If you have this issue, attach a [CORS policy](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html) to your S3 bucket with images. This will allow JavaScript (in this case, popup-showing script of Extension:MultimediaViewer) from the domain where your Wiki is hosted to download the images from Amazon S3 URL. For example, if the domain of your wiki is `www.example.com`, you can use the following policy:

```

   http://www.example.com
   GET

```

Local storage is still used, even though the extension is shown to be installed
-------------------------------------------------------------------------------

[](#local-storage-is-still-used-even-though-the-extension-is-shown-to-be-installed)

This can happen if some settings are missing. Make sure you have at least `$wgAWSBucketName` and `$wgAWSRegion` are set.

I'm getting Exception, even though the extension is shown to be installed
-------------------------------------------------------------------------

[](#im-getting-exception-even-though-the-extension-is-shown-to-be-installed)

This can happen if some settings are missing. Make sure that `$wgAWSRegion` is set (even if your config doesn't use it, e.g. when using non-Amazon providers).

Non-standard configuration
==========================

[](#non-standard-configuration)

Using another S3-compatible service (not Amazon S3 itself)
----------------------------------------------------------

[](#using-another-s3-compatible-service-not-amazon-s3-itself)

You can use non-Amazon software that supports S3 API (such as Apache CloudStack, Digital Ocean, etc.) instead of Amazon S3 itself. To enable this, add the following lines to LocalSettings.php:

```
//The url used for the API (PutObject, etc.)
$wgFileBackends['s3']['endpoint'] = 'https://my-custom-url';
//The url used for showing images. $1 is translated to the bucket name.
$wgAWSBucketDomain = '$1.my-custom-url';
```

Make sure `$wgAWSBucketName` and `$wgAWSRegion` are set as well.

Some software (such as MinIO) doesn't use subdomains for buckets, in which case you need the following configuration:

```
$wgFileBackends['s3']['use_path_style_endpoint'] = true;
```

Some software doesn't support modern checksums (expected by AWS SDK v3.337.0 and above). You can workaround it by adding the following lines to LocalSettings.php:

```
putenv( 'AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED' );
putenv( 'AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED' );
```

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance78

Regular maintenance activity

Popularity40

Moderate usage in the ecosystem

Community27

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 69.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 ~365 days

Recently: every ~463 days

Total

10

Last Release

127d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/517f06df77fa317fdb6873154d4058f57528db35278722e9a1e9035f13a93d8e?d=identicon)[edwardspec](/maintainers/edwardspec)

---

Top Contributors

[![edwardspec](https://avatars.githubusercontent.com/u/1163218?v=4)](https://github.com/edwardspec "edwardspec (283 commits)")[![translatewiki](https://avatars.githubusercontent.com/u/24829418?v=4)](https://github.com/translatewiki "translatewiki (56 commits)")[![yardenac](https://avatars.githubusercontent.com/u/687943?v=4)](https://github.com/yardenac "yardenac (9 commits)")[![hashar](https://avatars.githubusercontent.com/u/281689?v=4)](https://github.com/hashar "hashar (7 commits)")[![Parent5446](https://avatars.githubusercontent.com/u/52883?v=4)](https://github.com/Parent5446 "Parent5446 (5 commits)")[![kghbln](https://avatars.githubusercontent.com/u/1104078?v=4)](https://github.com/kghbln "kghbln (5 commits)")[![gboyers](https://avatars.githubusercontent.com/u/9747255?v=4)](https://github.com/gboyers "gboyers (4 commits)")[![umherirrender](https://avatars.githubusercontent.com/u/1174884?v=4)](https://github.com/umherirrender "umherirrender (3 commits)")[![samwilson](https://avatars.githubusercontent.com/u/213655?v=4)](https://github.com/samwilson "samwilson (3 commits)")[![snuxoll](https://avatars.githubusercontent.com/u/36403?v=4)](https://github.com/snuxoll "snuxoll (3 commits)")[![thaiphan](https://avatars.githubusercontent.com/u/644172?v=4)](https://github.com/thaiphan "thaiphan (2 commits)")[![yoshz](https://avatars.githubusercontent.com/u/397425?v=4)](https://github.com/yoshz "yoshz (2 commits)")[![Ladsgroup](https://avatars.githubusercontent.com/u/5351225?v=4)](https://github.com/Ladsgroup "Ladsgroup (2 commits)")[![siebrand](https://avatars.githubusercontent.com/u/210297?v=4)](https://github.com/siebrand "siebrand (2 commits)")[![lens0021](https://avatars.githubusercontent.com/u/28209361?v=4)](https://github.com/lens0021 "lens0021 (2 commits)")[![reedy](https://avatars.githubusercontent.com/u/67615?v=4)](https://github.com/reedy "reedy (2 commits)")[![originalauthority](https://avatars.githubusercontent.com/u/123885349?v=4)](https://github.com/originalauthority "originalauthority (2 commits)")[![paladox](https://avatars.githubusercontent.com/u/5727000?v=4)](https://github.com/paladox "paladox (2 commits)")[![Mastergalen](https://avatars.githubusercontent.com/u/1261152?v=4)](https://github.com/Mastergalen "Mastergalen (1 commits)")[![addshore](https://avatars.githubusercontent.com/u/3308769?v=4)](https://github.com/addshore "addshore (1 commits)")

---

Tags

mediawiki-extension

### Embed Badge

![Health badge](/badges/edwardspec-mediawiki-aws-s3/health.svg)

```
[![Health](https://phpackages.com/badges/edwardspec-mediawiki-aws-s3/health.svg)](https://phpackages.com/packages/edwardspec-mediawiki-aws-s3)
```

###  Alternatives

[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.6k263.6M790](/packages/league-flysystem-aws-s3-v3)[humanmade/s3-uploads

WordPress plugin to store uploads on S3

2.1k2.4M9](/packages/humanmade-s3-uploads)[aws/aws-sdk-php-laravel

A simple Laravel 9/10/11/12/13 service provider for including the AWS SDK for PHP.

1.7k35.6M75](/packages/aws-aws-sdk-php-laravel)[fusic/filebinder

Simple file attachment plugin for CakePHP

7230.1k](/packages/fusic-filebinder)[mreduar/s3m

Multipart Uploads using Laravel and AWS S3

173.6k](/packages/mreduar-s3m)[jonnyw/craft-awss3assets

A Craft CMS plugin allowing you to upload assets to an AWS S3 bucket.

101.6k](/packages/jonnyw-craft-awss3assets)

PHPackages © 2026

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