YAML 格式

编辑此页

Symfony Yaml 组件 实现了 YAML 1.2 版本规范 中定义的精选功能子集。

标量

标量的语法与 PHP 语法类似。

字符串

YAML 中的字符串可以用单引号和双引号包裹。在某些情况下，它们也可以不加引号

1
2
3
4
5
A string in YAML

'A single-quoted string in YAML'

"A double-quoted string in YAML"

当字符串以一个或多个相关空格开始或结束时，带引号的样式很有用，因为在解析其内容时，未加引号的字符串会在两端被修剪。当字符串包含特殊字符或保留字符时，需要使用引号。

当使用单引号字符串时，内容中的任何单引号 ' 都必须加倍以进行转义

1
'A single quote '' inside a single-quoted string'

包含以下任何字符的字符串必须用引号引起来：: { } [ ] , & * # ? | - < > = ! % @ 虽然可以使用双引号，但对于这些字符，使用单引号更方便，这样可以避免转义任何反斜杠 \。

双引号样式提供了一种表示任意字符串的方法，通过使用 \ 来转义字符和序列。例如，当需要在字符串中嵌入 \n 或 Unicode 字符时，它非常有用。

1
"A double-quoted string in 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
>
  This is a very long sentence
  that spans several lines in the YAML.

# This will be parsed as follows: (notice the trailing \n)
# "This is a very long sentence that spans several lines in the YAML.\n"

>-
  This is a very long sentence
  that spans several lines in the YAML.

# This will be parsed as follows: (without a trailing \n)
# "This is a very long sentence that spans several lines in the YAML."

注意

请注意前面示例中每行之前的两个空格。它们不会出现在生成的 PHP 字符串中。

数字

1
2
# an integer
12
1
2
# an octal
0o14
1
2
# an hexadecimal
0xC
1
2
# a float
13.4
1
2
# an exponential number
1.2e+34
1
2
# infinity
.inf

Null 值

YAML 中的 Null 值可以用 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'];

注意

在映射中，键可以是任何有效的标量。

冒号和值之间的空格数无关紧要

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 } # Comment at the end of a line
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

注意

YAML 解析器会忽略注释，并且不需要根据集合中当前的嵌套级别进行缩进。

显式类型

YAML 规范定义了一些标签来显式设置任何数据的类型

1
2
3
4
5
6
7
8
9
10
11
12
13
data:
    # this value is parsed as a string (it's not transformed into a DateTime)
    start_date: !!str 2002-12-14

    # this value is parsed as a float number (it will be 3.0 instead of 3)
    price: !!float 3

    # this value is parsed as binary data encoded in 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:
    # You can use the typed enum case...
    operator_type: !php/enum App\Operator\Enum\Type::Or
    # ... or you can also use "->value" to directly use the value of a BackedEnum case
    operator_type: !php/enum App\Operator\Enum\Type::Or->value

    此标签允许省略枚举案例，仅提供枚举 FQCN 以返回所有可用枚举案例的数组

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

    7.1

    Symfony 7.1 中引入了对使用枚举 FQCN 而不指定案例的支持。

不支持的 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: ~}）。
本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。
目录
    版本