Компонент Yaml в Symfony
Компонент Yaml
Одна из целей Symfony Yaml — найти правильный баланс между скоростью работы и функционалом. Он поддерживает только те функции, которые необходимы для работы с файлами конфигурации, способен обрабатывать большую часть спецификации YAML для любых нужд, связанных с настройкой.
Symfony Yaml-компонент реализует часть функций, определенных в спецификации версии YAML 1.2
Компонент YAML использует метод serialize() в PHP для создания строкового представления объекта.
Компонент Symfony Yaml состоит из двух основных классов: один анализирует строки YAML (Parser), а другой преобразует массив PHP в строку YAML (Dumper).
Если при разборе кода yaml возникает ошибка, парсер выдает исключение ParseException с указанием типа ошибки и строки в исходной строке YAML, в которой произошла ошибка
#Преобразование строки в массив php
$value = Yaml::parse("foo: bar");
Метод parseFile() анализирует содержимое YAML в указанном файле и преобразует его в значение PHP
$value = Yaml::parseFile('/path/to/file.yaml');
Метод dump() преобразует любой массив PHP в его представление в формате YAML
Если во время дампа возникает ошибка, парсер выдает исключение DumpException
use Symfony\Component\Yaml\Yaml;
$array = [
'foo' => 'bar',
'bar' => ['foo' => 'bar', 'bar' => 'baz'],
];
$yaml = Yaml::dump($array);
file_put_contents('/path/to/file.yaml', $yaml);
Формат YAML поддерживает два вида представления массивов: развернутое и встроенное. По умолчанию дампер использует развернутое представление.
#Развернутое представление
foo: bar
bar:
foo: bar
bar: baz
#Встроенное представление
foo: bar
bar: { foo: bar, bar: baz }
Отступ
По умолчанию компонент YAML использует 4 пробела для отступа.
foo: bar
bar:
foo: bar
bar: baz
Числовые Литералы
В YAML-файлах можно добавлять символы подчеркивания для улучшения читаемости:
При разборе содержимого YAML все символы _ удаляются из числовых литералов
parameters:
credit_card_number: 1234_5678_9012_3456
long_number: 10_000_000_000
Обработка даты
По умолчанию парсер YAML преобразует строки без кавычек, которые выглядят как дата или дата и время, в метку времени Unix
Yaml::parse('2016-05-27'); // 1464307200
#Or
$date = Yaml::parse('2016-05-27', Yaml::PARSE_DATETIME);
Выгрузка многострочных литеральных блоков
В YAML несколько строк могут быть представлены в виде литеральных блоков. По умолчанию дампер кодирует несколько строк как встроенную строку
Синтаксический анализ перечислений PHP
Парсер YAML поддерживает перечисления PHP
По умолчанию они анализируются как обычные строки
$yaml = '{ foo: FooEnum::Foo, bar: !php/enum FooEnum::Foo->value }';
$parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
// $parameters = ['foo' => 'FooEnum::Foo', 'bar' => 'foo'];
Разбор и сохранение пользовательских тегов
Помимо встроенной поддержки таких тегов, как !php/const и !!binary, вы можете создавать собственные теги YAML и анализировать их с помощью флага PARSE_CUSTOM_TAGS
Выдача числовых ключей в виде строк
По умолчанию ключи массива, состоящие только из цифр, выводятся как целые числа. Если вы хотите вывести ключи только в виде строк, используйте флаг DUMP_NUMERIC_KEY_AS_STRING:
$dumped = Yaml::dump([200 => 'foo'], 2, 4, Yaml::DUMP_NUMERIC_KEY_AS_STRING);
// '200': foo
Выгрузка коллекции карт
При выгрузке коллекций карт в формате YAML компонент использует дефис в отдельной строке в качестве разделителя:
planets:
-
name: Mercury
distance: 57910000
-
name: Jupiter
distance: 778500000
Строки в YAML могут быть заключены как в одинарные, так и в двойные кавычки
Кавычки необходимы, если строка содержит специальные или зарезервированные символы.
Стиль с двойными кавычками позволяет использовать \ для экранирования символов и последовательностей
Если строка содержит разрывы строк, можно использовать литеральный стиль, обозначаемый вертикальной чертой (|), чтобы указать, что строка будет занимать несколько строк.
Кроме того, строки можно записывать в свернутом виде, обозначая их символом >, где каждый разрыв строки заменяется пробелом
Пустые значения
Пустые значения в YAML можно обозначить с помощью null или ~.
Булевы значения
Булевы значения в YAML обозначаются символами true и false.
Даты
В YAML для обозначения дат используется стандарт ISO-8601
2001-12-14T21:59:43.10-05:00
# simple date
2002-12-14
Коллекции
Коллекции в YAML могут представлять собой последовательность (индексированные массивы в PHP) или набор элементов (ассоциативные массивы в PHP).
#В последовательностях используется дефис, за которым следует пробел:
- PHP
- Perl
- Python
#Предыдущий файл YAML эквивалентен следующему коду на PHP:
['PHP', 'Perl', 'Python'];
#В сопоставлениях для обозначения каждой пары «ключ-значение» используется двоеточие и пробел
PHP: 5.2
MySQL: 5.1
Apache: 2.2.20
#Это эквивалентно следующему коду на PHP:
['PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20'];
Количество пробелов между двоеточием и значением не имеет значения
#В YAML для описания вложенных коллекций используются отступы в один или несколько пробелов:
'symfony 1.0':
PHP: 5.0
Propel: 1.2
'symfony 1.2':
PHP: 5.2
Propel: 1.3
#Приведенный выше YAML-код эквивалентен следующему коду на PHP:
[
'symfony 1.0' => [
'PHP' => 5.0,
'Propel' => 1.2,
],
'symfony 1.2' => [
'PHP' => 5.2,
'Propel' => 1.3,
],
];
При использовании отступов в файле YAML нужно помнить одну важную вещь: отступы должны быть сделаны с помощью одного или нескольких пробелов, но ни в коем случае не с помощью табуляции.
#Последовательность можно записать в виде списка, разделенного запятыми, в квадратных скобках
[PHP, Perl, Python]
#Сопоставление можно записать в виде списка ключей и значений, разделенных запятыми и заключенных в фигурные скобки ({}):
{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }
Явное указание типа
#Это значение обрабатывается как строка (а не преобразуется в DateTime)
start_date: !!str 2002-12-14
#Это значение обрабатывается как число с плавающей запятой (вместо 3 будет 3,0)
price: !!float 3
Дополнительные возможности
!php/const позволяет получить значение константы PHP. В качестве аргумента этот тег принимает полное имя класса константы:
data:
page_limit: !php/const App\Pagination\Paginator::PAGE_LIMIT
!php/object позволяет передать сериализованное представление объекта PHP (созданного с помощью функции serialize()), которое будет десериализовано при разборе файла YAML:
my_object: !php/object 'O:8:"stdClass":1:{s:3:"bar";i:2;}'
!php/enum позволяет использовать перечисление PHP enum case. Этот тег принимает в качестве аргумента полное имя класса перечисления case:
operator_type: !php/enum App\Operator\Enum\Type::Or
Префикс @= используется компонентом внедрения зависимостей для внедрения значений, вычисляемых с помощью выражений. В файлах конфигурации YAML любая строка, начинающаяся с @=, рассматривается как выражение:
arguments:
- '@=service("App\\Mail\\MailerConfiguration").getMailerMethod()'
Как внедрить значения на основе сложных выражений.
https://symfony.com/doc/current/service_container/expression_language.html
Дополнительный источник
https://yaml.org/spec/1.2.2/