PSR-1 Basic Coding Standard

phpWith the explosion in PHP frameworks and PHP libraries that has occurred over the last couple of years, developers have started to be concerned about standards for coding that can be used across all frameworks.  To this end, at the php|tek conference in 2009, a group was established called, the PHP Standards Group, which later became the "Framework Interoperability Group", or FIG.

FIG members include many of the most popular frameworks and libraries, like: Zend, Symfony, Lithium, Laravel, PEAR, Composer, phpDocumentor, Drupal, Joomla, Propel, and Doctrine to name a few.  You get the idea.  Each of these frameworks and libraries had their own code, and developers wanted to make sure it all played well together.

To date, FIG members have agreed on four standards that they have labeled PSR-0 to PSR-3.      PSR-0 is an Autoloading Standard, PSR-1 is a Basic Coding Standard, PSR-2 is a Coding Style Guide, and PSR-3 is a Logger Interface, which sets up a Syslog protocol.

The FIG group is gradually becoming a major force in PHP that will dictate how all PHP developers should code for interoperability, thus it behooves all PHP devleopers to pay attention to and code using the PSR standards.  With that in mind, I thought it would be worth while to gradually review these standards.

We'll start with PSR-1 the Basic Coding Standard.  This standard is meant to be a minimum requirement for interoperability between frameworks, so it is relatively short.

1. Only use <?php ?> and <?=  ?> starting and ending tags, and not any other variations.
To avoid interoperability problems in the past frameworks and libraries had been making different starting tags, this avoids the problem.

2. Only use UTF-8 with out any BOM, or byte-order-marking.
The Unicode standard permits byte-order-marking with UTF-8.  Its purpose was to signal the start of the text string with the proper encoding.   One of the main reasons for BOM was legacy encoding, and one of the major drawbacks was it can interfere with pattern matching.  For interoperability, it is best to ensure no BOM is used, and to standardize on UTF-8.  It  means not having to worry about different encoding across frameworks.

3. Namespaces and Classes must follow the PSR-0 standard.
This is for ease of autoloading. We'll cover this in a post on PSR-0. Mostly it means each class is in a file by itself and has a namespace.

4. Class names must be declared in StudlyCaps.
There are two base naming conventions, Snake_Case, and camelCase.  Snake case connects words with underscores, like so: mail_label, or Mail_Label.  CamelCase separates words with capital letters.  CamelCase comes in two forms lower camel case, called camelCase, and upper camel case, or StudlyCaps.  The upper and lower refer to the first letter of the name, thus class names should not be : class codeGenerator, and instead should be: class CodeGenerator with the first letter capitalized.

5. Method names must be declared in camelCase, like: public function getFirstName();

6. Class constants must be declared in all upper case with an underscore separator when needed, like so: const VERSION = 5.3; and const VERSION_DATE = '2013-05-11';.

7. Lastly PSR-1 specifies that classes "should" either not have side effects or have side effects but not mix them in a class with one class to a file.

Side effects is doing other functionality not related to the declaring class, usually done by including files in the class.  Side effects means things like generating output, connecting to external services, modifying ini settings, emitting errors or exceptions, modifying global or static variables, reading from or writing to a file, and so on. This is difficult to do in some cases and is more a guideline, or something to strive for rather than a standard.

The PSR-1 standard is described on github.   If your interested in following the group, or becoming a member,  here is the FIG web site.   The group currently has a proposal to add to the PSR-0 standard some refinements, specifically on how to handle underscores in class names, and the group is currently looking at caching.

To cut to the essentials, and sum up,

class names should look like: class DarkSide{},

methods like: public function setDormLights(), and

constants like: const SERVER_NAME = ...

We'll cover the other PSR standards in future posts.

Comments are closed.