Конфігурація Symfony
Дата оновлення перекладу 2024-06-07
Конфігурація Symfony
Файли конфігурації
Додатки Symfony сконфігуровані з файлами, що зберігаються в
каталозі config/
, який за замовчуванням має наступну структуру:
1 2 3 4 5 6
your-project/
├─ config/
│ ├─ packages/
│ ├─ bundles.php
│ ├─ routes.yaml
│ └─ services.yaml
- Файл
routes.yaml
визначає конфігурацію маршрутизації; - Файл
services.yaml
конфігурує сервіси сервіс-контейнеру; - Файл
bundles.php
вмикає/вимикає пакети у вашому додатку. - Каталог
config/packages/
зберігає конфігурацію кожного пакета, встановленого у вашому додатку.
Пакети (які також називаються "bundles" в Symfony і "plugins/modules" в інших проектах) додають готові до використання функції до ваших проектів.
При використанні Symfony Flex , який в додаткаї Symfony ввімкнено
за замовчуванням, пакети оновлюють файл bundles.php
та створюють нові файли в
config/packages/
автоматично під час установки. Наприклад, це файл за замовчуванням,
який створено пакетом "API Platform":
1 2 3 4
# config/packages/api_platform.yaml
api_platform:
mapping:
paths: ['%kernel.project_dir%/src/Entity']
Розділення конфігурації на безліч маленьких файлів лякає деяких новачків в Symfony. Однак ви швидко до них звикнете і вам рідко коли необхідно буде змінювати ці файли після установки пакету.
Tip
Щоб дізнатися все про доступні опції конфігурації, подивіться
довідник конфігурації Symfony або виконайте
команду config:dump-reference
.
Формати конфігурації
На відміну від інших фреймворків, Symfony не змушує вас використовувати конкретний формат для конфігурації додатку. Symfony дозволяє вам обирати між YAML, XML та PHP, і по всій документації Symfony, всі приклади конфігурації будуть продемонстровані в цих трьох форматах.
Між форматами немає практичної різниці. Насправді, Symfony трансформує та кешує їх всі в PHP перед запуском додатку, так що між ними навіть немає різниці у продуктивності.
YAML використовується за замовчуванням при установці пакетів так як він лаконічний та дуже читаний. Ось основні переваги та недоліки кожного формату:
- YAML: простий, чистий та читаний, але не всі IDE підтримують автозаповнення та валідацію для нього. Дізнайтеся про синтаксіс YAML ;
- XML: автозаповнюється/валідується більшістю IDE та нативно аналізується PHP, але інколи генерує конфігурацію, яка вважається надто перевантаженою. Вивчіть синтаксис XML;
- PHP: дуже потужний та дозволяє вам створювати динамічну конфігурацію з масивами або ConfigBuilder .
Note
За замовчуванням, Symfony завантажує файли конфігурації, визначені у форматах YAML
та PHP. Якщо ви визначаєте конфігурацію у форматі XML, оновіть файл src/Kernel.php
,
щоб додати підтримку для розширення файлу .xml
.
Імпорт файлів конфігурації
Symfony завантажує файли конфігурації з використанням компонента Config, який надає просунуті функції, такі як імпорт інших файлів конфігурації, навіть якщо вони використовують інший формат:
1 2 3 4 5 6 7 8 9 10 11 12 13
# config/services.yaml
imports:
- { resource: 'legacy_config.php' }
# глобальні вирази також підтримують завантаження декількох файлів
- { resource: '/etc/myapp/*.yaml' }
# ignore_errors: not_found тихо видаляє помилки у випадку, якщо завантажений файл не існує
- { resource: 'my_config_file.xml', ignore_errors: not_found }
# ignore_errors: true тихо видаляє всі помилки (включно з невірним кодом та не знайдено)
- { resource: 'my_other_config_file.xml', ignore_errors: true }
# ...
Параметри конфігурації
Інколи одне і те саме значення конфігурації використовується в декількох файлах конфігурації.
Замість його повторення, ви можете визначити його як "параметр", що є чимось на кшталт повторно
використовуваного значення конфігурації. За згодою, параметри визначаються під ключем
parameters
в файлі config/services.yaml
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
# config/services.yaml
parameters:
# ім'я параметру - довільний рядок (рекомендовано префікс 'app.'
# для кращої диференціації ваших параметрів від параметрів Symfony).
app.admin_email: 'something@example.com'
# булеві параметри
app.enable_v2_protocol: true
# параметри масиву/колекції
app.supported_locales: ['en', 'es', 'fr']
# параметри бінарного змісту (закодуйте його з допомогою base64_encode())
app.some_parameter: !!binary VGhpcyBpcyBhIEJlbGwgY2hhciAH
# PHP-константи в якості значень параметру
app.some_constant: !php/const GLOBAL_CONSTANT
app.another_constant: !php/const App\Entity\BlogPost::MAX_ITEMS
# ...
Caution
При використанні XML-конфігурації, значення між тегами <parameter>
не обрізаються. Це означає, що значення наступного параметру буде
'\n something@example.com\n'
:
1 2 3
<parameter key="app.admin_email">
something@example.com
</parameter>
Коли він буде визначений, ви можете послатися на значення цього параметру з
будь-якого іншого файлу конфігурації, використовуючи спеціальний синтаксис:
оберніть ім'я параметру в два %
(наприклад, %app.admin_email%
):
1 2 3 4 5 6
# config/packages/some_package.yaml
some_package:
# будь-який рядок, оточений двома %, замінюється цим значенням параметру
email_address: '%app.admin_email%'
# ...
Note
Якщо якесь значення параметру включає в себе символ %
, вам необхідно
екранувати його, додавши ще один %
, щоб Symfony не сприйняла його в якості
посилання на ім'я параметру:
1 2 3 4
# config/services.yaml
parameters:
# Аналізується як 'https://symfony.com/?foo=%s&bar=%d'
url_pattern: 'https://symfony.com/?foo=%%s&bar=%%d'
Дата оновлення перекладу 2023-08-21
Note
У звʼязку з тим, як розвʼязуються параметри, ви не можете використовувати їх для побудови шляхів в імпорті динамічно. Це означає, що щось на кшталт цього працювати не буде:
1 2 3
# config/services.yaml
imports:
- { resource: '%kernel.project_dir%/somefile.yaml' }
Параметри конфігурації дуже розповсюджені в додатках Symfony. Деякі пакети навіть
визначають свої власні параметри (наприклад, при встановленні пакету перекладів, в
файл config/services.yaml
додається новий параметр locale
).
Tip
За угодою, параметри, імена яких починаються з крапки .
(наприклад,
.mailer.transport
), доступні лише під час компіляції контейнера. Вони
корисні при роботі з Передачами Компілятора
для оголошення деяких тимчасових параметрів, які не будуть доступні пізніше у
додатку.
See also
Пізніше в цій статті ви можете прочитати як отримувати параметри конфігурації в контролерах та сервісах .
Середовища конфігурації
У вас є лише один застосунок, але розумієте ви це, чи ні, вам необхідно, щоб він поводив себе по-різному за різних обставин:
- Під час розробки, вам необхідно вести логи усього і мати гарні інструменти налагодження;
- Після запуску у виробництво, вам необхідно, щоб той же застосунок було оптимізовано для швидкості і вело логи тільки для помилок.
Файли, що зберігаються в config/packages/
, використовуються Symfony для конфігурації
сервісів додатку. Іншими словами, ви можете змінити поведінку
додатку, змінивши те, які файли конфігурації завантажуються. В цьому полягає ідея
середовищ конфігурації Symfony.
Типовий застосунок Symfony починається з трьох середовищ:
dev
для локальної розробки,prod
для виробничих серверів,test
для автоматизованих тестів. П
При запуску додатку, Symfony завантажує файли конфігурації в цьому порядку (останні файли можуть перевизначити значення, які були встановлені в попередніх):
- Файли в
config/packages/*.<extension>
; - Файли в
config/packages/<environment-name>/*.<extension>
; config/services.<extension>
;config/services_<environment-name>.<extension>
.
Візьмемо пакет framework
, встановлений за замовчуванням, в якості прикладу:
- Спочатку завантажується
config/packages/framework.yaml
у всіх середовищах та конфігурує фреймворк з деякими опціями; - В середовищі prod не буде встановлено нічого додатково, так як відсутній файл
config/packages/prod/framework.yaml
; - В середовищі dev, також відсутній файл (
config/packages/dev/framework.yaml
не існує). - В середовищі test, файл
config/packages/test/framework.yaml
завантажується для перевизначення деяких з налаштувань, що були раніше сконфігуровані вconfig/packages/framework.yaml
.
В реальності, кожне середовище відрізняється від інших лише трошки. Це означає, що
всі середовища мають спільну базу конфігурації, яка розташовує файли напряму в
каталозі config/packages/
.
Tip
Ви також можете визначити опції для різних середовищ в одному файлі
конфігурації, використовуючи спеціальне ключове слово when
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
# config/packages/webpack_encore.yaml
webpack_encore:
# ...
output_path: '%kernel.project_dir%/public/build'
strict_mode: true
cache: false
# кеш включено лише у середовищі "prod"
when@prod:
webpack_encore:
cache: true
# відключити суворий режим лише у середовищі "test"
when@test:
webpack_encore:
strict_mode: false
# синтаксис YAML дозволяє повторно використовувати зміст, використовуючи "якорі" (&some_name) та "псевдоніми" (*some_name).
# У цьому прикладі, конфігурація 'test' використовує точно таку ж конфігурацію, як і в 'prod'
when@prod: &webpack_prod
webpack_encore:
# ...
when@test: *webpack_prod
See also
Див. також метод configureContainer()
класу Kernel,
щоб дізнатися все про порядок завантаження файлів конфігурації.
Вибір активного середовища
Додатки Symfony мають файл під назвою .env
, який знаходиться в кореневому
каталозі проекту. Цей файл використовується для визначення значення змінних
середовища, та детально пояснюється далі в цій статті.
Відкрийте файл .env
(а краще файл .env.local
, якщо ви його створювали), та
відредагуйте значення змінної APP_ENV
, щоб змінити середовище, в якому працює
застосунок. Наприклад, запустіть застосунок у виробництві:
1 2
# .env (або .env.local)
APP_ENV=prod
Це значення використовується як для веб-команд, так і для консольних. Однак, ви
можете перевизначити його для команд, встановивши значення APP_ENV
до їх запуску:
1 2 3 4 5
# Використовуйте середовище, визначене в файлі .env
$ php bin/console command_name
# Ігноруйте файл .env та виконайте цю команду у виробництві
$ APP_ENV=prod php bin/console command_name
Створення нового середовища
Трьох середовищ наданих Symfony за замовчуванням достатньо для більшості проектів, але
ви також можете визначати власні середовища. Наприклад, ось як ви можете визначити середовище
staging
, де клієнт може тестувати проект до його запуску у виробництво:
- Створіть каталог конфігурації з тим же іменем, що і у середовища (в даному
випадку,
config/packages/staging/
); - Додайте необхідні файли конфігурації в
config/packages/staging/
, щоб визначити поведінку нового середовища. Symfony завантажує файлиconfig/packages/*.yaml
першими, тому вам необхідно сконфігурувати лише різницю в цих файлах; - Оберіть середовище
staging
, використовуючи варіант середовищаAPP_ENV
, як пояснювалося у попередньому розділі.
Tip
Середовища часто схожі одне на одне, тому ви можете використовувати
символьні посилання між каталогами config/packages/<environment-name>/
,
щоб повторно використовувати одну й ту саму конфігурацію.
Замість створення нових середовищ, ви можете використовувати змінні середовища, як
пояснюється у наступному розділі. Таким чином ви можете використовувати однакові
додаток та середовище (наприклад, prod
), але змінити його поведінку завдяки
конфігурації, заснованій на зміннних середовища (наприклад, щоб запустити додаток
в інших сценаріях: постановці, контролю якості, рецензуванні клієнтом тощо).
Конфігурація, заснована на змінних середовища
Використання змінних середовища (або скорочено "env vars") - це розповсюджена практика для конфігурації опцій, які залежать від того, де запускається застосунок (наприклад, ідентифікаційні дані бази даних зазвичай відрізняються у виробництві та на вашій локальній машині). Якщо значення чутливі, ви навіть можете закодувати їх як секретні.
Ви можете послатися на змінні середовища, використовуючи спеціальний синтаксіс
%env(ENV_VAR_NAME)%
. Значення цих опцій дозволяється під час виконання (лише
один раз за запит, щоб не вплинути на этих опций разрешаются во время выполнения
(только единожды за запрос, чтобы не повлиять на продуктивність).
Цей приклад демонструж, як ви можете сконфігурувати з'єднання бази даних, використовуючи змінну середовища:
1 2 3 4 5 6
# config/packages/doctrine.yaml
doctrine:
dbal:
# за згодою, імена змінних середовищ завжди використовують верхній регістр
url: '%env(resolve:DATABASE_URL)%'
# ...
Note
Ваші змінні середовища також можуть бути доступні через супер-глобальні PHP $_ENV
та $_SERVER
(обидва рівнозначні):
1 2
$databaseUrl = $_ENV['DATABASE_URL']; // mysql://db_user:db_password@127.0.0.1:3306/db_name
$env = $_SERVER['APP_ENV']; // prod
Однак, у додатках Symfony немає потреби в їх використанні, так як система конфігурації надає кращий спосіб роботи зі змінними середовища.
See also
Значення змінних середовища можуть бути лише рядками, але Symfony має деякі процесори env var, щоб трансформувати їхній зміст (наприклад, перетворити значення рядку в ціле число).
Щоб визначити значення будь-якої змінної середовища, у вас є декілька варіантів:
- Додати значення до файлу .env ;
- Закодувати значення як секрет ;
- Встановити значення як реальну змінну середовища в вашій оболонці бо веб-сервері.
Якщо ваш додаток намагається використати змінну середовища, яку не було визначено, ви побачите виключення. Ви можете запобігти цьому, визначивши значення за замовчуванням для змінної середовища. Для цього визначте параметр з такою самою назвою, як і змінна середовища, використовуючи цей синтаксис:
1 2 3 4 5 6
# config/packages/framework.yaml
parameters:
# якщо значення SECRET змінної середовища ніде не визначено, Symfony використовує це значення
env(SECRET): 'some_secret'
# ...
Tip
Деякі хостінги - як SymfonyCloud - пропонують прості у виробництві утіліти для роботи з env var
Note
Деякі функції конфігурації несумісні зі змінними середовища. Наприклад, визначення
деяких параметрів контейнера залежно від умов, засновуючись на існуванні іншої опції
конфігурації. При використанні змінної середоовища, опція конфігурації завжди існує,
так як її значення буде null
, якщо повʼязана змінна середовища не визначена.
Danger
Майте на увазі, що скидання змісту змінних $_SERVER
та $_ENV
або виведення
змісту phpinfo()
відобразить значення змінних середовища, оголюючи чутливу
інформацію на кшталт ідентифікаційних даних бази даних.
Значення змінних середовища також розкриваються у веб-інтерфейсі профілювальника Symfony. На практиці це не має бути проблемою, так як веб-профільувальник ніколи не має бути увімкнений у виробництві.
Конфігурація змінних середовища у файлах .env
Замість визначення змінних середовища у вашій оболонці або веб-сервері, Symfony
надає зручний спосіб визначити їх в файлі .env
(починається з крапки), що знаходиться
в корені вашого проекту.
Файл .env
читається та аналізується при кожному запиті і його змінні середовища
додаються до PHP-змінних $_ENV
та $_SERVER
. Всі існуючі змінні середовища
ніколи не перевизначаються значеннями, визначеними в .env
, тому ви можете їх
комбінувати.
Наприклад, щоб визначити змінні середовища DATABASE_URL
, продемонстровані раніше в цій
статті, ви можете додати:
1 2
# .env
DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"
Цей файл має бути надісланий у ваше сховище, і (у зв'язку з цим фактом) має містити лище значення "за замовчуванням", які підохдять для локальної розробки. Цей файл не має містити значень виробництва.
На додаток до ваших власних змінних середовища, цей файл .env
також містить змінні
середовища, визначені сторонніми пакетами, що встановлені в вашому додатку (вони автоматично
додаються Symfony Flex при установці пакетів).
Tip
Так як файл .env
читається та парсується за кожним запитом, вам не потрібно
очищувати кеш Symfony або перезавантажувати PHP контейнер, якщо ви використовуєте
Docker.
Синтаксис файлу .env
Додавайте коментарі з префіксом #
:
1 2 3
# повноваження бази даних
DB_USER=root
DB_PASS=pass # це секретний пароль
Використовуйте змінні середовища в значеннях, додаючи до них префікс $
:
1 2
DB_USER=root
DB_PASS=${DB_USER}pass # додайте користувача в якості префіксу пароля
Caution
Порядок важливий, коли деякі зі змінних середовища залежать від значення інших змінних
середовища. У прикладі вище, DB_PASS
повиен бути визначений після DB_USER
. Більш
того, якщо ви визначаєте декілька файлів .env
та ставите DB_PASS
першим, його
значення залежатиме від значення DB_USER
, визначеного в інших файлах, замість значення,
визначеного у цьому файлі.
Визначте значення за замовчуванням у випадку, якщо змінна середовища не встановлена:
1 2
DB_USER=
DB_PASS=${DB_USER:-root}pass # результати в DB_PASS=rootpass
Вбудуйте команди через $()
(не підтримується у Windows):
1
START_TIME=$(date)
Caution
Використання $()
може не працювати в залежності від вашої оболонки.
Tip
Так як файл .env
- звичайний скрипт оболонки, ви можете source
його
у ваших власних скриптах оболонки:
1
$ source .env
Перевизначення значень середовища через .env.local
Якщо вам потрібно перевизначити значення середовища (наприклад, на інше значення на
вашій локальній машині), ви можете зробити це в файлі .env.local
:
1 2
# .env.local
DATABASE_URL="mysql://root:@127.0.0.1:3306/my_database_name"
Цей файл має бути проігнорований git і не має бути відправлений до вашого сховища.
Декілька інших файлів .env
доступні для установки змінних середовища лише у
правильних ситуаціях:
.env
: визначає значення за замовчуванням для змінних середовища, які необхідні додатку;.env.local
: перевизначає значення за замовчуванням для всіх середовищ, але лише на машині, що містить цей файл. Цей файл не має бути відправлений у сховище, він ігнорується в середовищіtest
(так як тести мають виробляти однакові результати для всіх);.env.<environment>
(наприклад,.env.test
): перевизначає змінні середовища лише для одного середовища, але для всіх машин (ці файли відправляються);.env.<environment>.local
(наприклад,.env.test.local
): визначає змінні середовища, які відносяться до конкретної машини, перевизначаючи їх лише для одного середовища. Схоже на.env.local
, але перевизначення застосовується лише до одного середовища.
Справжні змінні середовища завжди мають перевагу над змінними середовища, створеними будь-яким з файлів
.env
. Зауважте, що ця поведінка залежить від конфігурації
variables_order, яка має містити E
, щоб показати суперглобальну змінну $_ENV
.
Це конфігурація за замовчуванням у PHP.
Файли .env
та .env.<environment>
не повинні бути відправлені в сховище, так як
вони однакові для всіх розробників та машин. Однак, файли env, які закінчуються на
.local
(.env.local
та .env.<environment>.local
) не мають бути відправлені,
так як їх будете використовувати лише ви. Насправді, файл .gitignore
, який постачається
з Symfony, запобігає їхньому відправленню.
Перевизначення змінних середовища, визначених системою
Якщо вам потрібно перевизначити змінну середовища, визначену системою, використовуйте параметр
overrideExistingVars
, визначений методами
loadEnv(),
bootEnv() та
populate():
1 2 3 4 5 6
use Symfony\Component\Dotenv\Dotenv;
$dotenv = new Dotenv();
$dotenv->loadEnv(__DIR__.'/.env', overrideExistingVars: true);
// ...
Це призведе до перевизначення змінних середовища, визначених системою, але не
перевизначить змінні середовища, визначені у файлах .env
.
Конфігурація змінних середовища у виробництві
У виробництві, файли .env
також аналізуються та завантажуються по кожному запиту. Тому
найпростіший спосіб визначити змінні середовища - розгорнути файл .env.local
на вашому
виробничому сервері(ах) з вашими значеннями виробництва.
Для покращення продуктивності, ви можете за бажанням виконати команду Composer dump-env
:
1 2
# аналізує ВСІ файли .env та скидає їх фінальні значення в .env.local.php
$ composer dump-env prod
Після виконання цієї команди, Symfony завантажить файл .env.local.php
, щоб
отримати змінні середовища, і не буде витрачати час, аналізуючи файли .env
.
Tip
Оновіть ваші інструменти/робочий процес, щоб запускати команду dotenv:dump
після
кожного розгортання для покращення продуктивності програми.
Зберігання змінних середовища в інших файлах
За замовчуванням, змінні середовища зберігаються у файлі .env
, розташованому
в корені вашого проекту. Однак, ви можете зберігати їх в інших файлах у
різними способами.
Якщо ви використовуєте компонент Runtime, шлях dotenv
шлях є частиною опцій, які ви можете задати у вашому файлі composer.json
:
1 2 3 4 5 6 7 8 9
{
// ...
"extra": {
// ...
"runtime": {
"dotenv_path": "my/custom/path/to/.env"
}
}
}
Ви також можете встановити змінну середовища SYMFONY_DOTENV_PATH
на системному рівні
(наприклад, у конфігурації вашого веб-сервера або у вашому Docker-файлі):
1 2
# .env (або .env.local)
SYMFONY_DOTENV_PATH=my/custom/path/to/.env
Нарешті, ви можете напряму викликати клас Dotenv
у вашому
bootstrap.php
або будь-якому іншому файлі вашого додатку:
1 2 3
use Symfony\Component\Dotenv\Dotenv;
(new Dotenv())->bootEnv(dirname(__DIR__).'my/custom/path/to/.env');
Після цього Symfony шукатиме змінні середовища у цьому файлі, а також у
локальних та специфічних для середовища файлах (наприклад, .*.local
та
.*.<environment>.local
). Прочитайте
як перевизначити змінні середовища ,
щоб дізнатися більше про це.
7.1
Змінна середовища SYMFONY_DOTENV_PATH
була представлена в Symfony 7.1.
Кодування змінних середовища (секрети)
Замість визначення реальної змінної середовища, або її додавання в файл .env
,
якщо значення змінної чутливе (наприклад, ключ API або пароль БД), ви можете закодувати
значення, використовуючи систему управління секретами.
Перелік змінних середовища
Використовуйте команду debug:dotenv
, щоб розуміти, як Symfony аналізує різні файли
.env
, щоб встановити значення кожної змінної середовища:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
$ php bin/console debug:dotenv
Dotenv змінні та файли
======================
Проскановані файли (в порядку зниження пріорітету)
--------------------------------------------------
* ⨯ .env.local.php
* ⨯ .env.dev.local
* ✓ .env.dev
* ⨯ .env.local
* ✓ .env
Змінні
------
------------ ---------- ---------- ------
Змінна Значення .env.dev .env
------------ ---------- ---------- ------
FOO BAR n/a BAR
ALICE BOB BOB bob
------------ ---------- ---------- ------
# шукати конкретну змінну, що передає своє повне або часткове імʼя в якості аргументу
$ php bin/console debug:dotenv foo
Крім того, незалежно від того, як ви встановили змінні середовища, ви можете бачити всі змінні середовища з їх значеннями, на які є посилання у конфігурації контейнера Symfony, ви також можете побачити кількість випадків використання кожної змінної середовища у контейнері:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
$ php bin/console debug:container --env-vars
------------ --------------------------- ------------------------------------ -----------------------
Імʼя Значення за замовчуванням Справжнє значення Кількість використань
------------ --------------------------- ------------------------------------ -----------------------
APP_SECRET n/a "471a62e2d601a8952deb186e44186cb3" 2
BAR n/a n/a 1
BAZ n/a "value" 0
FOO "[1, "2.5", 3]" n/a 1
------------ --------------------------- ------------------------------------ -----------------------
# ви також можете відфільтрувати список env vars за іменем:
$ php bin/console debug:container --env-vars foo
# виконайте цю команду, щоб показати всі деталі для конкретної env var:
$ php bin/console debug:container --env-var=FOO
Створення вашої власної логіки для завантаження змінних середовища
Ви можете реалізувати власну логіку завантаження змінних середовища, якщо поведінка Symfony за замовчуванням не відповідає вашим потребам. Для цього створіть сервіс, клас якого реалізує EnvVarLoaderInterface.
Note
Якщо ви використовуєте конфігурацію services.yaml за замовчуванням ,
функція автоконфігурації увімкне і тегує цей сервіс автоматично. В іншому випадку, вам
потрібно зареєструвати і тегувати ваш сервіс
тегом container.env_var_loader
.
Припустимо що у вас є JSON-файл з ім'ям env.json
, який містить ваші змінні середовища:
1 2 3 4 5 6
{
"vars": {
"APP_ENV": "prod",
"APP_DEBUG": false
}
}
Ви можете визначити клас на зразок наступного JsonEnvVarLoader
для заповнення
змінних середовища з файлу:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
namespace App\DependencyInjection;
use Symfony\Component\DependencyInjection\EnvVarLoaderInterface;
final class JsonEnvVarLoader implements EnvVarLoaderInterface
{
private const ENV_VARS_FILE = 'env.json';
public function loadEnvVars(): array
{
$fileName = __DIR__.\DIRECTORY_SEPARATOR.self::ENV_VARS_FILE;
if (!is_file($fileName)) {
// викликати виключення або просто проігнорувати цей завантажувач, залежно від ваших потреб
}
$content = json_decode(file_get_contents($fileName), true);
return $content['vars'];
}
}
Ось і все! Тепер додаток буде шукати файл env.json
у поточному каталозі
для заповнення змінних середовища (на додачу до
вже існуючих файлів .env
).
Tip
Якщо ви хочете, щоб змінна середовища мала значення у певному середовищі, але користуватися резервом завантажувачів в іншому середовищі, призначте порожнє значення змінній середовища для середовища, у якому ви хочете використовувати завантажувачі:
1 2 3 4 5
# .env (або .env.local)
APP_ENV=prod
# .env.prod (або .env.prod.local) - це використовуватиме резерв тих завантажувачів, які ви визначили
APP_ENV=
Доступ до параметрів конфігурації
Контролери та сервіси можуть отримати доступ до всіх параметрів конфігуацрії. Це включає в себе як параметри, визначені вами , так і параметри, створені пакетами. Виконайте наступну команду, щоб побачити всі параметри, які існують у вашому додатку:
1
$ php bin/console debug:container --parameters
У контролерах, що розширюються з AbstractController ,
використовуйте хелпер getParameter()
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
// src/Controller/UserController.php
namespace App\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
class UserController extends AbstractController
{
// ...
public function index(): Response
{
$projectDir = $this->getParameter('kernel.project_dir');
$adminEmail = $this->getParameter('app.admin_email');
// ...
}
}
У сервісах та контролерах, які не розширюються з AbstractController
, впровадьте
параметри в якості аргументів їх конструкторів. Ви маєте впровадити їх чітко, тому що
автоматичне впровадження сервісів не працює для
параметрів:
1 2 3 4 5 6 7 8
# config/services.yaml
parameters:
app.contents_dir: '...'
services:
App\Service\MessageGenerator:
arguments:
$contentsDir: '%app.contents_dir%'
Якщо ви будете вроваджувати одні й ті самі параметри знов і знов, використовуйте
замість цього опцію services._defaults.bind
. Аргументи, визначені в цій опції,
впроваджуються автоматично кожного разу, коли конструктор сервісу або дія контролера
визначає аргумент з точно таким же іменем. Наприклад, щоб впроваджувати значення
параметра kernel.project_dir , кожний раз,
коли сервіс/контролер визначає аргумень $projectDir
, використовуйте це:
1 2 3 4 5 6 7 8 9
# config/services.yaml
services:
_defaults:
bind:
# передайте це значення будь-якому аргументу $projectDir для будь-якого сервісу,
# створеного в цьому файлі (включно з аргументами контролера)
$projectDir: '%kernel.project_dir%'
# ...
See also
Прочитайте статтю про об'єднання аргументів за іменем та/або типом , щоб дізнатися більше про цю потужну функцію.
Нарешті, якщо якомусь сервісу необхідний доступ до багатьох параметрів, замість впровадження кожного з них окремо, ви можете впровадити всі параметри додатку одночасно, додавши підказки при введені коду до будь-якого з аргументів конструктора з ContainerBagInterface:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
// src/Service/MessageGenerator.php
namespace App\Service;
// ...
use Symfony\Component\DependencyInjection\ParameterBag\ContainerBagInterface;
class MessageGenerator
{
public function __construct(
private ContainerBagInterface $params,
) {
}
public function someMethod(): void
{
// отримайте будь-який параметр контейнеру з $this->params, який зберігає їх всі
$sender = $this->params->get('mailer_sender');
// ...
}
}
Використання PHP ConfigBuilders
Написання PHP-конфігурації інколи буває складним, тому що у вас виходять великі вкладені масиви, і у вас немає допомоги а автозаповнюванні з вашого улюбленого IDE. Це можна вирішити з допомогою "ConfigBuilders". Це об'єкти, які допоможуть вам будувати ці масиви.
Symfony генерує класи ConfigBuilder автоматично в
каталозі будови ядра для всіх пакетів,
встановлених у вашому додатку. За згодою, вони всі живуть в просторі імен
Symfony\Config
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
// config/packages/security.php
use Symfony\Config\SecurityConfig;
return static function (SecurityConfig $security): void {
$security->firewall('main')
->pattern('^/*')
->lazy(true)
->security(false);
$security
->roleHierarchy('ROLE_ADMIN', ['ROLE_USER'])
->roleHierarchy('ROLE_SUPER_ADMIN', ['ROLE_ADMIN', 'ROLE_ALLOWED_TO_SWITCH'])
->accessControl()
->path('^/user')
->roles('ROLE_USER');
$security->accessControl(['path' => '^/admin', 'roles' => 'ROLE_ADMIN']);
};
Note
Тільки кореневі класи в просторі імен Symfony\Config
є ConfigBuilders. Вкладені
конфігурації (наприклад,
) є звичайними PHP
об'єктами, які не впроваджуються автоматично під час їх використання в якості типу
аргументу.
Note
Для того, щоб отримати автозаповнення ConfigBuilders у вашому IDE/редакторі, переконайтеся,
що ви не виключили каталог, в якому генеруються ці класи (за замовчуванням,
var/cache/dev/Symfony/Config/
).
Не зупиняйтесь!
Вітаємо! Ви впоралися з основами Symfony. Далі, дізнайтеся про кожну частину Symfony окремо, слідуючи посібникам. Подивіться:
- Форми
- Бази даних та Doctrine ORM
- Сервіс-контейнер
- Security
- Відправлення листів за допомогою Mailer
- Логування
І всі інші теми, пов'язані з конфігурацією:
- Як організувати файли конфігурації
- Зміни в .env від листопада 2018 року та як оновитися
- Процесори змінних середовища
- Процесори змінних середовища
- Як встановлювати зовнішні параметри в сервіс-контейнері
- Розуміння того, як працюють фронт-контролер, ядро та середовища разом
- Побудова власного фреймворку з MicroKernelTrait
- Як створити декілька додатків Symfony з одним ядром
- Як перевизначити структуру каталогів Symfony за замовчуванням
- Як зробити чутливу інформацію секретною
- Використання параметрів у класі впровадження залежностей