+++ title = "格式化器配置参考" description = "mago.toml 中 [formatter] 下可设置的所有选项。" nav_order = 50 nav_section = "工具" nav_subsection = "Formatter" +++

配置参考

格式化器是有主见的,默认值即为合理的 PER-CS,但少量选项让你可以调整为不同的团队风格。所有项都位于 [formatter] 表下。

[formatter]
print-width = 100
use-tabs = true

预设

预设是为某种编码标准量身打包的一整套格式化器选项。

[formatter]
preset = "laravel"

预设	含义
`default`	兼容 PER-CS。等同于内置默认值。
`psr-12`	PSR-12 编码标准。
`laravel`	Laravel Pint 的 `laravel` 预设。
`drupal`	Drupal 编码标准。

预设支持版本后缀:

preset = "psr-12@latest"
preset = "psr-12"          # 等同于 [@latest](https://github.com/latest)

目前仅支持 latest。未来的 Mago 版本将允许锁定到具体的标准版本。

你也可以把预设与单独的选项组合使用。预设提供基础,显式选项会覆盖它。

[formatter]
preset = "laravel"
print-width = 140

工具级选项

选项	类型	默认值	说明
`preset`	字符串	无	`default`、`psr-12`、`laravel`、`drupal` 之一。
`excludes`	字符串列表	`[]`	格式化器跳过的路径或 glob。叠加在 `source.excludes` 之上。

这里的 excludes 是在全局列表之上叠加。被全局匹配到的文件总是会被排除;此选项只能让你额外为格式化器排除一些文件。

[source]
excludes = ["cache/**"]                          # 对所有工具排除

[formatter]
excludes = ["src/**/AutoGenerated/**/*.php"]     # 额外对格式化器排除

布局与宽度

选项	类型	默认值	说明
`print-width`	整数	`120`	打印器进行换行的最大行长。
`tab-width`	整数	`4`	每级缩进所占空格数。
`use-tabs`	布尔值	`false`	使用制表符而非空格。
`end-of-line`	枚举	`"lf"`	行尾。取值:`auto`、`lf`、`crlf`、`cr`。
`single-quote`	布尔值	`true`	字符串优先使用单引号。
`indent-heredoc`	布尔值	`true`	缩进 heredoc/nowdoc 的主体以匹配外层作用域(PER-CS 3.0 §10)。设为 false 时,主体和闭合标签位于第 0 列。
`trailing-comma`	布尔值	`true`	在多行数组、参数列表等末尾添加尾随逗号。
`remove-trailing-close-tag`	布尔值	`true`	去除文件末尾的 `?>`。

大括号位置

选项	类型	默认值	说明
`control-brace-style`	枚举	`"same-line"`	控制结构的大括号。
`following-clause-on-newline`	布尔值	`false`	把 `else`、`elseif`、`catch`、`finally` 放到新行。
`closure-brace-style`	枚举	`"same-line"`	闭包和匿名类的大括号。
`function-brace-style`	枚举	`"next-line"`	函数的大括号。
`method-brace-style`	枚举	`"next-line"`	方法的大括号。
`classlike-brace-style`	枚举	`"always-next-line"`	类、trait、接口、枚举的大括号。

大括号样式枚举均接受相同的三个值:

same-line:左大括号留在声明所在行。
next-line:对于单行签名,左大括号放到下一行;签名跨行换行时,左大括号留在声明行。
always-next-line:左大括号始终放到下一行,即使签名换行也是如此。

method-brace-style = "next-line" 时:

public function foo(): string
{
}

public function bar(
    string $veryLongParam,
): string {
}

method-brace-style = "always-next-line" 时:

public function bar(
    string $veryLongParam,
): string
{
}

空主体

选项	类型	默认值	说明
`inline-empty-control-braces`	布尔值	`false`	内联空的控制结构主体。
`inline-empty-closure-braces`	布尔值	`true`	内联空的闭包主体。
`inline-empty-function-braces`	布尔值	`true`	内联空的函数主体。
`inline-empty-method-braces`	布尔值	`true`	内联空的方法主体。
`inline-empty-constructor-braces`	布尔值	`true`	内联空的构造函数主体。
`inline-empty-classlike-braces`	布尔值	`true`	内联空的类型主体。
`inline-empty-anonymous-class-braces`	布尔值	`true`	内联空的匿名类主体。

方法链

选项	类型	默认值	说明
`method-chain-breaking-style`	枚举	`"next-line"`	一旦链断开,调用所在的位置。取值:`same-line`、`next-line`。
`first-method-chain-on-new-line`	布尔值	`true`	当对象链(`->`、`?->`)断开时,把第一个调用放到新行。静态访问(`::`)保持附着在其目标上(PER-CS 4.7)。
`method-chain-semicolon-on-next-line`	布尔值	`false`	当多行链是一条语句时,把终结的分号放到独立的一行。
`preserve-breaking-member-access-chain`	布尔值	`false`	保留成员访问链中已有的换行。
`preserve-breaking-member-access-chain-first-method-on-same-line`	布尔值	`false`	保留断开链时,把第一个方法保留在接收者所在行。

