PHP Whitespace Formatter

A whitespace-only PHP formatter. It never touches strings, heredocs, comments, or any non-whitespace token. If it detects a non-whitespace change, it returns the original source unchanged. Requires PHP >= 8.0. Supports full-document and selection formatting.

What it does

Braces & structure

• Cuddled braces: } else { on one line; { pulled up to the if/function/etc. line
• else if → elseif

Parentheses & brackets

• No space between control keywords/function/method names and (: if($x), func($x)
• No space after ( or [, or before ) or ]: func($x), $a['k']
• No space before [ in array access: $arr['key']

Operators

• No space around ->, ?->, ::: $obj->method()
• No space around return type colon: ):array
• Compact operators: $a??$b, $x?:$y, $c?$A:$B

Punctuation

• No space before ,, after ,, or before ;: func($a,$b), $x=1;
• Inside [ ], comma spacing is left untouched so column-aligned array data is preserved: [ 1 , 2 ] stays [1 , 2]. Commas outside brackets (e.g. function-call arguments) still tighten: func(1 , 2) → func(1,2)
• Remove empty statements: $x=1; not $x=1;; (preserves for(;;))

Unary & prefix operators — no space after !, @, ..., or casts: !$x, @func(), f(...$args), (int)$x

Indentation & whitespace

• Re-indentation with consistent depth
• Same-line openers collapse to one indent level: func([ indents contents by 1, not 2
• Trailing whitespace stripped; max 2 consecutive blank lines; single trailing newline

Tab / Spaces

No extension-specific config — the formatter reads your VS Code editor settings:

{
    "editor.insertSpaces": false,
    "editor.tabSize": 4
}

Important: editor.detectIndentation is enabled by default and overrides insertSpaces based on the file's existing whitespace. So if your files already use spaces, VS Code keeps sending "use spaces" even after you switch to tabs. Fix it by disabling detection globally or per-language:

{
    "[php]": {
        "editor.insertSpaces": false,
        "editor.detectIndentation": false
    }
}

The PHP Whitespace Formatter output channel (View → Output → select from dropdown) is used only to report errors (e.g. PHP not found or a non-zero exit); it stays quiet during normal formatting.

Directives

@fmt-off / @fmt-on

Freeze a region so it's left exactly as-is — useful for hand-aligned tables, ASCII art, or intentional whitespace.

// @fmt-off
$map = [
    'key1'   => 'value1',
    'longer' => 'value2',
];
// @fmt-on

Works with //, #, or any comment style. Only text between the markers is frozen; code outside is still formatted. An unterminated @fmt-off is ignored and the rest of the file is formatted as usual.

@fmt-indent-reset

Place on a function's opening { line to reset the indent base to 0, so the block's contents indent relative to column 0 instead of the function's nesting level. Useful for large dispatch functions where an extra indent level across thousands of lines adds no value.

function handleAction($action){ # @fmt-indent-reset
if($action === 'register'){
    validate($action);
}elseif($action === 'login'){
    authenticate($action);
}
}

Safety

The formatter compares the non-whitespace token stream before and after formatting. If anything differs (besides the else if → elseif and ;; → ; normalizations), the original source is returned unchanged. Broken or unparseable PHP is passed through as-is.