Documentation menu
On this page
Components · v2.x
Config
The Config component loads every YAML file of config/ into one tree of dotted keys.
Values can use placeholders for environment variables, kernel parameters and other configuration keys.
Module
| Manager | NeoPHP\Component\Config\ConfigManager (final) |
| Interface | NeoPHP\Component\Config\ConfigManagerInterface |
| Attribute | #[Component(provider: ConfigProvider::class, requires: [YamlManager::class])] |
| Requires | Yaml |
| Required by | Kernel, Routing, Service, View |
Inject ConfigManagerInterface in a service, a command or a controller:
use NeoPHP\Component\Config\ConfigManagerInterface;
public function __construct(private ConfigManagerInterface $config)
{
}
The kernel requires this module: it is always loaded and cannot be disabled in config/config.php.
The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.
Environment files
The kernel loads, in this order (later files override earlier ones):
| File | Committed | Purpose |
|---|---|---|
.env |
yes | default values |
.env.local |
no | local overrides (not loaded when APP_ENV=test) |
.env.{APP_ENV} |
yes | values for one environment (.env.prod, .env.test...) |
.env.{APP_ENV}.local |
no | local overrides for one environment |
Real environment variables (server, Docker...) always win over the files.
APP_NAME="My application"
APP_ENV=dev
APP_DEBUG=1
DATABASE_URL="mysql://${DB_USER}@localhost/app"
| Variable | Default | Description |
|---|---|---|
APP_ENV |
dev |
environment name |
APP_DEBUG |
true unless APP_ENV=prod |
shows the detailed error page |
APP_SECRET |
none | key used to sign cookies |
APP_URL |
none | base URL of the absolute URLs generated in the console (framework.app.url) |
APP_TIMEZONE |
PHP date.timezone |
default timezone of PHP and of the database sessions (framework.app.timezone) |
DATABASE_URL |
sqlite:///%kernel.root_path%/var/data.db |
URL of the default database connection |
php bin/neo install creates .env; when .env already exists, it adds the missing variables (with their comments) and keeps the others.
YAML files
Every *.yaml / *.yml file of config/ is loaded, except routes.yaml, config/routes/ and services.yaml. The key is the file path:
| File | Key |
|---|---|
config/framework/app.yaml |
framework.app |
config/packages/mail.yaml |
packages.mail |
name: '%env(APP_NAME)%'
secret: '%env(APP_SECRET)%'
url: '%env(APP_URL)%'
Reading values
<?php
declare(strict_types=1);
namespace App\Controller;
use NeoPHP\Component\Config\ConfigManagerInterface;
use NeoPHP\Component\Controller\Contract\AbstractController;
use NeoPHP\Component\Http\Response\Response;
class AboutController extends AbstractController
{
public function show(ConfigManagerInterface $config): Response
{
return $this->render('about', [
'name' => $config->get('framework.app.name'),
'port' => $config->get('packages.mail.port', 25),
]);
}
}
In a template, the config($key, $default = null) view helper:
{{ config('framework.app.name') }}
<?= $this->e($this->config('framework.app.name')) ?>
A service can receive a value with #[Autowire(config: 'framework.app.name')] (see the Container documentation).
Placeholders
Placeholders can be used in every YAML file, routes.yaml included:
host: '%env(MAIL_HOST)%'
port: '%env(int:MAIL_PORT)%'
secure: '%env(bool:MAIL_SECURE)%'
from: 'noreply@%env(MAIL_HOST)%'
templates: '%kernel.templates_path%/emails'
app_name: '%framework.app.name%'
discount: '10%%'
| Placeholder | Value |
|---|---|
%env(NAME)% |
environment variable (string) |
%env(int:NAME)%, %env(float:NAME)%, %env(bool:NAME)% |
environment variable cast to a type |
%env(json:NAME)%, %env(csv:NAME)% |
environment variable decoded as JSON / split on commas |
%kernel.root_path% |
project root directory |
%kernel.config_path% |
config/ directory |
%kernel.public_path% |
public/ directory |
%kernel.templates_path% |
templates/ directory |
%kernel.cache_path% |
var/cache/ directory |
%kernel.environment% |
APP_ENV |
%kernel.debug% |
debug mode (bool) |
%kernel.version% |
NeoPHP version |
%any.config.key% |
value of another configuration key |
%% |
a literal % |
Only %env(...)% and keys containing a dot (%kernel.root_path%, %framework.app.name%) are placeholders: %datetime% or %type% are kept as is.
A value made of a single placeholder keeps its type ('%kernel.debug%' is a bool).
PHP API
NeoPHP\Component\Config\ConfigManagerInterface (implemented by ConfigManager):
| Method | Description |
|---|---|
get(string $key, mixed $default = null): mixed |
value of a dotted key |
has(string $key): bool |
whether the key exists |
set(string $key, mixed $value): void |
sets a value (not persisted) |
all(): array |
the whole tree |
loadDirectory(string $directory, array $exclude = []): static |
loads every YAML file of a directory, keyed by path |
loadFile(string $file, string $key = '', bool $resolve = true): static |
loads one file under $key (merged with the existing value; root when empty); its values can reference each other |
resolve(mixed $value): mixed |
resolves the placeholders of a value or an array |
$config->loadFile('/path/to/extra.yaml', 'packages.extra');
$path = $config->resolve('%kernel.root_path%/var');
Exceptions
NeoPHP\Component\Config\Exception\ConfigException is thrown for an undefined environment variable or configuration key in a placeholder, and for a YAML file that does not contain a mapping.
Changelog
- v2.2.0 —
APP_TIMEZONE/framework.app.timezone. - v2.0.1 — Bugfix: an escaped
%%stays a literal%when the value is referenced by another placeholder or the configuration is loaded again (it was resolved a second time); a file loaded withloadFile()can reference its own keys. - v2.0.0 —
ConfigManageris thefinalentry point of the module, declared with#[Component];ConfigManagerInterfacereplacesContract\ConfigInterface;Contract\AbstractConfigis merged into the manager; the internal classes are marked@internal. - Bugfix after v1.17.0 —
framework.app.url/APP_URLfor absolute URLs outside of an HTTP request. - v1.11.0 —
neo installadds the missing variables to an existing.env. - v1.2.0 —
config()view helper, usable with PHP and Twig templates. - v1.0.0 — Configuration:
.envfiles,config/**/*.yaml, placeholders%kernel.*%,%env(...)%and%config.key%.