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.

Versions 1.4.x will be the final versions targeting Flarum V1. No more new features will be added, but some bug fixes & security updates will still be provided (if necessary) until full support will be dropped sometime before the end of 2026 or early 2027. All future dev efforts will be for versions 2.x and up targeting Flarum V2.

🧩 3rd party extensions support

• Flarum V2

  • As of version 2.0.0 only fof/discussion-viewsis supported. The other extensions that where supported in V1 have yet to be ported for Flarum V2 as of the latest release. Support will be added once they'll be ported or it will be dropped unless an alternative is released.

• 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 (runs automatically on update).
• 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. 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 & here for Flarum V1.

🗒️ Notes

• V2 developed and tested on Flarum 2.0.0-rc.1 (first 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.
• 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 ChatGPT, Gemini & Claude Code using Ollama Cloud models).

📥️ 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)

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)

ℹ️ Note that, as of versions 2.0.1 (V2) & 1.4.4 (V1), right after the installation, an automatic command will run to generate card images for the 20 latest, top & newest discussions

↕️ Updating

ℹ️ If you're updating from version 1.3.0 or earlier TO version 1.4.0 or later not that the discussion-cards:migrate-images command will be automatically run to move and convert old images used for cards to new file structure and format (See changelog of version 1.4.0 for more details). You will also need to need to regenerate card images if you updating from those older versions (see post installation instruction above)

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.

🔗 Links

• Packagist
• GitHub
• Documentation
• Discuss
• Donate