Формат YAML

Дата обновления перевода 2024-07-25

Формат YAML

Компонент Symfony Yaml реализует избранное подмножество функций, определенных в `спецификации YAML версии 1.2`.

Скаляры

Синтаксис скаляров аналогичен синтаксису PHP.

Строки

Строки в YAML могут быть заключены как в одинарные, так и в двойные кавычки. В некоторых случаях они также могут быть без кавычек:

1
2
3
4
5
Строка в YAML

'Строка в YAML с одинарными кавычками'

" Строка в YAML с двойными кавычками"

Стили с кавычками полезны, когда строка начинается или заканчивается одним или несколькими соответствующими пробелами, потому что строки без кавычек обрезаются с обоих концов при анализе их содержимого содержимого. Кавычки требуются, если строка содержит специальные или зарезервированные символы.

При использовании строк с одинарными кавычками, любая одинарная кавычка ' внутри ее содержимого должна быть удвоена, чтобы экранировать ее:

1
'Одинарные кавычку '' внутри строки с одинарными кавычками'

Строки, содержащие любой из следующих символов, должны быть заключены в кавычки: : { } [ ] , & * # ? | - < > = ! % @ Хотя вы можете использовать двойные кавычки, для этих символов удобнее использовать одинарные кавычки, что позволяет избежать необходимости экранирования обратного слеша \.

Стиль двойных кавычек предоставляет возможность выражать произвольные строки, используя \ для экранирования символов и последовательностей. Например, он очень полезен когда нужно вставить в строку символ \n или символ Unicode.

1
"Строка с двойными кавычками в YAML\n"

Если строка содержит любой из следующих управляющих символов, он должен быть экранирован двойными кавычками:

\0, \x01, \x02, \x03, \x04, \x05, \x06, \a, \b, \t, \n, \v, \f, \r, \x0e, \x0f, \x10, \x11, \x12, \x13, \x14, \x15, \x16, \x17, \x18, \x19, \x1a, \e, \x1c, \x1d, \x1e, \x1f, \N, \_, \L, \P

Наконец, есть и другие случаи, когда строки должны быть заключены в кавычки, независимо от того. используете ли вы одинарные или двойные кавычки:

  • Когда строка имеет значение true'' или false`` (в противном случае она будет рассматриваться как булево значение);
  • Когда строка является null или ~ (в противном случае она будет рассматриваться как значение null);
  • Когда строка выглядит как число, например, целые числа (например, 2, 14 и т. д.), плавающие (например, 2.6, 14.9) и экспоненциальные числа (например, 12e7 и т. д.) (в противном случае она будет рассматриваться как числовое значение);
  • Если строка выглядит как дата (например, 2014-12-31) (в противном случае она будет автоматически преобразуется во временную метку Unix).

Если строка содержит разрывы строк, вы можете использовать литеральный стиль, обозначенный символом трубы (|), чтобы указать, что строка будет охватывать несколько строк. В литералах новые строки сохраняются:

1
2
3
|
  \/ /| |\/| |
  / / | |  | |__

Кроме того, строки можно записывать в свернутом стиле, обозначаемом >, где каждый разрыв строки заменяется пробелом:

1
2
3
4
5
6
7
8
9
10
>
  Это очень длинное предложение
  которое занимает несколько строк в YAML.

# Это будет проанализировано следующим образом: (обратите внимание на \n)
# "Это очень длинное предложение, которое занимает несколько строк в YAML.\n"

>-
  Это очень длинное предложение
  которое занимает несколько строк в YAML.

Note

Обратите внимание на два пробела перед каждой строкой в предыдущих примерах. Они не появятся в результирующих строках PHP.

Числа

1
2
# целое число
12
1
2
# восьмеричное число
0o14
1
2
# шестнадцатиричное число
0xC
1
2
# плавающее число
13.4
1
2
# экспоненциальное число
1.2e+34
1
2
# бесконечность
.inf

Нули

Нули в YAML можно выразить с помощью null или ~.

Булевые значения

Булевые значения в YAML выражаются с помощью true и false.

Даты

В YAML для выражения дат используется стандарт ISO-8601:

1
2001-12-14T21:59:43.10-05:00
1
2
# simple date
2002-12-14

Коллекции

YAML-файл редко используется для описания простого скаляра. Чаще всего он описывает коллекцию. Коллекции YAML могут быть последовательностью (индексированные массивы в PHP) или отображением элементов (ассоциативные массивы в PHP).

В последовательностях используется тире, за которым следует пробел:

1
2
3
- PHP
- Perl
- Python

Предыдущий YAML-файл эквивалентен следующему PHP-коду:

1
['PHP', 'Perl', 'Python'];

В сопоставлениях для обозначения каждой пары ключ/значение используется двоеточие, за которым следует пробел (:):

1
2
3
PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

что эквивалентно этому PHP-коду:

1
['PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20'];

Note

В отображении ключ может быть любым валидным скаляром.

Количество пробелов между двоеточием и значением не имеет значения:

