Configuration reference

The formatter is opinionated and ships sensible PER-CS defaults, but a handful of options let you tune it to a different house style. Everything sits under the [formatter] table.

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

Presets

A preset is a complete bundle of formatter options tuned for a specific coding standard.

[formatter]
preset = "laravel"

Preset	What it is
`default`	PER-CS compliant. Same as the built-in defaults.
`psr-12`	PSR-12 coding standard.
`laravel`	Laravel Pint's `laravel` preset.
`drupal`	Drupal coding standard.

Presets accept a version suffix:

preset = "psr-12@latest"
preset = "psr-12"          # same as @latest

Today only latest is supported. Future Mago releases will allow pinning to specific standard versions.

You can also combine a preset with individual options. The preset provides the base; explicit options override it.

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

Tool-wide options

Option	Type	Default	Description
`preset`	string	none	One of `default`, `psr-12`, `laravel`, `drupal`.
`excludes`	string list	`[]`	Paths or globs the formatter skips. Additive to `source.excludes`.

excludes here adds to the global list. Files matched globally are always excluded; this option lets you exclude additional files from the formatter only.

[source]
excludes = ["cache/**"]                          # excluded from every tool

[formatter]
excludes = ["src/**/AutoGenerated/**/*.php"]     # additionally excluded from formatting

Layout and width

Option	Type	Default	Description
`print-width`	integer	`120`	Maximum line length the printer wraps at.
`tab-width`	integer	`4`	Spaces per indentation level.
`use-tabs`	boolean	`false`	Use tabs instead of spaces.
`end-of-line`	enum	`"lf"`	Line terminator. Values: `auto`, `lf`, `crlf`, `cr`.
`single-quote`	boolean	`true`	Prefer single quotes for strings.
`indent-heredoc`	boolean	`true`	Indent heredoc/nowdoc body to match the surrounding scope (PER-CS 3.0 §10). When false, body and closing label sit at column 0.
`trailing-comma`	boolean	`true`	Add a trailing comma to multi-line arrays, parameter lists, etc.
`remove-trailing-close-tag`	boolean	`true`	Strip the trailing `?>` from files.

Brace placement

Option	Type	Default	Description
`control-brace-style`	enum	`"same-line"`	Braces for control structures.
`following-clause-on-newline`	boolean	`false`	Put `else`, `elseif`, `catch`, `finally` on a new line.
`closure-brace-style`	enum	`"same-line"`	Braces for closures and anonymous classes.
`function-brace-style`	enum	`"next-line"`	Braces for functions.
`method-brace-style`	enum	`"next-line"`	Braces for methods.
`classlike-brace-style`	enum	`"always-next-line"`	Braces for classes, traits, interfaces, enums.

The brace-style enums all accept the same three values:

same-line: opening brace stays on the declaration line.
next-line: opening brace goes on the next line for single-line signatures, but stays on the declaration line when the signature breaks across lines.
always-next-line: opening brace always goes on the next line, even when the signature breaks.

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

public function foo(): string
{
}

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

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

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

Empty bodies

Option	Type	Default	Description
`inline-empty-control-braces`	boolean	`false`	Inline empty control-structure bodies.
`inline-empty-closure-braces`	boolean	`true`	Inline empty closure bodies.
`inline-empty-function-braces`	boolean	`true`	Inline empty function bodies.
`inline-empty-method-braces`	boolean	`true`	Inline empty method bodies.
`inline-empty-constructor-braces`	boolean	`true`	Inline empty constructor bodies.
`inline-empty-classlike-braces`	boolean	`true`	Inline empty class-like bodies.
`inline-empty-anonymous-class-braces`	boolean	`true`	Inline empty anonymous-class bodies.

Method chains

