README

pretty-php is a fast, deterministic, minimally configurable code formatter for PHP.

By taking responsibility for the whitespace in your code, pretty-php makes it easier to focus on the content, providing time and mental energy savings that accrue over time.

Code formatted by pretty-php produces the smallest diffs possible and looks the same regardless of the project you're working on, eliminating visual dissonance and improving the speed and effectiveness of code review.

You can use pretty-php as a standalone tool, run it from your editor, pair it with a linter, or add it to your CI workflows. Configuration is optional in each case.

If you have questions or feedback, I'd love to hear from you.

pretty-php isn't stable yet, so updates may introduce formatting changes that affect your code.

Features

• Supports code written for PHP 8.4 and below (when running on a PHP version that can parse it)
• Code is formatted for readability, consistency and small diffs
• With few exceptions, previous formatting is ignored, and nothing in the original file other than whitespace is changed
• Entire files are formatted in place
• Formatting options are deliberately limited (pretty-php is opinionated so you don't have to be)
• Configuration via a simple JSON file is supported but not required
• PHP's embedded tokenizer is used to parse input and validate output
• Formatted and original code are compared for equivalence
• Output is optionally compliant with PSR-12 and PER (details here)

Installation

Requirements

• Linux, macOS or Windows
• PHP 8.4, 8.3, 8.2, 8.1, 8.0 or 7.4 with the standard tokenizer, mbstring and json extensions enabled

PHP archive (PHAR)

pretty-php is distributed as a PHP archive you can download and run:

wget -O pretty-php.phar https://github.com/lkrms/pretty-php/releases/latest/download/pretty-php.phar

php pretty-php.phar --version

The PHAR can be made executable:

chmod +x pretty-php.phar

./pretty-php.phar --version

Official releases distributed via GitHub are signed and can be verified as follows:

wget -O pretty-php.phar https://github.com/lkrms/pretty-php/releases/latest/download/pretty-php.phar
wget -O pretty-php.phar.asc https://github.com/lkrms/pretty-php/releases/latest/download/pretty-php.phar.asc
gpg --recv-keys 0xE8CC5BC780B581F2
gpg --verify pretty-php.phar.asc pretty-php.phar

Installation with PHIVE, which verifies PHAR releases automatically, is also supported:

phive install lkrms/pretty-php

./tools/pretty-php --version

Adding lkrms/pretty-php to your project as a Composer dependency is not recommended.

Arch Linux

Arch Linux users can install pretty-php from the AUR. For example, if your preferred AUR helper is yay:

yay -S pretty-php

macOS

Homebrew users on macOS can install pretty-php using the following command, which automatically taps lkrms/misc if necessary:

brew install lkrms/misc/pretty-php

Usage

Once installed, getting started with pretty-php is as simple as giving it something to format. For example, to format bootstrap.php and any PHP files in the src directory:

pretty-php bootstrap.php src

To see what would change without actually replacing any files, add the --diff option:

pretty-php --diff bootstrap.php src

For detailed usage information, see usage or run:

pretty-php --help

Editor integrations

• pretty-php for Visual Studio Code
  Official VS Code extension
  Visual Studio Marketplace | Open VSX Registry | Repository

Pragmatism

pretty-php generally abides by its own rules ("previous formatting is ignored, and nothing in the original file other than whitespace is changed"), but exceptions are occasionally made and documented here.

• Newlines are preserved
  Line breaks adjacent to most operators, delimiters and brackets are copied from the input to the output.

  Use -N/--ignore-newlines to disable this behaviour.

• Strings and numbers are normalised
  Single-quoted strings are preferred unless the alternative is shorter or backslash escapes are required.

  Use -S/--no-simplify-strings and -n/--no-simplify-numbers to disable or modify this behaviour.

• Alias/import statements are grouped and sorted alphabetically
  Use -M/--no-sort-imports or -m/--sort-imports-by to disable or modify this behaviour.

• Comments are moved if necessary for correct placement of adjacent tokens
  Use --disable=move-comments to disable this behaviour.

• Comments beside code are not moved to the next line

• Comments are trimmed and aligned

• Empty DocBlocks are removed

License

This project is licensed under the MIT License.