PHP Symfony Yaml解析多行字符串时要注意什么

Symfony Yaml 解析多行字符串时，真正需要先判断的不是 PHP 语法，而是 YAML 块标量的语义：| 会保留换行，> 会把大多数换行折叠为空格；块内容的缩进又决定了哪些文字仍属于这个字符串。官方地址：https://symfony.com/doc/current/components/yaml.html。

如果文章、邮件模板或证书说明必须保留原有换行，优先使用 literal block；如果只是为了让配置文件分行书写、解析后希望得到一段连续文本，则使用 folded block。下面按这个差异拆开说明。

先区分 | 和 > 的换行语义

这两个符号看起来只是 YAML 的排版选择，解析结果却不同。| 适合 Markdown、邮件正文和带固定段落的模板；> 更适合把较长的描述分行排版，但在 PHP 字符串中按空格连接。

# | 保留块内换行，适合需要段落结构的文本
release_note: |
  第一行说明
  第二行说明

  第三行说明

# > 折叠普通换行，适合希望得到一段连续描述的文本
summary: >
  这是一段较长的配置说明，
  写成多行后仍可读，
  解析结果按折叠规则连接。

| 与 > 只决定块字符串的换行处理，并不替你修正块内缩进。缩进层级必须比键名更深，且同一块的内容保持一致；把下一行缩进得过浅，解析器就可能把它当成新的 YAML 结构。

用 PHP nowdoc 控制输入字符串边界

在 PHP 中把 YAML 写成普通双引号字符串，反斜杠、换行和引号容易互相影响。测试解析规则或把配置放在代码中时，nowdoc 能更接近文件里的原始文本：

  这是第一段，
  这是第二段。
YAML;

// parse 只负责把 YAML 文本转换成 PHP 值，不会把 | 和 > 当普通字符保留
$data = Yaml::parse($yaml);

// 业务层再按字段读取，避免在调用点重复拆分原始文本
printf("%s\n%s\n", $data['message'], $data['summary']);

注意 nowdoc 末尾的结束标记要单独成行，YAML 块内的每一行也要保持一致缩进。把 PHP 代码缩进后直接复制进 YAML，并不会自动替你重新计算块层级；多出来的空格可能会成为解析后字符串的一部分。

给容易被识别为类型的值加引号

多行字符串经常夹带日期、编号或开关文字。Symfony Yaml 文档特别提醒，未加引号且看起来像日期的值默认可能被转换为 Unix 时间戳；true、false、null 和数字样式也可能不再是普通字符串。只要业务含义是“原样文本”，就把它放进引号中。

# 这些字段表达的是文本，就显式使用引号避免类型歧义
version_text: '2026-10-13'
enabled_text: 'false'
ticket_code: '0017'

# 多行块内部仍要保持统一缩进，块值的内容属于 description
description: |
  发布批次：2026-10-13
  状态词：false
  编号：0017

如果确实希望日期被解析成日期时间对象，可以在可信输入上使用 Yaml::PARSE_DATETIME；不要把这个选项当成“所有字段都更准确”的开关。尤其是外部提交的 YAML，不要为了方便启用会解析 PHP 常量或枚举的高权限选项。

读取和生成要使用不同的判断方式

Yaml::parse() 面向读取：重点是块语义、缩进和标量类型。反过来把 PHP 数组生成 YAML 时，默认 Dumper 可能把换行写成带转义的行内字符串；希望输出 literal block 时，要明确传入对应标志：

 "第一行\n第二行\n第三行",
];

// 使用 literal block 选项，让输出 YAML 更适合人工阅读和版本管理
$yaml = Yaml::dump(
    $payload,
    2,
    4,
    Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK,
);

echo $yaml;

因此可以按一个简单规则决策：输入配置需要保留段落，就写 |；输入配置只是长句换行，就写 >；输出配置需要稳定展示多行，就给 Yaml::dump() 增加 DUMP_MULTI_LINE_LITERAL_BLOCK。Symfony Yaml 实现的是 YAML 规范的一个子集，不要把其他 YAML 实现支持的语法直接假设为当前组件可用。

常见追问

为什么使用 > 后，PHP 字符串里的换行少了？

因为 folded block 的设计就是把普通换行折叠为空格。需要保留每一行时改用 |，不要在 PHP 读取后再用字符串替换补换行。

块内容前面的空格会不会被保留？

块的基础缩进由 YAML 层级决定，额外缩进可能成为内容的一部分。最稳妥的做法是让同一块文本使用一致缩进，并用 nowdoc 保持输入边界清晰。

所有多行文本都应该加引号吗？

不需要。块标量本身已经用 | 或 > 表达多行语义；引号主要用于那些可能被识别成日期、布尔值、空值或数字的普通标量。