Written by on 21 December 2015

Converting big PHP codebases to PSR2.

It is known by now that every codebase large enough (in terms of lines of code or people collaborating to it) should follow any code standard. Here at Coolblue we weren’t different and were using our own coding standard.

But codebases evolve. And our codebase – that has been supporting one of the most visited ecommerces in The Netherlands – needed to be upgraded to a coding standard that’s a little bit more up to date.

This is the process we follow to move into PSR-2.

Screen Shot 2015-12-21 at 13.35.30Why changing the standard?

So, if any standard is better than no standard… why change the one we already had?

We wanted to have a little bit more consistency. Our biggest codebase was the only one not following the PSR-2 convention, as all our newest (and smaller) projects did. Having to switch from one another was cumbersome, and so it was peer reviewing. We also felt that, if we wanted to start opening the source code of some of our libraries, adhering to an already discussed and accepted standard was the way to go.

The decision process was a no-brainer. It involved a presentation using our Decision Roundtable methodology, explaining the pro’s and con’s of this and rapidly reaching consensus between all the present developers. The next step wouldn’t be so fast. A lot needed to happen.

The conversion process

At first, we didn’t want to enforce the new standard too firmly. It’d be a gradual and measured change, easier to control, one pull request at a time.

The rule was simple, if you were creating a pull request, then all the files included should be converted to PSR-2 in the first commit of the pull request. But after some consideration, this approach deemed too slow and even insecure, as converting files in a “as-used base”, didn’t guarantee that the change wasn’t affecting other areas of the codebase.

So, we went in for a full “big bang” fashion.

The Big Bang.

For this to happen, we had to take some precautions:
We set up a Release lock on the codebase, to prevent merging conflicts.
We decided that if by 4 PM we didn’t achieved the expected results, we would just roll back and try again next Monday.
Every team worked on a testing plan 4 days in advance, so everybody would be prepared on Friday to test as fast as possible.
So, we first decided to start the process around 13:00 hs on a Friday with the Release Lock. Guys could keep on working, but releases were off the table for the time being. We checked out our master branch, and ran Fabien Potencier’s PHP Coding Standards Fixer (PHPCSF) on it.

$ ./php-cs-fixer fix Library/ --level=psr2 -vvv
[... Lots of stuff...]
Fixed 2094 files in 406.985 seconds, 21.500 MB memory used

After what seemed to be an eternity (but actually were a couple of minutes) the process ended most of our files were already complying to PSR-2, 2100 files in around 400 seconds wasn’t too bad, right?

The next step would be to check that the files actually complied to PSR2. For that, there’s no better tool than PHP_CodeSniffer. So, after running it against our codebase, we got some nasty surprises.

./phpcs.phar -vvv --standard=psr2 Library/

----------------------------------------------------------------------
FOUND 1 ERRORS AFFECTING 1 LINE
----------------------------------------------------------------------
7 | ERROR | [x] The extends keyword must be on the same line as the
| | class name
----------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

The previous error actually appeared in most our files. Well, apparently PHPCSF didn’t fixed it all on the first try. So, apparently and according to the error message, PHP Code Beautifier (same repository as PHP_CodeSniffer) could automatically fix this. Fortunately, this would be our last step.

./phpcbf.phar --standard=psr2 Library/
[... more and more stuff ...]
 Patched 1978 files
 Time: 161.270s; Memory: 21Mb

So, this time, after running PHP_CodeSniffer again, all the errors were gone.

Checking that everything works.

We’ve just automatically changed thousands of files. Now it was the time to check if everything was still working.

As I told you before, during this process we created a release lock. So we deployed all this changes directly into the acceptance environment, sure that we were the only ones able to do this. This was the time our teams had to step up and do their part.

Every single team fully tested all the functionalities they were responsible for, within this acceptance environment. This meant manual checks, including tasks like making sure we were still able to log in, navigate the website, add products to the shopping cart and completing the order process. There were also a lot of automated checks, with batteries of integration and unit tests running for the changed codebase.

This checking process was extremely fast, and in less than half an hour, we were confident the site was still in good shape. This was the moment we deployed everything into one of our web servers, and clawed onto our logging system to check for errors. Nothing there? Really? NOPE? Great.

We kept our jobs.

Deploy and automating the checks

When our confidence level was high, just creating one of our biggests pull request and merging it wasn’t such a big deal. After all, we made sure that everything worked. After this, everyone just pulled the changes in their repos and voilĂ , the PSR-2 Big Bang was over.

As we showed you before, we have an automatic deployment pipeline ready to check, build and deploy our software automatically, using TeamCity. We also configured the PSR2 check here, so every single time there’s a Pull Request or a merge in our codebase, we’re pretty sure the code is PSR-2 compliant. No need for human eyes, so prone to error, for this process.

What now?

After all this effort, now everybody just complies with PSR2 in the most natural way. Thanks to IDEs like PHPStorm or Sublime, and their ability to check coding styles automatically, this has been no hassle at all, even for those more accustomed to the old standard.

So, just as a piece of advice, don’t be afraid to tackle the conversion of a large PHP codebase into PSR2, just because “it’s a lot of work” or “things will break”. Like many other things in Web development, it’s a process and a little planning goes a long way. And we’re lucky enough to have several tools that will help us along the way.

Which are your experiences regarding coding standards? I would love to hear from you in the comments.

REPLIES (2)What you say.

COMMENTGive your two cents.

*