PHP Formatter

PHP Formatter formats your PHP files using a native Rust binary — no Node.js dependencies, no PHP runtime required.

Before / After

  <?php
  
- $name = 'foo';
- $version = '1.0';
- $x = 42;
+ $name    = 'foo';
+ $version = '1.0';
+ $x       = 42;
  
  $arr = [
-     'key' => 1,
-     'longkey' => 2,
+     'key'     => 1,
+     'longkey' => 2,
  ];
  
- $data['setting']= json_encode($this->setting);
- $data['title'] = 'Dashboard';
- $data['list']= $this->model->get();
+ $data['setting'] = json_encode($this->setting);
+ $data['title']   = 'Dashboard';
+ $data['list']    = $this->model->get();

Features

• = alignment — aligns consecutive assignments: $var, typed params (string $x = …), typed constants (const string FOO = …)
• => alignment — aligns fat arrows in array literals and match expressions
• Inline comment alignment — aligns // comments that appear on consecutive lines
• HTML structural indentation — re-indents mixed PHP/HTML view files (CodeIgniter, Laravel plain views); auto-detected, zero config
• UTF-8 safe — accented characters (á, é, ñ…), emojis and CJK preserved correctly
• @fmt-off / @fmt-on — skip formatting for a region; @formatter:off / @formatter:on (PhpStorm syntax) also supported
• Presets — psr12, per-cs, laravel apply curated rule groups in one line
• Format on save — opt-in via setting
• Preview diff — see what would change before applying, using VS Code's native diff editor
• Format selection — format only the highlighted code
• Format workspace / folder — parallel bulk formatting via rayon (single binary call)
• Problems panel integration — opt-in diagnostics with Quick Fix support
• Per-project config — .phpfmt.toml; generate a full commented template with PHP Formatter: Create .phpfmt.toml
• Status bar timing — shows how long the last format took (e.g. ⌚ PHP fmt: 8ms)
• Native binary — single self-contained executable; no PHP, no Composer, no Node.js at runtime

Installation

From the VS Code Marketplace

Search for PHP Formatter in the Extensions panel (Ctrl+Shift+X) and click Install.

Or from the command line:

code --install-extension local.php-formatter

From a VSIX file

Download the .vsix from the Releases page, then:

code --install-extension php-formatter-0.1.0.vsix

Or: Extensions panel → ··· menu → Install from VSIX…

Note: do not open the .vsix by double-clicking — Windows associates that extension with Visual Studio, not VS Code.

Usage

Format document

Format on save

Enable in VS Code settings:

// settings.json
{
    "phpFormatter.formatOnSave": true
}

Or per project in .phpfmt.toml (takes precedence over the VS Code setting):

[on_save]
enabled = true

Skip a region

// @fmt-off
$matrix = [[1,0,0],[0,1,0],[0,0,1]];  // leave this untouched
// @fmt-on

Both @fmt-off / @fmt-on and @formatter:off / @formatter:on are recognised.

Configuration

VS Code settings

All settings live under the phpFormatter namespace.

.phpfmt.toml (per-project)

Generate a fully-commented template from the Command Palette:

PHP Formatter: Create .phpfmt.toml

Or from the terminal:

php_formatter --init-config /path/to/project

Full reference (all defaults shown):

# ── Preset (optional) ────────────────────────────────────────────────────────
# Applies a curated group of rules. Per-field values below take precedence.
# Available: psr12 | per-cs | laravel
#
# [preset]
# name = "laravel"

[style]
# indent_size          = 4     # Spaces per indent level (1–16)
# normalize_keywords   = false # TRUE→true, FALSE→false, NULL→null
# lowercase_casts      = false # (INT)→(int), (STRING)→(string) …
# no_extra_blank_lines = false # Collapse 2+ blank lines into 1
# strip_import_slash   = false # use \App\Models\User → use App\Models\User
# format_html          = true  # Re-indent HTML in mixed PHP/HTML view files

[align]
# assignments     = true  # Align = in consecutive assignment blocks
# fat_arrows      = true  # Align => in arrays and match expressions
# inline_comments = true  # Align // comments at end of lines

Examples

Variable alignment

<?php

// before
$name = 'Alice';
$age = 30;
$email = 'alice@example.com';

// after
$name  = 'Alice';
$age   = 30;
$email = 'alice@example.com';

Array alignment

<?php

// before
$config = [
    'host' => 'localhost',
    'port' => 3306,
    'database' => 'mydb',
    'charset' => 'utf8mb4',
];

// after
$config = [
    'host'     => 'localhost',
    'port'     => 3306,
    'database' => 'mydb',
    'charset'  => 'utf8mb4',
];

Mixed block (assignments + inline comments)

<?php

// before
$data['setting'] = json_encode($this->setting); // global config
$data['list'] = $this->model->get(); // rows
$data['title'] = 'Dashboard'; // page title

// after
$data['setting'] = json_encode($this->setting);  // global config
$data['list']    = $this->model->get();           // rows
$data['title']   = 'Dashboard';                   // page title

Supported Platforms

The published .vsix bundles the Windows x86-64 binary. For other platforms, build the binary from source (see Contributing) and point phpFormatter.binaryPath to it.

Contributing

Requirements

• Rust (stable, 1.70+)
• Node.js 18+ and npm (for the VS Code extension)
• VS Code 1.85+

Clone and build

