Формат 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: ~}).