README

A Flarum extension that automatically fetches and applies width and height dimensions to all <img> tags in your forum posts.

By hardcoding the dimensions into the parsed XML of the posts, this extension eliminates Cumulative Layout Shift (CLS), dramatically improving your forum's page performance scores and scrolling experience.

Features

• Smart Processing: Uses highly optimized HTTP streams (via FastImageSize) to only download the header bytes of remote images, drastically reducing memory and bandwidth overhead.
• Dynamic Operating Modes: Choose how the extension extracts dimensions based on your server resources:
  • Client Mode (Default): Forum visitors automatically detect image dimensions in their browser and silently report them back to the server. Best for heavily cached or low-resource servers.
  • Backend Mode: The server uses a background Queue Worker to fetch dimensions every time a post is created or edited.
  • Hybrid Mode: Combines both approaches for maximum coverage.
• Data Integrity: Implements robust Optimistic Locking to ensure background workers never overwrite concurrent user edits.
• Network Proxy Support: Configurable proxy settings (e.g. tcp://10.0.0.5:3128) for servers behind corporate firewalls.
• Scheduled Backfills: Automatically retry failed image fetching on a daily, weekly, or monthly cron schedule.

Installation

Install with composer:

composer require huoxin/auto-image-dimensions:"*"

CLI Commands

If you have thousands of existing posts, you can manually trigger a backfill from the command line:

# Fetch dimensions for ALL images that don't have them
php flarum image-dimensions:backfill

# ONLY retry images that previously failed (e.g. due to 404s or timeouts)
php flarum image-dimensions:backfill --retry-failed

Updating

composer update huoxin/auto-image-dimensions:"*"
php flarum migrate
php flarum cache:clear

Links

• Packagist
• GitHub