git clone https://github.com/eder-rimarachinr/vscode-extension-php-formater-rust.git
cd php-formatter

Build the Rust binary:

cd php-formatter        # Rust crate directory
cargo build --release
# Output: target/release/php_formatter  (or .exe on Windows)

Copy the binary into the extension:

# Windows
copy target\release\php_formatter.exe ..\vscode-extension\bin\

# macOS / Linux
cp target/release/php_formatter ../vscode-extension/bin/

Build the VS Code extension:

cd ../vscode-extension
npm install
npm run compile
npx vsce package          # produces php-formatter-x.y.z.vsix

Project structure

php-formatter/                  Rust binary (cargo project)
├── src/
│   ├── main.rs                 Entry point — legacy + --json dispatch
│   ├── formatter.rs            Line struct, format pipeline
│   ├── config.rs               Config struct, .phpfmt.toml discovery
│   ├── protocol.rs             BinaryRequest / BinaryResponse types
│   └── rules/
│       ├── align.rs            = alignment
│       ├── align_arrows.rs     => alignment
│       ├── align_comments.rs   Inline comment alignment
│       ├── frozen.rs           @fmt-off / @fmt-on regions
│       ├── indent.rs           Indentation normalisation
│       └── spacing.rs          Operator and comma spacing
├── Cargo.toml
└── .cargo/config.toml          Linker config (uses rust-lld)

vscode-extension/               VS Code extension (TypeScript)
├── src/
│   └── extension.ts            Activation, commands, providers
├── bin/
│   └── php_formatter.exe       Bundled release binary (Windows)
├── package.json
└── tsconfig.json

Running the binary directly

The binary accepts PHP via stdin (legacy mode) or a JSON request on stdin (--json mode):

# Legacy: pipe source, get formatted source on stdout
echo '<?php $a = 1; $foo = 2;' | php_formatter

# JSON mode: send a request object, receive a response object
echo '{"command":"format","source":"<?php $a=1;\n$foo=2;\n"}' | php_formatter --json

# Check mode: returns diagnostics without modifying source
echo '{"command":"check","source":"<?php $a=1;\n"}' | php_formatter --json

Changelog

v0.4.0

Rust engine

• HTML structural indentation — mixed PHP/HTML view files (CodeIgniter, Laravel plain views, Symfony templates) are re-indented based on HTML tag depth; auto-detected, zero config; can be disabled with format_html = false
• UTF-8 fix — accented characters (á, é, ñ…) and other multi-byte sequences no longer corrupted during formatting
• PHP 8.3 typed class constants — alignment support for public const string FOO = 'bar'
• PHP 8.4 property hooks — all forms: inline { get => expr; }, multi-line, full-body set(Type $v) { … }, abstract { get; }, promoted in constructor
• PHP 8.4 asymmetric visibility — public private(set) pass-through (no corruption)
• PHP 8.5 pipe operator — |> pass-through
• Typed parameter / property alignment — string $name = 'default' and public string $prop = '' align as a separate group from plain $var assignments
• Presets — psr12, per-cs, laravel activate curated rule groups with a single line
• Individual config toggles — all rules now settable per-project in [style]: normalize_keywords, lowercase_casts, no_extra_blank_lines, strip_import_slash, format_html
• --init-config — generates a fully-commented .phpfmt.toml template
• --format-dir — parallel multi-file formatting via rayon; incremental SHA-256 cache skips unchanged files; --no-cache, --dry-run, --jobs N flags
• --check — CI mode: exit 0 (clean) / 1 (needs formatting) / 2 (error)
• --print-config — shows the active config as JSON for any file
• Diagnostic classification — Problems panel shows rule codes: FMT-INDENT, FMT-SPACING, FMT-ALIGN, FMT-KW, FMT-CAST, FMT-IMPORT
• Hexagonal architecture: domain / adapters / infrastructure separation

VS Code extension

• PHP Formatter: Create .phpfmt.toml command — generates commented config template, offers to open the file immediately
• Workspace/folder formatting now uses --format-dir (single binary call, rayon-parallel) instead of per-file spawning
• Dynamic workspace roots: new folders added during a session are picked up automatically
• build-local npm script to compile and install the Rust binary in one step

v0.3.3

• Fixed binary integrity check (checksums.txt had placeholder hashes)

v0.3.2

• Updated README with correct repository links

v0.3.1

• Added extension icon

v0.3.0

• JSON protocol between extension and binary (--json mode)
• => alignment for arrays and match expressions
• Inline // comment alignment in consecutive blocks
• @fmt-off / @fmt-on region exclusion (PhpStorm @formatter:off also supported)
• Format on save (phpFormatter.formatOnSave)
• Preview diff before applying (PHP Formatter: Preview Format)
• Format selection
• Per-project .phpfmt.toml configuration with full validation
• Problems panel diagnostics with Quick Fix (phpFormatter.diagnostics)
• Bulk format: workspace and folder (PHP Formatter: Format All PHP Files in Workspace)
• Status bar timing (⌚ PHP fmt: Nms)

v0.1.0 — Initial release

• = alignment for consecutive assignment blocks
• Indentation normalisation (tabs → spaces)
• Spacing normalisation around operators and commas
• Bundled Windows x86-64 binary
• VS Code formatter provider (Shift+Alt+F)

Upcoming

• macOS and Linux bundled binaries

License

MIT License.