Automating PHP PSR standards using Jenkins

Introduction

Whenever you’re writing any programming code, it’s a good idea to make sure it’s all consistent whatever language you’re using so that other people can read it easily. You could argue that programming languages (like PHP, Java, Python etc.) are similar to the languages we speak (English, French, Italian etc.) in that they both have syntax and semantics that make them comprehensible by other people. For example, in English we begin sentences with capital letters and end them with full stops, this could be comparable to ending a statement in PHP with a semi-colon.

As programming languages are mostly written, it makes sense for them to follow suit and have their own grammar in the form of programming standards.

The standards

The most popular standards around for PHP are from the PHP Framework Interop Group (PHP-FIG). This is a group of developers who communicate ways of working together and includes names from popular projects such as Composer, Drupal, Laravel, PEAR and Symfony2. They’ve defined 5 PSR (PHP Specification Request) standards so far, PSR-0 to PSR-4. Next follows a quick overview of PSR-1 and PSR-2 which are the standards that we’re adopting here at UVD.

PSR-1

Overview

• Files MUST use only  Files MUST use only UTF-8 without BOM for PHP code.
• Files SHOULD either declare symbols (classes, functions, constants, etc.) or cause side-effects (e.g. generate output, change .ini settings, etc.) but SHOULD NOT do both.
• Namespaces and classes MUST follow PSR-0.
• Class names MUST be declared in StudlyCaps.
• Class constants MUST be declared in all upper case with underscore separators.
• Method names MUST be declared in camelCase.

Here’s an example of a simple class that meets the standards of PSR-1

PSR-2

Overview

• Code MUST follow PSR-1.
• Code MUST use 4 spaces for indenting, not tabs.
• There MUST NOT be a hard limit on line length; the soft limit MUST be 120 characters; lines SHOULD be 80 characters or less.
• There MUST be one blank line after the namespace declaration, and there MUST be one blank line after the block of use declarations.
• Opening braces for classes MUST go on the next line, and closing braces MUST go on the next line after the body.
• Opening braces for methods MUST go on the next line, and closing braces MUST go on the next line after the body.
• Visibility MUST be declared on all properties and methods; abstract and final MUST be declared before the visibility; static MUST be declared after the visibility.
• Control structure keywords MUST have one space after them; method and function calls MUST NOT.
• Opening braces for control structures MUST go on the same line, and closing braces MUST go on the next line after the body.
• Opening parentheses for control structures MUST NOT have a space after them, and closing parentheses for control structures MUST NOT have a space before.

Here’s an example of a simple class that meets the standards of PSR-2

How?

There’s a few tools that help verify that your project is written to a ruleset. SquizLab’s CodeSniffer is the most popular tool out there, however it takes a bit of configuration to get running smoothly. We found a simpler solution that meets our requirements from SensioLabs.

PHP Coding Standards Fixer

The PHP Coding Standards Fixer, as already mentioned, is a product by SensioLabs. It comes as a PHAR (PHP Archive) and is also available through Composer.

Using Composer

1). From the command line, run the following:

composer global require fabpot/php-cs-fixer @stable

We’re using global which means this will be added to a composer.json in your ~/.composer/ directory.

1a). We also need to make sure that composer’s global vendors binaries are in our $PATH. To do so, execute the following:

export PATH="$PATH:$HOME/.composer/vendor/bin"

2). Now, running php-cs-fixer should output:

You’ll notice that this tool has the ability to fix your code so that it passes the PSR standards. Whilst this is extremely useful, we decided to dry-run so that we can fix these issues ourselves and practice using the standards that we’re writing to.

Output with our Sprinter project

To test this out I ran this tool with our upcoming project planning tool, Sprinter, by executing the following in the project root directory.

php-cs-fixer fix src/ --level="psr2" --dry-run -v --diff

Note: I’ve removed a lot of the output regarding white space to make this easier to read.

To summarise, I need to do the following to make this PSR-2 compliant.

• Match the class names’ case to the filename (PSR-0 is case sensitive!)
• Move some of my braces so that they’re on the correct lines
• rename else if to elseif

After fixing these, executing the tool again gives an exit code of 0 which means it ran successfully.

Rake task

This exit code allows us to write the following task that can be ran with Rake.

This can be called by executing rake cs:sensio[psr2]. You can replace psr2 with psr0, psr1 or all depending on your needs.

We now use this in our Continuous Integration environment, Jenkins, so that any code we run through our deployment stages has to be compliant with PSR-2 for it to succeed.

So there you have it, how we’re making our code more readable and maintainable here at UVD!