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.
- Supports code written for PHP 8.4 and below (when running on a PHP version that can parse it)
- Formats property hooks introduced in PHP 8.4
- 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)
- Linux, macOS or Windows
- PHP 8.4, 8.3, 8.2, 8.1, 8.0 or 7.4 with the standard
tokenizer
,mbstring
andjson
extensions enabled
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 users can install pretty-php
from the AUR. For example, if your
preferred AUR helper is yay
:
yay -S pretty-php
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
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
- pretty-php for Visual Studio Code
Official VS Code extension
Visual Studio Marketplace | Open VSX Registry | Repository
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
This project is licensed under the MIT License.