Skip to content

2.0.0-beta.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@imorland imorland released this 22 Feb 17:00
· 9 commits to 2.x since this release
2.0.0-beta.1
af2ff11
This commit was signed with the committer’s verified signature.
imorland IanM
GPG key ID: 9DFE339D48FA8519
Verified
Learn about vigilant mode.

FoF Upload 2.0.0-beta.1

This is the first beta release of FoF Upload for Flarum 2.0. It is a significant update — beyond the Flarum 2.0 compatibility work, several long-requested features have been added and a number of bugs fixed.

Flarum 2.0 compatibility

The entire extension has been updated to run on Flarum 2.0. Key changes under the hood:

  • Flysystem 3.x — the file storage layer has been updated to the new League Flysystem API, which changes how adapters are constructed and how errors are handled
  • JSON:API rewrite — Flarum 2.0 replaces Tobscure JSON:API with a new implementation; all API controllers and serialisers have been updated accordingly
  • PHPUnit 11 — the test suite has been migrated from PHPUnit 9 to PHPUnit 11, including the move to model factories for database tests
  • LESS variables — CSS variables are now used throughout; light/dark mode variable names have been updated to match Flarum 2.0 conventions
  • Frontend infrastructure — all JS/TS has been updated for Flarum 2.0's frontend changes

New features

WebP thumbnail generation (#465)

Images are now automatically downscaled to a thumbnail at upload time. The thumbnail is shown inline in the Image Preview template; clicking it opens the original full-resolution file in a new tab. This can significantly reduce bandwidth on image-heavy forums.

  • Thumbnails are encoded as WebP by default (~30% smaller than JPEG at equivalent quality), with an admin toggle to use the original format instead
  • Thumbnail max width is configurable (default: 1000 px); images smaller than the limit are never upscaled
  • The thumbnail path is stored in the database, but the full URL is derived from the live storage hostname at render time — so CDN domain changes are reflected automatically without any re-processing
  • Imgur and private-shared uploads are excluded (Imgur manages its own thumbnails)
  • A new console command — php flarum fof:upload:backfill-thumbnails — generates thumbnails for existing uploads created before the feature was enabled. It supports --dry-run and --chunk options and is safe to run multiple times

Per-MIME-type upload permissions (#461)

MIME type mappings can now have an optional permission label (e.g. "Images", "Videos"). When set, a dedicated permission entry appears in the Flarum permission grid, allowing you to restrict which user groups may upload that specific file type — in addition to the base "Upload files" permission that is always required.

This is fully backwards compatible: existing mappings without a label continue to work exactly as before, governed only by the base upload permission.

Image dimension storage and CLS prevention (#464)

The width and height of JPEG, PNG, and GIF uploads are now stored in the database. These are injected as width and height attributes on the <img> tag in the Image Preview template, which allows the browser to reserve the correct amount of space before the image loads — preventing Cumulative Layout Shift (CLS).

A console command — php flarum fof:upload:backfill-dimensions — backfills dimensions for existing images.

Watermark improvements (#462)

The watermark system has been significantly improved:

  • Proportional sizing — watermark size is now set as a percentage of the image width (e.g. 20%), so it scales correctly across different image sizes instead of being a fixed pixel size
  • Opacity control — configurable from 0–100%
  • Padding — configurable distance from the edge of the image in pixels
  • All settings are adjustable from the admin panel; animated GIFs are excluded from watermarking

Bug fixes

Correct adapter key stored for third-party adapters (#466)

Third-party adapters register under custom keys (e.g. 'blomstra'), but upload_method was being derived from the class name (e.g. 'blomstraobjectstorage'). This mismatch caused a ValidationException on every subsequent lookup — URL generation, file cleanup, GDPR export, and thumbnail backfill all failed for affected adapters. The fix stamps the canonical registration key directly on the adapter instance at instantiation time.

File–post mapping fixed for all templates (#459)

File-to-post associations were not being correctly created or cleaned up for some upload templates. This affected the media manager, GDPR export, and orphan cleanup features for certain template types.

Alt text bug in Image Preview template (#463)

The {TEXT?} placeholder was being stored literally in post XML for legacy posts. The formatter now sanitises this value and falls back to the file's base name, matching the intended behaviour.

PHP fileinfo extension is now optional (#467)

Without the fileinfo PHP extension, mime_content_type() would throw an uncaught exception, causing all uploads to fail with a generic error. The MIME detector now checks whether fileinfo is loaded before calling it. When absent, uploads continue to work using the magic-byte based SoftCreatR\MimeDetector library alone. Admins are shown a warning banner on the settings page explaining that the MIME cross-validation layer is disabled, and how to re-enable it.

Upgrade notes

Please read the README on the 2.x branch in full before upgrading. It covers storage configuration, all available settings, and environment variable support in detail.

  • Flarum 2.0 is required. This release does not support Flarum 1.x; continue using the 1.x branch for Flarum 1.x installations.
  • Run migrations after upgrading: php flarum migrate
  • S3 / compatible storage users: the underlying Flysystem AWS S3 adapter has been updated from v1 to v3. You must upgrade the package in your project: 
    composer require league/flysystem-aws-s3-v3:"^3.0"
    The v1 package (league/flysystem-aws-s3-v3:^1) is no longer compatible with this release.
  • Optionally run the backfill commands for existing content:
    • php flarum fof:upload:backfill-dimensions — adds stored image dimensions
    • php flarum fof:upload:backfill-thumbnails — generates thumbnails for existing images (may take a while on large forums; use --dry-run first)
  • Third-party upload adapter extensions (e.g. blomstra/object-storage) will need to be updated for Flarum 2.0 / Flysystem 3.x compatibility before they can be used with this release.

What's Changed

  • refactor: Upgrade for 2.0 by @imorland in #458
  • [2.x] fix: correctly map and clean up files for all upload templates by @imorland in #459
  • [2.x] feat: per-mime-type permission scoping by @imorland in #461
  • [2.x] feat: proportional watermark scaling, opacity and padding controls by @imorland in #462
  • [2.x] test: add unit tests for all templates; fix image-preview alt text bug by @imorland in #463
  • [2.x] feat: store image dimensions to prevent layout shifts on lazy-loaded images by @imorland in #464
  • [2.x] feat: generate WebP thumbnails at upload time to reduce bandwidth by @imorland in #465
  • [2.x] fix: store correct adapter key in upload_method for third-party adapters by @imorland in #466
  • [2.x] fix: degrade gracefully when PHP fileinfo extension is missing; show admin warning by @imorland in #467

Full Changelog: 1.8.8...2.0.0-beta.1

Contributors

imorland
Assets 2
Loading