The objective of cleaning is not just to clean, but to feel happiness living within that environment.
~ Marie Kondo
Everyone who has written PHP for a while ends up confronted with messy code. The gentle learning curve, the forgiving type system, and the easy execution model all lend themselves to writing PHP that’s quick, dirty, and eventually frustrating.
In 2013, the PHP Framework Interoperability Group (PHP-FIG) adopted PSR-2, a standard for code which was intended to “reduce cognitive friction when scanning code from different authors.” The result? Reading PHP code by different authors in different projects has never been easier. Whether you’re diving into your workplace’s proprietary code or Laravel’s Eloquent ORM code, you’ll find that it’s readable (even if not quite understandable!).
Our goal here is going to be setting up automated tools in Vim to clean up your code as you write. By making it part of your regular flow and getting quick feedback, you’ll be able to write your code with the confidence that in a year or two when you open up this file again, you’ll still be able to read it!
If you clean your bathroom every day, you never have to clean your bathroom.
~ Lindy West’s Mother, Shrill: Notes from a Loud Woman
We’re going to take advantage of some existing tools: PHP-Code Sniffer (PHP-CS) and PHP-CS-Fixer.
Installing PHP-CS
To add PHP-CS to your project using composer, run:
composer require --dev "squizlabs/php_codesniffer=\*"
By default, PHP-CS checks against the PEAR coding standard. However it ships
with several other configurations, including PSR2
. We can run PHP-CS to check
for standards violations using the phpcs
command.
./vendor/bin/phpcs --standard=PSR2 path/to/file
However, since we’re also looking to standardize and automate this in our
project, we are going to create a file in our project that configures PHP-CS.
The file that PHP-CS looks for is a phpcs.xml
file.
Our custom coding standard based on PSR-2
Since we’re using the PSR-2 standard, our ruleset is pretty simple. The PHP-CS documentation shows many more options, including the ability to exclude some files or rules, or include rules from other coding standards.
Now when we run .vendor/bin/phpcs
we’re going to get the PSR-2 coding standard
checked against every one of our files based on our phpcs.xml
file!
Installing PHP-CS-Fixer
Generally we don’t only want our computer to tell us when something is wrong, we can also get it to fix our coding issues for us! The tool for this is PHP-CS-Fixer.
Again we’ll use Composer to install PHP-CS-Fixer
composer require --dev friendsofphp/php-cs-fixer
And we’ll be able to run it using .vendor/bin/php-cs-fixer fix path/to/file
.
We’ll also create a .php_cs.dist
file in our project so we can standardize the
rules we’re going to enforce. The file will look like this:
setRules([
'@PSR2' => true,
])
->setFinder($finder)
;
Integrating With Vim
To bring these tools into Vim, we’re going to rely on the plugin ALE. ALE is capable of a lot of things, including linting (with PHP-CS), fixing (with PHP-CS-Fixer), and even deeper IDE-like features using the Language Server Protocol (going to get into that in a later post).
First, install ALE based on your own Vim setup.
Then we want to add some configuration so ALE knows where to look for our tools.
Add the following to your project’s .vimrc
assuming you’re using :exrc
to
allow for project-based vim configuration.
let g:ale_php_phpcs_executable='./vendor/bin/phpcs'
let g:ale_php_php_cs_fixer_executable='./vendor/bin/php-cs-fixer'
let g:ale_fixers = {'php': ['php-cs-fixer']}
And that should set up ALE with PHP-CS and PHP-CS-Fixer! PHP-CS should be running asynchronously, and the issues it finds will pop up as you type.
In order to run PHP-CS-Fixer, use the command :ALEFix
in a file, which will
run the fixer and write those changes.
You can also run the fixers every time you save by adding let g:ale_fix_on_save
in your .vimrc
file.