保留作者的换行

选项	类型	默认值	说明
`preserve-breaking-argument-list`	布尔值	`false`	保留参数列表(实参)中已有的换行。
`inline-single-breaking-value-argument`	布尔值	`false`	当调用的唯一实参是一个值(字面量、变量、标识符、类常量)时,即使整行超过 `print-width` 也保持在同一行。对这种实参拆开括号只会多出一个换行、一层缩进和一行单独的右括号,而不会让长值变短。对多实参调用,或本身就是调用、数组、闭包的实参没有效果。在 `tempest` 预设中默认开启,其他预设默认关闭。
`preserve-breaking-array-like`	布尔值	`true`	保留数组类结构中已有的换行。
`preserve-breaking-parameter-list`	布尔值	`false`	保留形参列表中已有的换行。
`preserve-breaking-attribute-list`	布尔值	`false`	保留 attribute 列表中已有的换行。
`preserve-breaking-conditional-expression`	布尔值	`false`	保留三元表达式中已有的换行。
`preserve-breaking-condition-expression`	布尔值	`false`	保留控制结构条件中已有的换行。启用时,每个布尔运算符放在独立的一行。
`break-promoted-properties-list`	布尔值	`true`	始终对包含构造器属性提升的形参列表进行换行。
`parameter-attribute-on-new-line`	布尔值	`true`	形参列表换行时,把形参 attribute 放到独立的一行(PER-CS 12.2)。
`line-before-binary-operator`	布尔值	`true`	二元表达式换行时,把运算符放到下一行。
`indent-binary-expression-continuation`	布尔值	`false`	在赋值语句中缩进二元表达式的续行。自 1.19 起可用。
`omit-redundant-arithmetic-binary-expression-parentheses`	布尔值	`false`	当比较或空合并已能保留语义时,去除算术运算外多余的括号。
`omit-redundant-bitwise-binary-expression-parentheses`	布尔值	`false`	当优先级已能保留语义时,去除位运算子表达式外多余的括号。
`preserve-redundant-logical-binary-expression-parentheses`	布尔值	`false`	当父表达式也是逻辑表达式时,保留作者在逻辑子表达式外书写的括号。

实参与形参对齐

选项	类型	默认值	说明
`always-break-named-arguments-list`	布尔值	`false`	始终对命名实参列表换行。
`always-break-attribute-named-argument-lists`	布尔值	`false`	始终对 attribute 中的命名实参换行。
`align-parameters`	布尔值	`false`	按变量进行多行形参列表的列对齐。
`align-named-arguments`	布尔值	`false`	在多行调用和 attribute 中对命名实参进行列对齐。
`array-table-style-alignment`	布尔值	`true`	对数组使用表格风格对齐。
`align-assignment-like`	布尔值	`false`	对连续的赋值类构造(变量、多行数组键值对、属性、常量、枚举 case、match 分支)进行列对齐。紧凑的内联数组保持不对齐。

`use` 语句

选项	类型	默认值	说明
`sort-uses`	枚举	`"alpha-ascending"`	控制 `use` 语句的排序方式。取值:`preserve`（别名 `as-is`、`none`、`keep`、`false`）、`alphanumeric-ascending`（别名 `alpha-ascending`、`ascending`、`true`）、`alphanumeric-descending`（别名 `alpha-descending`、`descending`）、`length-ascending`、`length-descending`。按长度排序时按源码中 use 语句的码点数计算；长度相同的语句以 `alphanumeric-ascending` 作为次级排序，保证输出稳定。
`sort-class-methods`	布尔值	`false`	按可见性和类型排序类方法:构造函数在前,然后是静态方法,然后按可见性排序的实例方法,析构函数在最后。
`separate-use-types`	布尔值	`true`	在不同种类的 `use` 之间插入空行。
`expand-use-groups`	布尔值	`true`	把分组的 `use` 语句展开为单独的语句。

类型提示和构造

选项	类型	默认值	说明
`null-type-hint`	枚举	`"question"`	如何格式化可空类型。`null_pipe` 把 `?T` 重写为 `null\|T`,保留联合的顺序。`null_pipe_last` 把 `?T` 重写为 `T\|null`,并将联合中的 `null` 放到末尾。`question` 把 `null\|T` 和 `T\|null` 重写为 `?T`。
`parentheses-around-new-in-member-access`	布尔值	`false`	在成员访问中包裹 `new`:`(new Foo)->bar()`。
`parentheses-in-new-expression`	布尔值	`true`	为没有实参的 `new` 添加 `()`:`new Foo()`。
`parentheses-in-exit-and-die`	布尔值	`true`	为 `exit` 和 `die` 添加 `()`。
`parentheses-in-attribute`	布尔值	`false`	为没有实参的 attribute 添加 `()`。

运算符周围的空白