Option	Type	Default	Description
`method-chain-breaking-style`	enum	`"next-line"`	Once a chain breaks, where the call sits. Values: `same-line`, `next-line`.
`first-method-chain-on-new-line`	boolean	`true`	When an object chain (`->`, `?->`) breaks, put the first call on a new line. Static access (`::`) stays attached to its target (PER-CS 4.7).
`method-chain-semicolon-on-next-line`	boolean	`false`	When a multi-line chain is a statement, put the terminating semicolon on its own line.
`preserve-breaking-member-access-chain`	boolean	`false`	Preserve existing line breaks in member-access chains.
`preserve-breaking-member-access-chain-first-method-on-same-line`	boolean	`false`	When preserving a broken chain, keep the first method on the receiver line.

Preserving author breaks

Option	Type	Default	Description
`preserve-breaking-argument-list`	boolean	`false`	Preserve existing line breaks in argument lists.
`preserve-breaking-array-like`	boolean	`true`	Preserve existing line breaks in array-likes.
`preserve-breaking-parameter-list`	boolean	`false`	Preserve existing line breaks in parameter lists.
`preserve-breaking-attribute-list`	boolean	`false`	Preserve existing line breaks in attribute lists.
`preserve-breaking-conditional-expression`	boolean	`false`	Preserve existing line breaks in ternaries.
`preserve-breaking-condition-expression`	boolean	`false`	Preserve existing line breaks in control-structure conditions. When enabled, each boolean operator goes on its own line.
`break-promoted-properties-list`	boolean	`true`	Always break parameter lists with promoted properties.
`parameter-attribute-on-new-line`	boolean	`true`	Put parameter attributes on their own line when the parameter list breaks (PER-CS 12.2).
`line-before-binary-operator`	boolean	`true`	When a binary expression breaks, place the operator on the next line.
`indent-binary-expression-continuation`	boolean	`false`	Indent continuation lines of binary expressions in assignments. Available since 1.19.
`omit-redundant-arithmetic-binary-expression-parentheses`	boolean	`false`	Drop redundant parens around arithmetic when comparison or null coalesce already preserves meaning.
`omit-redundant-bitwise-binary-expression-parentheses`	boolean	`false`	Drop redundant parens around bitwise sub-expressions when precedence already preserves meaning.
`preserve-redundant-logical-binary-expression-parentheses`	boolean	`false`	Keep author-written parens around a logical sub-expression when its parent is also logical.

Argument and parameter alignment

Option	Type	Default	Description
`always-break-named-arguments-list`	boolean	`false`	Always break named-argument lists.
`always-break-attribute-named-argument-lists`	boolean	`false`	Always break named arguments in attributes.
`align-parameters`	boolean	`false`	Column-align multi-line parameter lists by the variable.
`align-named-arguments`	boolean	`false`	Column-align named arguments in multi-line calls and attributes.
`array-table-style-alignment`	boolean	`true`	Use table-style alignment for arrays.
`align-assignment-like`	boolean	`false`	Column-align consecutive assignment-like constructs (variables, multi-line array key/value pairs, properties, constants, enum cases, match arms). Compact inline arrays stay unaligned.

`use` statements

Option	Type	Default	Description
`sort-uses`	boolean	`true`	Sort `use` statements alphabetically.
`sort-class-methods`	boolean	`false`	Order class methods by visibility and type: constructor first, then static methods, then instance methods by visibility, destructor last.
`separate-use-types`	boolean	`true`	Insert a blank line between different kinds of `use`.
`expand-use-groups`	boolean	`true`	Expand grouped `use` statements into individual ones.

Type hints and constructs

Option	Type	Default	Description
`null-type-hint`	enum	`"question"`	How to format nullable types. `null_pipe` rewrites `?T` to `null\|T`, preserving union order. `null_pipe_last` rewrites `?T` to `T\|null` and reorders unions to put `null` last. `question` rewrites `null\|T` and `T\|null` to `?T`.
`parentheses-around-new-in-member-access`	boolean	`false`	Wrap `new` in member access: `(new Foo)->bar()`.
`parentheses-in-new-expression`	boolean	`true`	Add `()` to `new` without arguments: `new Foo()`.
`parentheses-in-exit-and-die`	boolean	`true`	Add `()` to `exit` and `die`.
`parentheses-in-attribute`	boolean	`false`	Add `()` to attributes without arguments.

