Kirby S3 Sync

[!NOTE] This is an early-stage release. Although core safeguards are in place, use it at your own risk. We strongly recommend creating backups before use.

Sync Kirby CMS files to S3 bucket/storage automatically, offloading local/server disk usage and serving assets through a CDN.

This plugin was originally inteded to work with Cloudflare's r2 storage, but since this is s3 compatible it works with all any S3-compatible storage.

Files uploaded through the Panel are pushed to your bucket, verified, and then replaced locally with a tiny placeholder — so your Kirby installation stays lightweight while the real files live on R2. file::url, file::version, and file::dimensions are transparently rerouted to the CDN, so templates and the Panel keep working without any changes to your existing code.

Built and maintained by Jore Dierckx.

Features

• Automatic upload on file create/replace via Kirby hooks
• Local file is only swapped for a placeholder after the upload is verified — nothing is lost on a failed upload
• CDN-aware file::url, file::version, and file::dimensions components — templates don't need to change
• Image dimensions read locally via getimagesize(), so width/height are always correct regardless of CDN processing delays
• Optional Cloudflare Images JSON metadata stored alongside each file
• Soft-delete: files are archived (_archive/...) in the bucket before deletion, not destroyed outright
• REST API route for uploading from custom Panel UI or external tools
• Standalone CLI scripts for bulk migration of existing files and for backfilling metadata after upgrades
• Works with any S3-compatible provider (R2, DigitalOcean Spaces, etc.) — CDN-specific metadata is skipped automatically if s3.cdn isn't configured

Requirements

• Kirby 3.6+ (for automatic Composer autoloading of plugins)
• PHP 8.1+
• An S3-compatible bucket (Cloudflare R2, DigitalOcean Spaces, AWS S3, etc.)

Installation

Via Composer (recommended)

Configuration

Add the following to your site's config.php. Config options can be nested under an s3 key:

key and secret are your R2/S3 access credentials. These must never be hardcoded in config.php or committed to version control. Store the actual values in your site's .env file instead (which should be gitignored), and reference them via env() as shown above:

Kirby supports environment-specific config files (e.g. config/config.local.php), so s3.active can be set per environment — leaving it false on local/staging keeps development files on local disk (simpler to inspect and reset) and reserves bucket writes for production only.

Option reference

How it works

On file create / replace

1. File is uploaded to the bucket via putObject.
2. Upload is verified with a doesObjectExist check.
3. Image dimensions are read locally with getimagesize() — this doesn't depend on the CDN having finished processing the file yet.
4. If s3.cdn is configured, Cloudflare's image-info JSON endpoint is fetched as supplementary metadata (file size, format, etc.). This step is skipped entirely on non-Cloudflare providers.
5. s3_key, s3_json, s3_width, and s3_height are saved to the file's content file.
6. Only after all of the above succeeds, the local file is replaced with a 1×1px placeholder.

If any step fails, the error is logged and the local file is left completely untouched — nothing is deleted or replaced on a failed upload.

On file delete

The object is copied to an _archive/ prefix in the same bucket before the original key is deleted — a soft-delete safety net. You can periodically clear out _archive/ manually once you're confident nothing needs recovering.

Serving files

Three of Kirby's core components are overridden:

• file::url — returns the CDN/bucket URL when s3_key is set, otherwise falls back to Kirby's native local URL.
• file::dimensions — returns the stored s3_width/s3_height when available, avoiding a filesystem read on a file that's now just a placeholder.
• file::version — builds a Cloudflare Image Resizing URL (/cdn-cgi/image/...) from width, height, quality, fit, and crop options passed to Kirby's usual $file->resize() / $file->crop() calls.

Existing templates using $file->url(), $file->resize(), $file->crop(), etc. don't need any changes.

Blueprint fields

The plugin ships a reusable field group (blueprints/fields/s3meta.yml) that can be included in any file blueprint where you want these fields visible in the Panel — all are managed automatically and don't need to be editable:

The fields in the group are:

• s3_key — the S3 key of the file (read-only).
• s3_width — the width of the file (read-only).
• s3_height — the height of the file (read-only).

s3_json is intentionally left out of the group by default since it's raw metadata, not something editors need to see — but it's stored in the content file and can be added to the group the same way if useful for debugging.

REST API

A route is registered for programmatic uploads (e.g. from a custom Panel UI):

{pageId} should have any / characters replaced with +. Returns {"status": "ok"} on success, or {"status": "error", "message": "..."} on failure. Respects s3.active — returns an error if sync is disabled.

CLI scripts

Two standalone scripts are included in scripts/ for one-off and maintenance work outside the normal Panel flow. Both support --dry-run and prompt for confirmation before making any changes.

migrate-to-s3.php

Bulk-migrates existing local files to your bucket — intended for the initial move to R2, or for re-syncing after restoring a backup.

• Prompts to migrate all pages or a single page by ID
• Shows a scope summary (page/file counts, expected key structure) before asking for final confirmation
• Skips files already correctly placed; moves files whose expected key has changed; uploads new files
• Safe to re-run — already-migrated files are detected and skipped, failed files are retried automatically on the next run

update-s3-meta.php

Backfills s3_width / s3_height (and s3_json) on files that were migrated before those fields existed, or after a plugin upgrade that adds new metadata fields.

• Reuses a file's already-stored s3_json when present, only hitting the CDN if it's missing
• Skips files that already have both s3_width and s3_height populated
• Skips non-image files and files not yet on the bucket

Provider compatibility

This plugin works with any S3-compatible endpoint. Cloudflare-specific behavior (the JSON metadata fetch and Image Resizing URLs in file::version) is only active when s3.cdn is set — leave it unset when using a provider without an equivalent feature, and the plugin falls back to plain bucket URLs and locally-read dimensions.

Safety notes

• Nothing is ever deleted locally until the corresponding upload is verified in the bucket.
• Nothing is ever deleted from the bucket without first being archived under _archive/.
• All hooks and the API route respect s3.active — set it to false to fully disable the plugin's behavior without uninstalling it.

Support

If this project saves you time, consider supporting it:

License

MIT © Jore Dierckx