Cover Studio

TryHackX

Hi everyone! 👋

I'd like to share Cover Studio — a Flarum 2.x extension that adds profile covers with a repositionable focal point ("pos-crop") and zoom, fully integrated with the FoF Upload media manager. Optionally, the same focal-point editing is available for avatars.

🖼️ Screenshots

✨ Features

Profile covers

Upload a cover image or pick one you already uploaded from "My Media" (FoF Upload's media manager).
No destructive cropping — the image is kept at full resolution. You choose a focal point and an optional zoom (0.5×–4×), and every surface centers on that point.
Zooming out below 1× creates a cinematic letterbox effect: the exposed bands are filled with a blurred copy of the image — great for wide skies or full artworks.
Re-position at any time without re-uploading — drag with mouse/touch, zoom with the mouse wheel or a slider, or use the keyboard (arrows pan, +/- zoom). A rule-of-thirds grid and a focal-point crosshair make precise framing easy.
Covers show on the profile hero and (optionally) on post hover cards and in the FoF User Directory — those use a lightweight thumbnail instead of the full image.
Readability overlay (gradient / uniform darken / none) and an optional default cover URL for users without one.
Moderators with the edit user permission can manage other users' covers.

Media manager integration

Cover files are regular FoF Upload files owned by the profile owner — they appear in My Media.
Deleting the file there removes the cover automatically; hiding it keeps the cover visible.

Avatar focal point (optional)

Avatar uploads keep the original image, and the actual avatar is re-cropped server-side whenever the user adjusts the focal point or zoom — always full quality, never a re-upload.
The result stays a 100% standard Flarum avatar everywhere (all sizes, HiDPI, e-mails, notifications) — no CSS hacks, no compatibility issues.

📋 Requirements

Flarum ^2.0
PHP ^8.3
fof/upload installed and enabled

📦 Installation

composer require tryhackx/flarum-cover-studio
php flarum migrate
php flarum cache:clear

Then enable Cover Studio in the admin panel.

🔁 Migrating from sycho/flarum-profile-cover

Existing covers can be imported — each one becomes a proper FoF Upload file in the owner's media manager:

php flarum cover-studio:migrate-sycho --dry-run   # preview
php flarum cover-studio:migrate-sycho             # import

The command is non-destructive: legacy files and the users.cover column are left untouched.

❤️ Support

Cover Studio is free and MIT-licensed. If you find it useful, there is a Support Development button at the top of the extension's admin settings with donation addresses — every contribution helps keep the project maintained.

Feedback, bug reports and feature requests are very welcome — here or on the issue tracker.

Enjoy! 🎉

Forogramero

Great work! Thank you!!

TryHackX

[2.0.2] - 2026-07-03

Fixed

The user-controls dropdown (the ⋮ badge, .UserCard-controls) was hidden
behind the top navigation bar on phones when a cover was present. CoverStudio
gave .darkenBackground a z-index, which turned it into a stacking context
and trapped the dropdown below the fixed .App-navigation bar. The z-index
is now dropped (DOM order already keeps .darkenBackground above the cover
layers), so core's phone promotion of the dropdown to z-index: var(--zindex- header) + 1 works again and the badge floats above the nav bar. LESS-only fix
— no JS rebuild and no migration.

DLBB

Is Default avatar URL possible?

TryHackX

[2.1.0] - 2026-07-04

Added

Default cover and default avatar are now managed through the same
focal-point editor modal used on profiles, instead of a plain URL field.
Admins can upload an image or pick one from the FoF Upload shared media
library, reposition it (drag + zoom 0.5×–4×) and remove it. Uploads are stored
as shared files. The default avatar is shown (client-side) for users who have
not set their own, with core's letter avatar kept as the ultimate fallback.

Changed

The Default cover URL admin text field was replaced by the new default-cover
editor. Any previously configured URL keeps working and is shown in the editor.

Backend

New admin-only endpoints POST|PATCH|DELETE /api/cover-studio/default/{kind}
(kind = cover | avatar) and settings
default_{cover,avatar}_{url,focus_x,focus_y,zoom}. No migration required.

DLBB

Can we just make FoF Upload an optional dependency? Right now, it's blocking Cover Studio from being enabled.

Also, quick question: can we force existing letter avatars to switch to the new default avatar, or does that happen automatically once the default is configured?

Karl

DLBB if you don't want users to upload files, just take their permission away.

DLBB

Karl I can't enable Cover Studio without enabling FoF Upload first. I'm trying to keep my setup lean by only installing essential extensions.

Cannot enable Cover Studio until the following dependencies are enabled: FoF Upload

Karl

DLBB I understand. But honestly, FoF Upload is lean and you won't have to worry about it reducing your sites permissions on regular users when it comes to posting. They won't have the fof upload option loaded in their composer.

TryHackX

[2.2.1] - 2026-07-04

Fixed

The avatar-focus guard is now a request-scoped, container-managed instance
instead of a static property. Under persistent-process servers (Octane /
RoadRunner / Swoole) a worker terminated mid-re-crop could previously leave
the flag set, silently disabling the "clear the stored avatar original on an
external avatar change" listener for the rest of that worker's life. No effect
under standard PHP-FPM, where the flag was already reset per request.

Internal

Focus is now an injectable service (translator injected via the constructor)
instead of reaching into the container with resolve() on its error path,
making focal-point parsing unit-testable in isolation.
MigrateSychoCommand injects Illuminate\Database\Schema\Builder for its
schema-introspection check instead of Illuminate\Database\ConnectionInterface,
per Flarum convention.

No migration required.

[2.2.0] - 2026-07-04

Performance

Cover and avatar focal-point data has moved off the users table into a
dedicated, sparse cover_studio_user_data companion table (keyed by
user_id). The eleven columns previously added to users widened every row
on a table that is read — and whose authors are serialized — on nearly every
page; on large forums (hundreds of thousands to millions of users) that hurt
buffer-pool efficiency and cold reads. A row now exists only for users who
actually set a cover or avatar original, and it is eager-loaded on every user
query in a single batched WHERE user_id IN (…), so serialization stays free
of N+1 queries. Run php flarum migrate when updating — existing data is
copied across automatically and the old columns are dropped; the migration is
reversible.

Fixed

cover-studio:migrate-sycho never generated cover thumbnails during a real
(non-dry-run) import: the per-user closure used $makeThumbs /
$thumbMaxWidth without capturing them, so the fof-upload.generateThumbnails
setting was silently ignored. Imported covers now get thumbnails as intended.

Changed

Pinned the fof/upload dependency to ^2.0.0-beta.5 (was *), so a future
major release can no longer silently break the upload bridge.
Removed the MySQL-only ->unsigned() modifier from the decimal focal-point /
zoom columns for correct schema portability on PostgreSQL and SQLite (the
valid ranges are already enforced in application code).

Internal

The Guzzle HTTP client used to fetch remote-adapter files is now injected
instead of constructed inline (mockable, container-configurable), and the
fof/upload local-storage path is centralized in one method.
MigrateSychoCommand::handle() (162 lines) was split into focused private
methods. No behavior change beyond the thumbnail fix above.

Xkyer

Hello, thanks for extension. I was wonder why don't leech cover into blog post. ty

Nightroad94

@TryHackX I have opened a Issue on Github I like using Avocado theme by @ram0ng1 but it seems that the theme is overriding User Covers with <div class="AvocadoUserPage-cover"></div>

ram0ng1

Nightroad94

This isn't a functional issue with the extension, but rather with the custom theme...

Since I don't have context on the issue itself, I'll need more details...

Is this the same extension where I already applied the fixes:

#39144

Nightroad94

ram0ng1 its for this extension here Cover Studio you cant see the custom Profile Cover with your theme as it overrides this extensions profile cover.