选项	类型	默认值	说明
`space-before-arrow-function-parameter-list-parenthesis`	布尔值	`false`	箭头函数参数列表前的空格。
`space-before-closure-parameter-list-parenthesis`	布尔值	`true`	闭包参数列表前的空格。
`space-before-hook-parameter-list-parenthesis`	布尔值	`false`	属性钩子参数列表前的空格。
`inline-abstract-property-hooks`	布尔值	`true`	把抽象属性钩子(`get;`、`set;`)保留在一行(PER-CS 4.10)。
`space-before-closure-use-clause-parenthesis`	布尔值	`true`	闭包 `use (...)` 前的空格。
`space-after-cast-unary-prefix-operators`	布尔值	`true`	类似 `(int)` 的转换运算符之后的空格。
`space-after-reference-unary-prefix-operator`	布尔值	`false`	`&` 之后的空格。
`space-after-error-control-unary-prefix-operator`	布尔值	`false`	`@` 之后的空格。
`space-after-logical-not-unary-prefix-operator`	布尔值	`false`	`!` 之后的空格。
`space-after-bitwise-not-unary-prefix-operator`	布尔值	`false`	`~` 之后的空格。
`space-after-increment-unary-prefix-operator`	布尔值	`false`	前缀 `++` 之后的空格。
`space-after-decrement-unary-prefix-operator`	布尔值	`false`	前缀 `--` 之后的空格。
`space-after-additive-unary-prefix-operator`	布尔值	`false`	一元 `+` 和 `-` 之后的空格。
`space-around-concatenation-binary-operator`	布尔值	`true`	`.` 周围的空格。
`space-around-assignment-in-declare`	布尔值	`false`	`declare` 中 `=` 周围的空格。
`space-within-grouping-parenthesis`	布尔值	`false`	分组括号内部的空格:`( 1 + 2 )`。

空行

选项	类型	默认值	说明
`empty-line-after-control-structure`	布尔值	`false`	控制结构之后的空行。
`opening-tag-on-own-line`	布尔值	`true`	在纯 PHP 文件中,把 `<?php` 放到独立的一行(PER-CS 3.0)。带有内联 HTML 的模板不受影响。
`empty-line-after-opening-tag`	布尔值	`true`	`<?php` 之后的空行。
`empty-line-after-declare`	布尔值	`true`	`declare` 之后的空行。
`empty-line-after-namespace`	布尔值	`true`	`namespace` 之后的空行。
`empty-line-after-use`	布尔值	`true`	`use` 块之后的空行。
`empty-line-after-symbols`	布尔值	`true`	顶层符号之后的空行。
`empty-line-between-same-symbols`	布尔值	`true`	同种类型连续符号之间的空行。仅当 `empty-line-after-symbols` 为 true 时生效。
`empty-line-after-class-like-open`	布尔值	`false`	类型左大括号之后的空行。
`empty-line-after-class-like-constant`	布尔值	`false`	类常量之后的空行。
`empty-line-before-class-like-close`	布尔值	`false`	非空类型右大括号之前的空行。
`empty-line-after-enum-case`	布尔值	`false`	枚举 case 之后的空行。
`empty-line-after-trait-use`	布尔值	`false`	trait `use` 之后的空行。
`empty-line-after-property`	布尔值	`false`	属性之后的空行。
`empty-line-after-method`	布尔值	`true`	方法之后的空行。
`empty-line-before-return`	布尔值	`false`	`return` 之前的空行。
`empty-line-before-dangling-comments`	布尔值	`true`	悬挂注释之前的空行。
`separate-class-like-members`	布尔值	`true`	不同种类的类成员之间的空行。
`separate-trait-use`	布尔值	`true`	按 PSR-12 / PER-CS-3 section 4.2 的要求，将 `use FirstTrait, SecondTrait;` 拆分为每个 trait 一条 `use` 语句。仅对不带 `{ ... }` 适配块的抽象 trait-use 生效。
`attributes-order`	枚举	`"preserve"`	声明上 `#[Attribute]` 注解的排序方式。可选值：`preserve`（别名 `as-is`、`none`、`keep`）、`alphanumeric-ascending`（别名 `alpha-ascending`、`ascending`）、`alphanumeric-descending`（别名 `alpha-descending`、`descending`）、`length-ascending`、`length-descending`。按长度排序时按源码中属性名的码点数计算；长度相同的属性以 `alphanumeric-ascending` 作为次级排序，保证输出稳定。此设置只影响运行时 `ReflectionAttribute` 的枚举顺序；如果代码依赖源码顺序，请保持 `preserve`。
`separate-attributes`	布尔值	`false`	将单个 `#[Attr1, Attr2]` 组拆分为多行 `#[Attr1]` `#[Attr2]`。与非 `preserve` 的 `attributes-order` 搭配时，会跨组对所有属性进行全局排序，而非仅在组内排序。

大小写

选项	类型	默认值	说明
`uppercase-literal-keyword`	布尔值	`false`	设为 true 时,把 `true`、`false`、`null` 格式化为大写。

Mago Laravel Package