1
2
3
PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

В YAML используются отступы с одним или несколькими пробелами для описания вложенных коллекций:

1
2
3
4
5
6
'symfony 1.0':
  PHP:    5.0
  Propel: 1.2
'symfony 1.2':
  PHP:    5.2
  Propel: 1.3

Приведенный выше YAML эквивалентен следующему PHP-коду:

1
2
3
4
5
6
7
8
9
10
[
    'symfony 1.0' => [
        'PHP'    => 5.0,
        'Propel' => 1.2,
    ],
    'symfony 1.2' => [
        'PHP'    => 5.2,
        'Propel' => 1.3,
    ],
];

Есть одна важная вещь, которую нужно помнить при использовании отступов в YAML-файле: Отступы должны быть сделаны с помощью одного или нескольких пробелов, но никогда с помощью табуляции.

Вы можете вложить последовательности и сопоставления как угодно:

1
2
3
4
5
6
'Chapter 1':
  - Introduction
  - Event Types
'Chapter 2':
  - Introduction
  - Helpers

YAML также может использовать стили потока для коллекций, используя явные индикаторы, а не отступы для обозначения области видимости.

Последовательность может быть записана в виде списка, разделенного запятыми и заключенного в квадратные скобки ([]):

1
[PHP, Perl, Python]

Отображение может быть записано в виде списка ключей/значений, разделенных запятыми и заключенных в фигурные скобки ({}):

1
{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

Вы можете смешивать и сочетать стили, чтобы добиться лучшей читабельности:

1
2
'Chapter 1': [Introduction, Event Types]
'Chapter 2': [Introduction, Helpers]
1
2
'symfony 1.0': { PHP: 5.0, Propel: 1.2 }
'symfony 1.2': { PHP: 5.2, Propel: 1.3 }

Комментарии

Комментарии можно добавлять в YAML, добавляя к ним префикс в виде хеш-знака (#):

1
2
3
# Comment on a line
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Прокомментировать в конце строки
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

Note

Комментарии игнорируются парсером YAML и не нуждаются в отступах в соответствии с текущим уровнем вложенности коллекции.

Явная типизация

Спецификация YAML определяет некоторые теги для явного задания типа любых данных:

1
2
3
4
5
6
7
8
9
10
11
12
13
data:
    # это значение анализируется как строка (не преобразуется в DateTime)
    start_date: !!str 2002-12-14

    # это значение анализируется как плавающее число (будет 3.0 вместо 3)
    price: !!float 3

    # это значение анализируется как бинарные данные, зашифрованные в base64
    picture: !!binary |
        R0lGODlhDAAMAIQAAP//9/X
        17unp5WZmZgAAAOfn515eXv
        Pz7Y6OjuDg4J+fn5OTk6enp
        56enmleECcgggoBADs=

Сепциальные функции Symfony

Компонент Yaml предоставляет некоторые дополнительные функции, которые не являются частью официальной спецификации YAML, но полезны в приложениях Symfony:

  • !php/const позволяет получить значение PHP-константы. Этот тег принимает полное имя класса константы в качестве аргумента:

    1
    2
    data:
        page_limit: !php/const App\Pagination\Paginator::PAGE_LIMIT
  • !php/object позволяет передать сериализованное представление PHP-объекта (созданного с помощью функции serialize()), который будет десериализован при анализе YAML-файла:

    1
    2
    data:
        my_object: !php/object 'O:8:"stdClass":1:{s:3:"bar";i:2;}'
  • !php/enum позволяет использовать регистр PHP enum. Этот тег принимает имя класса регистра исчисления в качестве аргумента:

    1
    2
    3
    4
    5
    data:
        # Вы можете использовать типизированный случай enum...
        operator_type: !php/enum App\Operator\Enum\Type::Or
        # ... или вы также можете использовать "->value" напрямую, используя значение случая BackedEnum
        operator_type: !php/enum App\Operator\Enum\Type::Or->value

    Этот тег позволяет опустить случай исчисления и предоставить только исчисление FQCN, чтобы вернуть массив всех доступных исчислений:

    1
    2
    data:
        operator_types: !php/enum App\Operator\Enum\Type

    7.1

    Поддержка использования исчисления FQCN без указания случая была введена в Symfony 7.

Неподдерживаемые функци YAML

Компонент Symfony Yaml не поддерживает следующие функции YAML:

  • Мультидокументы (маркеры --- и ...);
  • Сложные ключи отображения и сложные значения, начинающиеся с ?;
  • Тегированные значения в качестве ключей;
  • Следующие теги и типы: !!set, !!omap, !!pairs, !!seq, !!bool, !!int, !!merge, !!null, !!timestamp, !!value, !!yaml;
  • Теги (директива TAG; пример: %TAG ! tag:example.com,2000:app/) и ссылки на теги (пример: !<tag:example.com,2000:app/foo>);
  • Использование синтаксиса, похожего на последовательность, для отображения элементов (пример: {foo, bar}; используйте {foo: ~, bar: ~} вместо этого).