Hi everyone,
I have been testing Flarum 2.0.0 RC8 with the Persian language pack and the irmmr/flarum-ext-rtl extension, and I ran into a compatibility issue that prevents Flarum from loading immediately after installing the RTL extension.
I created a small compatibility patch and tested it on a clean Flarum 2 RC8 installation. The results so far are positive, so I am sharing the problem, the workaround, and the complete test procedure here in case it is useful to other Flarum 2 users and extension developers.
There is already an ongoing discussion about the RTL extension here:
#29660
There is also a recent discussion about improving RTL support in Flarum 2.x:
#39139
Since my issue seemed to be related specifically to the interaction between the Flarum 2 asset compiler and the RTL extension, I decided to reproduce it on a completely fresh Flarum 2 RC8 installation and investigate what was happening.
I’m sharing the results here in case they are useful to others working on Flarum 2 and RTL languages.
Environment
The test environment was:
- Flarum: 2.0.0 RC8
- PHP: 8.5.10
- MariaDB: 11.8.9
- Nginx
- Composer: 2.10.3
- Persian language pack: flarum-lang/persian 2.0.1
- RTL extension: irmmr/flarum-ext-rtl dev-main
The test was performed on a fresh Flarum installation with no other third-party extensions installed.
The problem
After installing:
composer require irmmr/flarum-ext-rtl:dev-main --with-dependencies
both the forum and the admin dashboard stopped loading.
Interestingly, the RTL extension itself had not been enabled yet.
The Flarum log showed:
Error: Call to undefined method
Flarum\Frontend\Compiler\LessCompiler::setFontsDir()
The error originated from:
vendor/flarum/core/src/Frontend/Assets.php
while creating the LESS compiler.
At first this looked like a normal extension compatibility problem, but the fact that the extension was disabled and the entire application was still affected seemed worth investigating.
What I found
After inspecting the composer.json of irmmr/flarum-ext-rtl, I found that its autoload configuration contains:
"autoload": {
"psr-4": {
"Irmmr\\FlarumRtlSupport\\": "src/"
},
"files": [
"src/Overrides/Frontend/Compiler/LessCompiler.php"
]
}
This means that the LessCompiler.php override is loaded through Composer's autoloader independently of whether the Flarum extension is enabled.
I then compared the RTL extension's LessCompiler implementation with the corresponding Flarum 2 RC8 core class.
The Flarum 2 compiler contains several methods that are not present in the RTL extension's override, including:
setFontsDir()
readCache()
writeCache()
pruneCacheOnce()
fontRevision()
For example, Flarum 2 RC8 contains:
public function setFontsDir(?string $fontsDir): void
{
$this->fontsDir = $fontsDir;
}
while the RTL override did not provide this method.
So when Flarum 2's asset pipeline called:
$compiler->setFontsDir(...)
the overridden class did not have the method, resulting in the fatal error.
The patch
I created a small compatibility patch that keeps the Flarum 2 RC8 LessCompiler implementation intact and adds the RTL-specific functionality on top of it.
Repository:
mabioca/flarum-rtl-patch
Release:
mabioca/flarum-rtl-patchv1.0.1-flarum2
The main changes are in:
src/Overrides/Frontend/Compiler/LessCompiler.php
The patched compiler retains the Flarum 2 methods such as:
setFontsDir()
readCache()
writeCache()
pruneCacheOnce()
fontRevision()
and adds the RTL processing in the compiler's output stage.
The patch generates RTL CSS as a sidecar asset rather than replacing the normal LTR asset.
For example:
forum.css
forum.rtl.css
admin.css
admin.rtl.css
This means the normal LTR assets remain available while RTL versions are generated alongside them.
Testing
I tested the patch step by step on the same clean Flarum 2 RC8 installation.
Test Result
Fresh Flarum 2 RC8 installation PASS
Persian language pack PASS
Install RTL extension without patch FAIL
Forum after applying patch PASS
Admin after applying patch PASS
php flarum cache:clear PASS
Enable RTL extension PASS
Generate forum.rtl.css PASS
Generate admin.rtl.css PASS
LTR assets remain available PASS
Actual LTR → RTL property flipping PASS
After applying the patch and clearing the cache, both the forum and admin dashboard loaded normally.
I then enabled the RTL extension and confirmed that the RTL assets were generated.
The assets directory contained:
admin.css
admin.rtl.css
forum.css
forum.rtl.css
Verifying that the RTL CSS is actually different
I also wanted to make sure that forum.rtl.css was not simply a copy of forum.css.
For example, the LTR stylesheet contained:
margin-left:-100px
while the generated RTL stylesheet contained:
margin-right: -100px
So the generated RTL stylesheet is actually applying left/right transformations rather than merely duplicating the original CSS.
I also found other RTL-related transformations involving properties such as:
padding-left
padding-right
margin-left
margin-right
which provided additional confirmation that the RTL processing was taking place.
Installation / testing procedure
For anyone who wants to reproduce the test, my basic procedure was:
1. Install a fresh Flarum 2 RC8 instance
Then install the Persian language pack:
composer require flarum-lang/persian:"*"
2. Install the RTL extension
composer require irmmr/flarum-ext-rtl:dev-main --with-dependencies
At this point, on my test installation, the forum and admin stopped loading even though the extension was not enabled.
3. Clone the compatibility patch
git clone https://github.com/mabioca/flarum-rtl-patch.git
cd flarum-rtl-patch
git checkout v1.0.0-flarum2
4. Back up the existing RTL override
sudo cp \
/var/www/flarum2fresh/vendor/irmmr/flarum-ext-rtl/src/Overrides/Frontend/Compiler/LessCompiler.php \
/var/www/flarum2fresh/vendor/irmmr/flarum-ext-rtl/src/Overrides/Frontend/Compiler/LessCompiler.php.before-patch
5. Replace it with the patched version
sudo cp \
src/Overrides/Frontend/Compiler/LessCompiler.php \
/var/www/flarum2fresh/vendor/irmmr/flarum-ext-rtl/src/Overrides/Frontend/Compiler/LessCompiler.php
6. Clear the Flarum cache
sudo -u www-data php flarum cache:clear
After this, the forum and admin dashboard loaded normally again.
Important note
This is a compatibility patch for testing, not an official Flarum core change or an official replacement for the RTL extension.
So far I have tested it against:
- Flarum 2.0.0 RC8
- PHP 8.5+
- MariaDB 11.x
irmmr/flarum-ext-rtl dev-main
It would be great to get feedback from people testing other Flarum 2 versions, PHP versions, or RTL languages.
Also, since Flarum 2 and RTL support are still evolving, this patch should be considered a staging/testing solution rather than something I would recommend blindly deploying to a production forum.
I really appreciate everyone in the Flarum community who continues to put time and effort into making Flarum better. Thank you for all the great work, and I hope this experience can be useful to others working with Flarum 2 and RTL languages.
