huoxin/auto-image-dimensions

Automatically fetches and applies width and height dimensions to Flarum image tags to prevent layout shift (CLS).

Maintainers

Package info

github.com/huoxin233/flarum-ext-auto-image-dimensions

Type:flarum-extension

pkg:composer/huoxin/auto-image-dimensions

Transparency log

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

1.0.0-beta.1 2026-07-08 14:11 UTC

Requires

Requires (Dev)

MIT c6d8d4b121fe509bc995c82e7ee2bac5e529ca79

  • huoxin <23447157+huoxin233.woop@users.noreply.github.com>

flarum

Published on Packagist.org on 2026-07-08 14:15 UTC

This package is auto-updated.

Last update: 2026-07-08 17:01:23 UTC

README

License Latest Stable Version Total Downloads Review Review Score

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