README

A Flarum extension (Fork of @Dem13n's discussion-cards). Allows you to display discussions in the form of cards, the first image of the first post is used as a preview, if there are no images, a stub is displayed.

This fork makes changes and adds new features where you can now set custom cards settings per tag page (different default image along with number and width of primary cards). On the index page (all discussions), if a discussion has multiple tags with their own custom image set, the displayed image will be chosen according to these priority rules:

1. The image of the the highest positioned child primary tag of the highest positioned parent primary tag
2. The image of the highest positioned parent primary tag
3. The image of the secondary tag with the lowest id
4. The general default image

For full list of changes & new features, please refer to the CHANGELOG.md file.

📢 IMPORTANT NOTICE

Versions 2.x and up will target Flarum V2.

Version 1.4.4 was the final version targeting Flarum V1. All future dev efforts will be for versions 2.x and up targeting only Flarum V2.

🧩 3rd party extensions support

Flarum V2
- As of version 2.1.0, supported again:
  - michaelbelgium/flarum-discussion-views for views count on cards.
  - fof/blog (successor of the abandoned v17development/flarum-blog) for blog post cards.
  - shebaoting/flarum-repost (formerly shebaoting/repost) for "link sharing", with two new optional settings to add a link icon before the card title and the url's domain after it.
- As of version 2.0.0 fof/discussion-views is supported for views count on cards.
Flarum V1
- Until version 1.3.0 flarumite/simple-discussion-views was supported to show discussion views count on cards (see replacement below)
- As of version 1.1.0 added support for the v17development/flarum-blog extension. If activated, you can set to use the blog's extension images for blog posts' cards and/or their article summary as preview text on the cards.
- As of version 1.2.0 added support for the shebaoting/repost extension. If activated, you can set it so that when you click on the card title of a discussion starting with a url, it will open that url, and clicking anywhere else on the card will open the discussion as usual.
- As of version 1.3.0 added support for the michaelbelgium/flarum-discussion-views extension.
- As of version 1.4.0 added support for the fof/discussion-views extension (replacing the abandoned flarumite/simple-discussion-views)

🖥️ Console Commands (CLI)

As of version 1.4.0 new CLI commands have been added to manage card images:

php flarum discussion-cards:migrate-images to migrate old default images (pre 1.4.0). It is not run automatically: run it manually after updating if you come from 1.3.0 or earlier.
php flarum discussion-cards:purge-images to delete unused or all card images from server.
php flarum discussion-cards:regenerate-images to regenerate card images or generate missing card images.
php flarum discussion-cards:repair-images to detect and repair broken card images (deleted files). Added in version 2.1.0. As of version 2.1.0 the three commands above have a --log option (writes the command and the detail of each discussion or file to a log file) and show the same details in the terminal with -v or --verbose flag. All details on how to use them can be found in the extension's wiki on github (See Documentation in the Links section below or in the Admin Settings Page). You can also add the --help flag to each command to list options.

🖼️ Screenshots

💬 Languages

The extension is natively in English 🇬🇧 & French 🇫🇷; it's partially translated to other language by the Flarum translation community: You can help translate it to your language via Weblate: here for Flarum V2.

🗒️ Notes

Latest release developed and tested on Flarum 2.0.2 (first V2 version released 2.0.0).
V1 developed and tested on Flarum 1.8.7 (first version released 1.0.0) and last version 1.4.4 was developed and tested on Flarum 1.8.16.
V1: as of version 1.4.0 it requires a Flarum minimum version of 1.8.0.
Thanks to whomever suggested on Discord to use the tags selection component (sorry, we can no longer access the messages on Discord to mention them properly).
New settings page inspired by Friends of Flarum's Best Answer Extension.
Additional tags settings based on @askvortsov's Discussion Templates Extension.
Developed this with the help of AI (mainly Claude Code, ChatGPT, Gemini, Claude Code using Ollama Cloud models & Claude.ai).

📥️ Installation

⚠️ IMPORTANT

if you're installing any version for the first time or are updating from a version older than 1.4.0 you will need to regenerate card images for all existing discussions after activating the extension as it no longer does it in the frontend on page loads (performance issues). You can run php flarum discussion-cards:regenerate-imagesfirst to regenerate images for the 20 latest discussion (default) or use the button in the admin settings page (click on tools > regenerate images then on the Regenerate 20 latest card images button. Don't forget to add a general and/or tag default images first and if all is OK, you can regenerate card images for ALL discussions using the proper options with the command (see full documentation here)

Requirements: the PHP gd extension with WebP support is needed to generate card images (the Admin Info tool tells you if it's missing).

Install with composer:

composer require walsgit/flarum-discussion-cards

Then to generate card images for your discussion cards, activate the extension and run this command:

# For discussion cards without images (max 20 if no number is specified)
php flarum discussion-cards:regenerate-images -w [Number]

(see full documentation here for more options on the command)

↕️ Updating

ℹ️ If you're updating from version 1.3.0 or earlier TO version 1.4.0 or later, run php flarum discussion-cards:migrate-images manually after php flarum migrate: it moves and converts the old images used for cards to the new file structure and format (see the changelog of version 1.4.0 for details). You will also need to regenerate card images (see the post installation instructions above).

🔒 Version 2.0.3 is a complementary security release: all 2.x users are strongly advised to update.

ℹ️ Version 2.1.0: adds breaking changes like converting the stored card image paths (they no longer depend on your domain or sub-folder). Cards whose image comes from an old external URL keep it until their card image is regenerated. Run php flarum discussion-cards:repair-images --dry-run to check for broken card images.

composer update walsgit/flarum-discussion-cards
php flarum migrate
php flarum cache:clear

🆕 🔧 Troubleshooting & Support

As of version 2.0.1 (V2) & 1.4.4 (V1) a Debugging Information tools was added to the Tools menu in the Admin Settings Page. You can use it to check how & why a discussion has a specific card image (see what the resolver sees and checks).

Before you post an issue, copy & paste the debugging information from this tools along with your php flarum infooutput and any relevant screen capture.

walsgit / flarum-discussion-cards

Package info

Security

Fund package maintenance!

Statistics