codemix / yii2-configloader
Build configuration arrays from config files and env vars.
Installs: 105 846
Dependents: 0
Suggesters: 0
Security: 0
Stars: 61
Watchers: 14
Forks: 5
Open Issues: 0
Requires
- php: ^7.1.3 || ^8.0
- vlucas/phpdotenv: ^5.0
- yiisoft/yii2: *
Requires (Dev)
- phpunit/phpunit: >4.0 <8
This package is auto-updated.
Last update: 2024-11-05 20:34:11 UTC
README
Build configuration arrays from config files and environment variables.
Features
You can use this extension to solve some or all of the following tasks:
- Build Yii2 configuration arrays for web and console application
- Initialize Yii environment (
YII_DEBUG
,YII_ENV
) from environment variables - Load environment variables from a
.env
file - Get config options from environment variables
- Load local configuration overrides
- Streamline config initialization and Yii 2 bootstrapping
Installation
Install the package with composer:
composer require codemix/yii2-configloader
Description
We mainly use this extension to configure our dockerized yii2 applications. It's good practice to build your docker applications in such a way, that the runtime configuration in productive mode happens solely via environment variables.
But during local development we can loosen these strict requirement a little as we sometimes have to add debug options or the like that should not be part of the main configuration. Here the extension helps to override settings with local configuration files that live outside of version control.
You have several options how to use this extension:
- Use only the Yii environment initialization
- Use only the configuration loader
- Use both
We first show how to use the first two options "standalone" and then a third, combined way that includes all features.
1. Initializing Yii environment
This will set the YII_DEBUG
and YII_ENV
variables according to the respective
environment variables if those are set. It can also load them from a .env
file.
In debug mode error_reporting()
will also be set to E_ALL
.
<?php use codemix\yii2confload\Config; Config::initEnv('/path/to/app'); $setting = Config::env('MY_SETTING', 'default');
If you leave away the application path, no .env
file will be loaded.
2. Loading configuration
If want to load your configuration with this extenstion, the following naming scheme must be followed:
config/web.php
- Web configurationconfig/console.php
- Console configurationconfig/local.php
- Local overrides for the web configuration (optional)config/local-console.php
- Local overrides for the console configuration (optional)
If you only want to load configuration from files but whithout initializing the Yii
environments as shown above, you'd create a Config
instance and pass the application
base directory and, as second argument, false
to the constructor:
<?php use codemix\yii2confload\Config; $config = new Config('/path/to/app', false); // Reads configuration from config/web.php $webConfig = $config->web();
2.1 Local configuration
By default local configuration files local.php
and local-console.php
are not
loaded. To activate this feature you can either set the ENABLE_LOCALCONF
environment
variable (either in your server environment or in .env
):
ENABLE_LOCALCONF=1
Now the methods will return the corresponding merged results:
web()
:config/web.php
+config/local.php
console()
:config/console.php
+config/local-console.php
Alternatively you can explicitely ask for local configuration:
<?php use codemix\yii2confload\Config; $config = new Config('/path/to/app', false); // Merges configuration from config/web.php and config/local.php if present $webConfig = $config->web([], true); // Merges configuration from config/console.php and config/local-console.php if present $consoleConfig = $config->console([], true);
2.2 Merging custom configuration
You can also inject some other configuration when you fetch the web or console config:
<?php use codemix\yii2confload\Config; $config = new Config('/path/to/app', false); $webConfig = $config->web(['id' => 'test'], true);
3. Initialize Yii environment and load configuration
Let's finally show a full example that demonstrates how to use all the mentioned features in one go. A typical setup will use the following files:
.env
Here we define the Yii environment and DB credentials. You'd add more config options in the same manner:
YII_DEBUG=1
YII_ENV=dev
DB_DSN=mysql:host=db.example.com;dbname=web
DB_USER=user
DB_PASSWORD='**secret**'
config/web.php
This file is later included in the scope of codemix\yii2confload\Config
, so you
can easily access instance and class methods:
<?php /* @var codemix\yii2confload\Config $this */ return [ 'components' => [ 'db' => [ 'dsn' => self::env('DB_DSN', 'mysql:host=db;dbname=web'), 'username' => self::env('DB_USER', 'web'), 'password' => self::env('DB_PASSWORD', 'web'), ],
config/console.php
Having access to the config instance allows for example to reuse parts of your web configuration in your console config.
<?php /* @var codemix\yii2confload\Config $this */ $web = $this->web(); return [ // ... 'components' => [ 'db' => $web['components']['db'],
web/index.php
We've streamlined the process of setting up a Config
object and loading the
Yii 2 bootstrap file into a single method Config::boostrap()
which only
receives the application directory as argument.
<?php use codemix\yii2confload\Config; require(__DIR__ . '/../vendor/autoload.php'); $config = Config::bootstrap(__DIR__ . '/..'); Yii::createObject('yii\web\Application', [$config->web()])->run();
This makes sure that things are loaded in the right order. If you prefer a more verbose version, the code above is equivalent to:
<?php use codemix\yii2confload\Config; require(__DIR__ . '/../vendor/autoload.php'); $config = new Config(__DIR__ . '/..'); require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php'); Yii::createObject('yii\web\Application', [$config->web()])->run();
yii
The same approach is used for the console application:
<?php use codemix\yii2confload\Config; require(__DIR__ . '/vendor/autoload.php'); $config = Config::bootstrap(__DIR__); $application = Yii::createObject('yii\console\Application', [$config->console()]); exit($application->run());