Whitespace around operators

Option	Type	Default	Description
`space-before-arrow-function-parameter-list-parenthesis`	boolean	`false`	Space before arrow function parameter list.
`space-before-closure-parameter-list-parenthesis`	boolean	`true`	Space before closure parameter list.
`space-before-hook-parameter-list-parenthesis`	boolean	`false`	Space before property-hook parameter list.
`inline-abstract-property-hooks`	boolean	`true`	Keep abstract property hooks (`get;`, `set;`) on one line (PER-CS 4.10).
`space-before-closure-use-clause-parenthesis`	boolean	`true`	Space before closure `use (...)`.
`space-after-cast-unary-prefix-operators`	boolean	`true`	Space after cast operators like `(int)`.
`space-after-reference-unary-prefix-operator`	boolean	`false`	Space after `&`.
`space-after-error-control-unary-prefix-operator`	boolean	`false`	Space after `@`.
`space-after-logical-not-unary-prefix-operator`	boolean	`false`	Space after `!`.
`space-after-bitwise-not-unary-prefix-operator`	boolean	`false`	Space after `~`.
`space-after-increment-unary-prefix-operator`	boolean	`false`	Space after prefix `++`.
`space-after-decrement-unary-prefix-operator`	boolean	`false`	Space after prefix `--`.
`space-after-additive-unary-prefix-operator`	boolean	`false`	Space after unary `+` and `-`.
`space-around-concatenation-binary-operator`	boolean	`true`	Spaces around `.`.
`space-around-assignment-in-declare`	boolean	`false`	Spaces around `=` in `declare`.
`space-within-grouping-parenthesis`	boolean	`false`	Spaces inside grouping parens: `( 1 + 2 )`.

Blank lines

Option	Type	Default	Description
`empty-line-after-control-structure`	boolean	`false`	Blank line after a control structure.
`opening-tag-on-own-line`	boolean	`true`	Put `<?php` on its own line in pure PHP files (PER-CS 3.0). Templates with inline HTML are unaffected.
`empty-line-after-opening-tag`	boolean	`true`	Blank line after `<?php`.
`empty-line-after-declare`	boolean	`true`	Blank line after `declare`.
`empty-line-after-namespace`	boolean	`true`	Blank line after `namespace`.
`empty-line-after-use`	boolean	`true`	Blank line after `use` blocks.
`empty-line-after-symbols`	boolean	`true`	Blank line after top-level symbols.
`empty-line-between-same-symbols`	boolean	`true`	Blank line between consecutive symbols of the same type. Only applies when `empty-line-after-symbols` is true.
`empty-line-after-class-like-open`	boolean	`false`	Blank line after the opening brace of a class-like.
`empty-line-after-class-like-constant`	boolean	`false`	Blank line after a class constant.
`empty-line-before-class-like-close`	boolean	`false`	Blank line before the closing brace of a non-empty class-like.
`empty-line-after-enum-case`	boolean	`false`	Blank line after an enum case.
`empty-line-after-trait-use`	boolean	`false`	Blank line after a trait `use`.
`empty-line-after-property`	boolean	`false`	Blank line after a property.
`empty-line-after-method`	boolean	`true`	Blank line after a method.
`empty-line-before-return`	boolean	`false`	Blank line before a `return`.
`empty-line-before-dangling-comments`	boolean	`true`	Blank line before dangling comments.
`separate-class-like-members`	boolean	`true`	Blank line between different kinds of class member.

Casing

Option	Type	Default	Description
`uppercase-literal-keyword`	boolean	`false`	When true, format `true`, `false`, `null` in UPPERCASE.