[#44894] - [6.0] Configure Joomla with environment variables
- Closed
- 4 Mar 2025
- Medium
- Build: 5.3-dev
- # 44894
- Diff
- PopArtDesign:config-envs
User tests: Successful: Unsuccessful:
Pull Request for Issue #36898.
Summary of Changes
This PR adds an ability to configure Joomla using environment variables. To do this, the config provider has been changed to load all environment variables whose names start with JOOMLA_ (e.g. JOOMLA_DEBUG, JOOMLA_PASSWORD) and merge them into the config service.
Also, environment variables can be loaded from .env files, thankfully to symfony/dotenv.
Testing Instructions
-
Create
.envfile in the site's root directory -
Set environment variables (inside the
.envfile):JOOMLA_OFFLINE=1 JOOMLA_OFFLINE_MESSAGE='Joomla!'
-
Reload site's home page and ensure that site is offline and the
Joomla!message is shown -
Run the following command and ensure that the output is
true:cli/joomla.php config:get offline
-
Run the following command and ensure that the output is
Joomla!:cli/joomla.php config:get offline_message
Actual result BEFORE applying this Pull Request
All should work.
Expected result AFTER applying this Pull Request
All should work.
Link to documentations
Please select:
-
Documentation link for docs.joomla.org:
-
No documentation changes for docs.joomla.org needed
-
Pull Request link for manual.joomla.org:
-
No documentation changes for manual.joomla.org needed
Why?
The 12-factor app methodology recommends to store config in the environment.
Also, it makes Joomla more cloud-friendly and simplifies running it inside containers.
For example, using environment variables it's very easy to configure separate database for testing:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="tests/Unit/bootstrap.php" colors="false">
<testsuites>
<testsuite name="Unit">
<directory suffix="Test.php">./tests/Unit</directory>
</testsuite>
<testsuite name="Integration">
<directory suffix="Test.php">./tests/Integration</directory>
</testsuite>
</testsuites>
<php>
<env name="JOOMLA_DBHOST" value="localhost" force="true"/>
<env name="JOOMLA_DBNAME" value="joomla_test" force="true" />
<env name="JOOMLA_DBUSER" value="joomla_test_user" force="true" />
<env name="JOOMLA_DBPASSWORD" value="joomla_test_password" force="true" />
</php>
</phpunit>| Status | New | ⇒ | Pending |
joomla-cms-bot
- | Category | ⇒ | Administration Installation Libraries Unit Tests |
| Labels |
Added:
Unit/System Tests
PR-5.3-dev
|
||
@dgrammatiko, to check if the config value came from environment we can use the envs_config service:
/** @var Registry */
$envsConfig = $container->get('envs_config');
if ($envsConfig->has('debug')) {
// 'debug' came from environment
}| Labels |
Added:
Feature
|
||
Then load them manually in the respective files.
Just an update here, before you spend more time on it. We are discussing this in the maintainers team if it fits into our current setup. There are are already other ways to customize the config, so this would be another one.
I have tested this item 🔴 unsuccessfully on 2466eae
I have tested this item, issue not resolved
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/44894.
I have tested this item 🔴 unsuccessfully on 2466eae
Tested on: Joomla! 5.3-dev
Environment: Joomla! 5.3-dev (fresh setup)
Web Server: Apache
PHP Version: PHP 8.3
Database: MySQL
Steps Followed for Testing:
- Applied the patch via Patch Tester.
- Edited .htaccess file and added the environment variable: SetEnv JOOMLA_OFFLINE 1
- Restarted the web server : sudo systemctl restart apache2
- Opened the Joomla! frontend to check if the site was set to offline mode
Issue Observed:
- The site did not switch to offline mode.
- No errors were logged in Joomla! or the server error logs.
- Environment variables were not detected by Joomla!
Expected Behavior:
- Joomla! should recognize the JOOMLA_OFFLINE environment variable.
- The site should display the "Site is offline" message if the variable is set to 1.
Actual Behavior:
- Joomla! continues running normally, ignoring the JOOMLA_OFFLINE setting.
- No difference observed before and after applying the patch.
Additional Notes:
- Clearing Joomla! cache and restarting the server did not resolve the issue.
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/44894.
I have tested this item ✅ successfully on 2466eae
Sincerely apologize for my previous negative feedback regarding the issue. It was provided before properly applying the patch, and I realize now that it may not have reflected the actual results accurately.
After correctly applying the patch and retesting, here are my updated findings:
Tested on: Joomla! 5.3-dev
Environment: Joomla! 5.3-dev (fresh setup)
Web Server: Apache
PHP Version: PHP 8.3
Database: MySQL
Steps Followed for Testing:
- Applied the patch via Patch Tester.
- Edited .htaccess file and added the environment variable: SetEnv JOOMLA_OFFLINE 1
- Restarted the web server : sudo systemctl restart apache2
- Opened the Joomla! frontend to check if the site was set to offline mode
Issue Observed:
- The site switch to offline mode.
- No errors were logged in Joomla! or the server error logs.
Expected Behavior & Actual Behavior are same:
- Joomla! should recognize the JOOMLA_OFFLINE environment variable.
- The site should display the "Site is offline" message if the variable is set to 1.
Additional Notes:
- Clearing Joomla! cache and restarting the server did not resolve the issue.
Final Result:
- Patch works as intended; Joomla correctly recognizes the JOOMLA_OFFLINE variable, and the site goes offline as expected. No issues found.
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/44894.
We discussed this at todays maintainers meeting and we think it is a good idea. And now comes the but. But we want to use an industry standard implementation like “phpdotenv” or "https://github.com/symfony/dotenv".
| Category | Administration Installation Libraries Unit Tests | ⇒ | Administration External Library Composer Change Installation Libraries Unit Tests |
@rdeutz, I prefer symfony/dotenv because it supports creating environments: prod, dev, test and etc. I've implemented the loading of .env files, so you can try it now.
| Labels |
Added:
Composer Dependency Changed
|
||
This pull request has been automatically rebased to 6.0-dev.
| Title |
|
||||||
| Category | Administration Installation Libraries Unit Tests External Library Composer Change | ⇒ | Administration SQL com_admin Postgresql com_associations com_banners com_categories com_checkin com_config com_contact com_content com_contenthistory com_cpanel com_fields com_finder com_installer com_joomlaupdate |
| Status | Pending | ⇒ | Closed |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2025-03-04 21:45:50 |
| Closed_By | ⇒ | voronkovich | |
| Labels |
Added:
PR-6.0-dev
Removed: Unit/System Tests Composer Dependency Changed |
||
I accidentally removed the branch while rebasing and the PR closed automatically. I will try to figure out how to reopen it later.
Nice one! One suggestion probably another array with key the JConfig key and value 1 if the value comes from the php file or 0 if the value comes from the env. the reason is that then in the admin configuration the form could check if each input is editable ie coming from the php file (or not ie coming from the env and then add a readonly attribute).