Image Provider for phpBB

Image Provider gives registered phpBB users a reusable, S3-backed image gallery in the post and topic editor.

Users can upload one or more images from the editor toolbar or by drag and drop, follow per-file upload progress, browse recent images in a Masonry-style gallery, and insert the selected image as [img] BBCode at the current cursor position. A separate My images page supports uploads and deletion, while administrators can configure storage and manage every user’s images from the ACP.

Remote bucket URLs and object keys are never sent to the browser. Public forum image URLs contain a random 128-bit identifier and are served by a phpBB proxy with browser caching, conditional requests, byte ranges, and a size-bounded least-recently-used disk cache.

Requirements

• phpBB 3.3
• PHP 7.2 or newer, on a version supported by the installed phpBB release
• PHP cURL, DOM, Fileinfo, and Mbstring extensions
• An S3-compatible bucket and credentials with object read, write, and delete access
• A writable phpBB store/ directory

Install

1. Copy the extension to phpBB/ext/bobmaster/imageprovider. The directory name is imageprovider, without a hyphen.
2. In the ACP, open Customise → Manage extensions and enable Image Provider.
3. Open Extensions → Image Provider → Settings.
4. Enter the S3-compatible endpoint, bucket, signing region, access key, and secret.
5. Use Test connection. The test creates a random canary object, reads its metadata and contents, then deletes it.
6. Save the settings.

S3 permissions

The credentials need GetObject, PutObject, and DeleteObject for the configured prefix. S3 handles HEAD through the object-read permission. ListBucket is not required.

An AWS-style policy for the default image-provider/ prefix is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET/image-provider/*"
    }
  ]
}

Keep the bucket private. Browser CORS access to the bucket is not needed because browsers only contact the forum proxy.

Use virtual-host style when the provider supports bucket.endpoint/key. Enable path style when the provider instead requires endpoint/bucket/key. Cloudflare R2 uses the account endpoint, region auto, and normally virtual-host style.

Configuration

The ACP provides:

• a global upload/gallery switch;
• endpoint, bucket, region, access key, secret, request style, and object prefix;
• maximum upload size from 1 to 100 MiB;
• an optional per-user quota;
• a backend disk-cache limit;
• a browser/shared-cache lifetime from 0 to 365 days;
• an infinite-scroll page size from 5 to 50 images;
• an ACP image-manager page size from 5 to 100 rows.

The secret is stored in phpBB’s text configuration table and is never rendered back into the ACP. Leaving its field blank preserves the current value.

These environment variables override the corresponding database values at runtime:

S3_ENDPOINT
S3_BUCKET
S3_REGION
S3_ACCESS_KEY_ID
S3_SECRET_ACCESS_KEY
S3_FORCE_PATH_STYLE

The object-key prefix remains an ACP setting. Provision the same environment values to both web and CLI processes when environment overrides are used.

Access and deletion behavior

• Guests and bots cannot use the gallery or management API.
• Registered users can browse and manage their own existing images.
• Users marked by phpBB as newly registered cannot upload until phpBB clears their user_new status.
• API mutations use phpBB link hashes, and users can only delete their own rows.
• ACP settings require acl_a_board; ACP image management requires acl_a_user.
• Deletion removes the S3 object first. Only after S3 confirms deletion, or reports that the object is already absent, does the extension remove the database row and local cache entry.

Deleting an image breaks posts that reference its proxy URL. Browsers or shared caches may retain a previously fetched copy until the configured browser-cache lifetime expires.

Purging the extension removes its database table and settings but does not enumerate and delete objects left in the bucket. Remove images through the user or ACP interface first, or clean the configured prefix with the storage provider before purging.

Proxy and cache behavior

The proxy:

• returns the validated stored MIME type with X-Content-Type-Options: nosniff;
• applies a restrictive sandbox Content Security Policy to SVG responses;
• supports ETag, Last-Modified, If-None-Match, and range responses;
• sends public max-age, s-maxage, and immutable directives;
• stores fetched objects under phpBB/store/image_provider_cache/;
• updates cache-file modification time on access and evicts the least recently used files when the configured byte limit is exceeded.

The backend cache is local to each phpBB node. In a multi-node installation, the configured limit applies independently to every node.

Supported images

JPEG, PNG, GIF, WebP, TIFF, SVG, and AVIF are accepted. The server verifies the actual file format and image dimensions rather than trusting the filename or browser-provided content type. SVG files are parsed and stripped of scripts, external resources, event handlers, animation, and inline styles before upload. Object names are generated from random identifiers and never from the original filename.

TIFF display support varies by browser. The gallery shows a clear fallback when a browser cannot preview a valid TIFF; the original file remains available through the forum proxy and can still be inserted as image BBCode.

Languages

• English
• Simplified Chinese (zh_cmn_hans)
• Traditional Chinese (zh_cmn_hant)

Development and tests

Run the test suite from the extension root with a PHPUnit 9 runner:

phpunit --configuration phpunit.xml.dist

The suite covers S3 request construction and signing, storage configuration, SVG sanitization, AVIF/TIFF format handling, LRU eviction, access rules, editor/manager/ACP integration assets, and translation key and placeholder parity.

Security

Report vulnerabilities privately to the extension maintainer. Do not include live S3 credentials, phpBB passwords, session IDs, or private object contents in a public issue.

License

GNU General Public License v2.0 only.