Формат YAML

Дата оновлення перекладу 2024-05-29

Формат 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
11
12
13
>
  Це дуже довге речення, яке розтягується в YAML
  на декілька рядків.

# Це буде розібрано наступним чином: (відмітьте завершальний \n)
# "Це дуже довге речення, яке розтягується в 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

Null

Null в YAML можуть бути виражені за допомогою null або ~.

Булеві значення

Булеві значення в YAML виражені за допомогою true та false.

Дати

YAML використовує стандарт ISO-8601 для виразу дат:

1
2001-12-14T21:59:43.10-05:00
1
2
# проста дата
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
# Коментар до рядку
"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
дані:
    # це значення аналізується як рядок (не перетворюється в дату та час)
    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. Цей тег приймає в якості аргументу повне ім'я класу випадку зчислення:

    1
    2
    3
    4
    5
    data:
        # Ви можете використати типований випадок зчислення...
        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.1.

Функції YAML, які не підтримуються

Наступні функції YAML не підтримуються компонентом Symfony Yaml:

  • Мульти-документи (маркери --- та ...);
  • Складні ключі маршрутизації, складні значення, що починаються з ?;
  • Значення, теговані як ключі;
  • Наступні теги та типи: `!!set`, `!!omap`, `!!pairs`, `!!set`, `!!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: ~}).