PHP Standards Recommendation: Introduction to PSR-1 (Basic Coding Standard)

PSR is the PHP Standard Recommendation. You may have heard of it. But what is it? Should you care? Googling for it, I couldn’t find many pages that explained, without being overly long, what PSR is and how I can or should use it in my PHP projects. This introduction looks at the first standard, […]

This article was posted by Independent Software, a website and database application development company based in Maputo, Mozambique. Our website offers regular write-ups on technical and design issues, ranging from details at code level to 3D Studio Max rendering. Read more about Independent Software's philosophy, or get in touch with Independent Software.

PSR is the PHP Standard Recommendation. You may have heard of it. But what is it? Should you care? Googling for it, I couldn’t find many pages that explained, without being overly long, what PSR is and how I can or should use it in my PHP projects. This introduction looks at the first standard, PSR-1, and summarizes what it’s all about.

The PHP Standard Recommendation is about how you should write your code so that it’ll be easily readable and usable by others. It covers topics like coding style, file organization, autoloading and standardizes various interfaces (more on that below). The PSR was thought up by the Framework Interoperability Group (FIG), which came into being at the php|tek 2009 conference. Its members include the authors of various well-known PHP frameworks. The PSR is in no way “official”; it’s just that the Framework Interoperability Group (FIG) contains a nice cross-section of experienced PHP developers, who vote on whatever the best coding style should be. As such, you can follow all or part of PSR, or none of it. It’s up to you really, but some projects that you want to contribute to may require that you follow some of the PSR, just so that everyone is on the same page. There’s nothing wrong with having a standard where there wasn’t one before.

So who’s a member? There are over 20 members now (from 5 when they started), and they include the authors of CakePHP, Composer, Zend, Lithium, SugarCRM and Symphony. People who’ve been around the PHP block, so to speak.

As for the PSR standards themselves, there are about 17 of them, but only 7 have been accepted by all members. The rest are still being voted on, or have draft status. In this article and subsequent articles, we’ll look at the accepted standards in some detail.

PSR-1 – Basic Coding Standard

The first standard is also immediately the most obvious one: the basic coding standard. These are the basic rules that the voting members of the Framework Interoperability Group feel that you should follow when coding PHP. Surprisingly, the list is not too long (some coding standards for C/C++ are books unto themselves), but never fear, there’s more in PSR-2. This is all there is in PSR-1:

  • Files must use only <?php  and <?=  tags.
  • 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 an “autoloading” PSR (See PSR-4).
  • 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 .

All the shoulds and musts sound rather harsh, but as the FIG puts it, they follow the RFC 2119, just like the Internet Engineering Task Force (IETF) does, and, well, it’s good to follow standards. Or maybe they just thought it looked cool. At the very least, it’s clear.

So what do these rules mean?

Files must use only <?php  and <?=  tags

The first one is easy. Always start your PHP files with either <?php  or <?=  (but be careful, your Apache might be configured not to allow <?= , also known as a short open tag), but don’t use the closing ?>  tag. The reasoning here is likely that if you accidentally add code after the PHP closing tag, it’ll be interpreted as HTML which is not what you want.

Files must use only UTF-8 without BOM for PHP code

Depending on the operating system and code editor you use, your PHP code will be saved in different formats. The PSR-1 standard tries to streamline all those standards into one: you must configure your editor to use UTF-8 encoding, and you must now include a byte order mark (BOM). The latter is a unicode character (U+FEFF) which may appear at the beginning of a text stream to indicate its endianness (byte order). Since presence or absence of the BOM itself might cause confusion, it’s better to leave it out.

In order to write your files in UTF-8 encoding, make sure you use a proper editor that you can configure (i.e. not notepad). Notepad++, Brackets, or UltraEdit or some examples of editors that allow you to set in which encoding your files will be written.

Files should either declare symbols or cause side-effects but should not do both

When you have a PHP file full of functions, classes and constants, then including that file in some other code doesn’t do anything. It merely causes the functions, classes and constants to become available for use, but nothing else happens. However, if your file contains statements that are not inside a class or function, then they will be executed as soon as the file is included by other code, which can give another developer a really bad day, since your code may break his or her code without warning.

Code that’s directly executed upon inclusion of the file is called code with side effects. Side effects include echoing text, including other files, calling ini_set and more. You can still do it, as long as it’s all in a file that has only side effects which are hopefully properly documented.

Namespaces and classes must follow an “autoloading” PSR

OK, this is hard to follow if you’ve not heard of autoloading before. It turns out that the newest PHPs (version 5.3+) can load your classes for you automatically (you don’t have to write a lot of tedious require  statements) whenever you use them. Very handy, but there’s a requirement: your class names must be written using namespaces.

So what you do is this:

The code you’re trying to load must live inside a directory named vendor, in a subdirectory with the name of the package (Package, in this example), in a file with the name of the class (Foo.php). Also, your code file must contain only the class definition and nothing else, and the name of the class must be in StudlyCaps . Foo  qualifies, so does FooBarbetyBar . fooBar  doesn’t.

Class constants must be declared in all upper case with underscore separators

Well, this one should be familiar to anyone who’s every followed a coding standard for almost any language. Write your constants in uppercase, using underscores instead of spaces. Like THIS_GOOD_CONSTANT . It just helps people tell the difference between a constant, a class name, a function, and a variable. Also, stop using magic numbers in your code. Replace them with constants. Your computer science teacher will thank you, and so will people reading your code.

Method names must be declared in camelCase

Holy wars are fought over this one. I’m not touching it. It’s just that it’s in the recommendation, so there you are.

Checking your code for compliance

So that’s all there’s to it: follow the simple rules above and your code is PSR-1 compliant. There are so few rules that it shouldn’t be hard to implement them. But how do you test that your code follows the rules, barring going through each source file and checking visually? One way is using PHP_CodeSniffer. This tool, which you can install using PEAR or Composer, checks any file or files for compliance with a large set of rules, and you can set it to include PSR-1.

How do you use it? By default, PHP_CodeSniffer validates your code using the PEAR standard, but you can change that:

CodeSniffer also implements PSR-2, which we’ll get to in the next article.

That’s it for PSR-1. Check back soon as we continue with PSR-2!

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">