PHP Standards Working Group

I know this topic has been written about a lot. But I think it's so important that I wanted to continue to echo it out and continue promoting it.

The PHP community is making great efforts to enforce coding standards. The purpose of this is to make interoperability of frameworks easier to maintain. It also helps developers understand and read code if it adheres to a certain set of rules. Java has already had for a long time in the form of a JCP by creating JSRs to propose language changes as well as API creation. This is a similar effort.

PSR-0 was a great success and now they have 2 newer proposals called PSR-1 and PSR-2.

PSR-0

It describes a standard that must be adhered to for defining class Autoloaders. I will briefly explain each one:

• A fully-qualified namespace and class must have the following structure

\ \ ()* \

Namespaces are useful in PHP to avoid class name loading collissions. When I write API code or libraries I alread tend to follow this format. For instance, a class in an authentication library could have a namespace with like the following: net\rt\toolkit\auth\LoginService.

Where: 

net\rt is the Vendor Name
auth is the Namespace 
LoginService is the Class Name.

• Each namespace must have a top-level namespace ("Vendor Name"). 
• Each namespace can have as many sub-namespaces as it wishes. 
• Each namespace separator is converted to a DIRECTORY_SEPARATOR when loading from the file system. 
• Each "_" character in the CLASS NAME is converted to a DIRECTORY_SEPARATOR. The "_" character has no special meaning in the namespace. 
• The fully-qualified namespace and class is suffixed with ".php" when loading from the file system. Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case. 

In order to test your compliance to this standard, you can use the following function:
 
 

function autoload($className)

{

    $className = ltrim($className, '\\');

    $fileName  = '';

    $namespace = '';

    if ($lastNsPos = strripos($className, '\\')) {

        $namespace = substr($className, 0, $lastNsPos);

        $className = substr($className, $lastNsPos + 1);

        $fileName  = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;

    }

    $fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';

    require $fileName;

}

What PSR-0 boils down to is that your PHP file locations match the namespace provided. In very similar fashion that Java package names match the directory structure.

 PSR-1


Most of these are self-explanatory, I tried to add more details to the ones that are not:

• Files MUST use only and tags.
• Files MUST use only UTF-8 without BOM for PHP code.

A BOM (byte-order mark) is a character that indicates the byte order of a stream. The Unicode Standard does permit the BOM   but does not require or recommend its use.  Byte order has no meaning in UTF-8 , it serves only to identify a text stream or file as UTF-8.

• 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.

This also serves to keep classes with functions and constants in their seperate files. If a file changes .ini settings, have that file just do that and provide a clear name that this is a configuration file.

• Namespaces and classes MUST follow PSR-0 (read above).
• 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.

PSR-2

• Code MUST follow PSR-1 (read above)
• 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 (not so critical).
• Opening braces for methods MUST go on the next line, and closing braces MUST go on the next line after the body (not so critical).
• 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.


The following is an example of what a class should look like after applying some of the principles described here, they had incosistencies in the braces in their example so I fixed them here:

  


namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{
    public function sampleFunction($a, $b = null)
    {
        if ($a === $b)  

        {
            bar();
        } 

        elseif ($a > $b)  

        {
            $foo->bar($arg1);
        }

        else 

        {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // method body
    }

Stay Tuned! visit http://reflectivethought.net  

Resources


1. https://gist.github.com/1234504
2.  https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
3. https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md