Why PSR in Particular?

So, why choose one standard and not another? It happens that the PHP Framework Interop Group—the originators of PSRs—has a pretty great pedigree, and the standards themselves therefore make sense. But also, these are the standards that the major frameworks and components are adopting. If you are using Composer to add functionality to your projects, you are already consuming code that complies with PSRs . By using its conventions for autoloading and its style guides, you are likely building code that is ready for collaboration with other people and components.

PSRs are a good bet because they are supported by key framework and component projects, including Phing, Composer, PEAR, Symfony, and Zend 2. Like patterns, standards are infectious—you’re probably already benefiting from them.

Who Are PSRs for?

Ostensibly PSRs are designed for the creators of frameworks. The fact that the membership of the PHP-Fig group rapidly widened to include the creators of tools as well as frameworks, however, shows that standards have wide relevance. That said, unless you are creating a logger, you may not need to worry too much about the details of PSR-3 (beyond ensuring any logging tool you use is itself compliant). On the other hand, if you’ve read the rest of this book, chances are you are as likely to be creating tools as you are to be consuming them. So, it’s also likely that you’ll find something relevant to you either in the present standards or the standards to come.

And then there are the standards that matter to all of us. Unglamorous as style guides are, for example, they are relevant to every programmer. And while the rules that govern autoloading really apply to those who create autoloaders (and the main game in town is probably Composer’s), they also fundamentally affect how we organize our classes, our packages, and our files.

For these reasons, I will focus on coding style and autoloading for the rest of this chapter.

PSR-1 Basic Coding Standard

These are the fundamentals for PHP code. You can find them in detail at http://www.php-fig.org/psr/psr-1/ . Let’s break them down.

// listing 15.01
// index.php
namespace popp\ch15\batch01;

require_once(__DIR__ . "/../../../vendor/autoload.php");

$tree = new Tree();
print "loaded " . get_class($tree) . "\n";

// listing 15.02
// Tree.php
namespace popp\ch15\batch01;

class Tree
{
}

class MyClassName

private $myPropertyName

public function myMethodName()                                                            

const MY_NAME_IS = 'matt';

<?
// listing 15.03

class conf_reader {
    const ModeFile = 1;
    const Mode_DB = 2;
    private $conf_file;
    private $confValues= [];

    function read_conf() {
        // implementation
    }
}
?>

<?php
// listing 15.04

namespace popp\ch15\batch01;

class ConfReader {
    const MODE_FILE = 1;
    const MODE_DB = 2;
    private $confFile;
    private $confValues = [];

    function readConf() {
        // implementation
    }
}

PSR-2 Coding Style Guide

The Coding Style Guide (PSR-2) builds upon PSR-1. Let’s jump in and look at some of the rules.

// listing 15.05

namespace popp\ch15\batch01;

use popp\ch10\batch06\DiamondDecorator;
use popp\ch10\batch06\DiamondPlains;

// begin class

// listing 15.06
class EarthGame extends Game implements
    Playable,
    Savable
{
    // class body
}

class EarthGame extends Game implements Playable, Savable
{
    // class body
}

// listing 15.07

final public static function generateTile(int $diamondCount, bool $polluted = false)
{
    // implementation
}

// listing 15.08

    public function __construct(
        int $size,
        string $name,
        bool $wraparound = false,
        bool $aliens = false
    ) {
        // implementation
    }

// listing 15.09

        $earthgame = new EarthGame(
            5,
            "earth",
            true,
            true
        );
        $earthgame::generateTile(5, true);

// listing 15.10

        $tile = [];
        for ($x = 0; $x < $diamondcount; $x++) {
            if ($polluted) {
                $tile[] = new PollutionDecorator(new DiamondDecorator(new Plains()));
            } else {
                $tile[] = new DiamondDecorator(new Plains());
            }
        }

Checking and Fixing your Code

Even if this chapter covered every single directive in PSR-2, it would be hard to keep it all in your mind. After all, we have other things to think about—like the design and implementation of our systems. So, given that we have bought into the value of coding standards, how do we comply without using too much of our time or focus? We use a tool, of course.

PHP_CodeSnifferallows you to detect and even repair standards violations—and not just for PSR. You can get it by following the instructions at https://github.com/squizlabs/PHP_CodeSniffer . There are Composer and PEAR options, but here’s how you can download the PHP archive files:

curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar

curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar

Why two downloads? The first is for phpcs, which diagnoses and reports on violations. The second is for phpcbf, which can fix a lot of them. Let’s put the tools through their paces. First, here is a scrappily formatted piece of code:

// listing 15.11
namespace popp\ch15\batch01;

class ebookParser {
    function __construct(string $path , $format=0 ) {
        if ($format>1)
            $this->setFormat( 1 );
    }
    function setformat(int $format) {
        // do something with $format
    }
}

Rather than run through the problems here, let’s have PHP_CodeSnifferdo it for us:

$ php phpcs.phar --standard=PSR2 src/ch15/batch01/phpcsBroken.php
----------------------------------------------------------------------
FOUND 14 ERRORS AFFECTING 6 LINES
----------------------------------------------------------------------
  3 | ERROR | [x] There must be one blank line after the namespace
    |       |     declaration
  4 | ERROR | [ ] Class name "ebookParser" is not in camel caps
    |       |     format
  4 | ERROR | [x] Opening brace of a class must be on the line after
    |       |     the definition
  6 | ERROR | [ ] Visibility must be declared on method "__construct"
  6 | ERROR | [x] Expected 0 spaces between argument "$path" and
    |       |     comma; 1 found
  6 | ERROR | [x] Incorrect spacing between argument "$format" and
    |       |     equals sign; expected 1 but found 0
  6 | ERROR | [x] Incorrect spacing between default value and equals
    |       |     sign for argument "$format"; expected 1 but found 0
  6 | ERROR | [x] Expected 0 spaces between argument "$format" and
    |       |     closing bracket; 1 found
  6 | ERROR | [x] Opening brace should be on a new line
  7 | ERROR | [x] Inline control structures are not allowed
  8 | ERROR | [x] Space after opening parenthesis of function call
    |       |     prohibited
  8 | ERROR | [x] Expected 0 spaces before closing bracket; 1 found
 11 | ERROR | [ ] Visibility must be declared on method "setformat"
 11 | ERROR | [x] Opening brace should be on a new line
----------------------------------------------------------------------
PHPCBF CAN FIX THE 11 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

That’s an exhausting number of problems for just a few lines of code. Luckily, as the output indicates, we can fix a lot of these with very little effort:

$ php phpcbf.phar --standard=PSR2 src/ch15/batch01/EbookParser.php

Processing EbookParser.php [PHP => 83 tokens in 15 lines]... DONE in 11ms (11 fixable violations)
        => Fixing file: 0/11 violations remaining [made 4 passes]... DONE in 17ms
Patched 1 file

Now, if we run phpcs again, we’ll see that the situation is much improved:

$ php phpcs.phar --standard=PSR2 src/ch15/batch01/EbookParser.php

----------------------------------------------------------------------
FOUND 3 ERRORS AFFECTING 3 LINES
----------------------------------------------------------------------
  5 | ERROR | Class name "ebookParser" is not in camel caps format
  8 | ERROR | Visibility must be declared on method "__construct"
 15 | ERROR | Visibility must be declared on method "setformat"
----------------------------------------------------------------------

I’ll go ahead and add the visibility declarations, and then change the name of the class—a quick job! And now I have a stylishly compliant code file:

// listing 15.12

namespace popp\ch15\batch01;

class EbookParser
{
    public function __construct(string $path, $format = 0)
    {
        if ($format > 1) {
            $this->setFormat(1);
        }
    }

    private function setformat(int $format)
    {
        // do something with $format
    }
}

The Rules that Matter to Us

The main purpose of PSR-4 is to define rules for autoloader developers. However, those rules inevitably determine the way we must declare namespaces and classes. Here are some of the basics.

A fully-qualified classname (that is, the name of a class, including its namespaces) must include an initial “vendor” namespace. So, a class must have at least one namespace.

Let’s say that our vendor namespace is popp. We can declare a class in this way:

// listing 15.13

namespace popp;

class Services
{
}

The fully-qualified class name for this class is popp\Services.

The initial namespaces in a path must correspond to one or more base directories. We can use this to map a set of sub-namespaces to a starting directory. If, for example, we want to work with the namespace popp\library (and nothing else under the popp namespace), then we might map that to a top-level directory to spare us from having to maintain an empty popp/ directory.

Let’s set up a composer.json file to perform that mapping:

{
    "autoload": {
        "psr-4": {
            "popp\\library\\": "mylib"
        }
    }  
}

Notice that I don’t even need to call the base directory, "library". This is an arbitrary mapping of popp\libraryto the mylib directory. Now I can create a class file under the mylib directory:

// listing 15.14
// mylib/LibraryCatalogue.php

namespace popp\library;

use popp\library\inventory\Book;

class LibraryCatalogue
{
    private $books = [];
    public function addBook(Book $book)
    {
        $this->books[] = $book;
    }
}

In order to be found, the LibraryCatalogue class must be placed in a file with exactly the same name (with the obvious addition of the .php extension).

After a base directory (mylib) has been associated with initial namespaces (popp\library), there must then be a direct relation between subsequent directories and sub-namespaces. It happens that I have already referenced a class named popp\library\inventory\Bookin my LibraryCatalogue class. That class file should therefore be placed in the mylib/inventory directory:

// listing 15.15
// mylib/library/inventory/Book.php

namespace popp\library\inventory;

class Book
{
    // implementation
}

Remember the rule that the initial namespaces in a path must correspond to one or more base directories? So far we have made a one-to-one relationship between popp\library and mylib. There’s actually no reason why we can’t map the popp\library namespace to more than one base directory. Let’s add a directory named additional to the mapping; here’s the amendment to composer.json:

{
    "autoload": {
        "psr-4": {
            "popp\\library\\": ["mylib", "additional"]
        }
    }
}

Now I can create the additional/inventory directories and a class to go in them:

// listing 15.16
// additional/inventory/Ebook.php
namespace popp\library\inventory;

class Ebook extends Book
{
    // implementation
}

Next, let’s create a top-level runner script, index.php, to instantiate these classes:

// listing 15.17
// index.php

require_once("vendor/autoload.php");

use popp\library\LibraryCatalogue;

// will be found under mylib/
use popp\library\inventory\Book;

// will be found under additional/
use popp\library\inventory\Ebook;

$catalogue = new LibraryCatalogue();
$catalogue->addBook(new Book());
$catalogue->addBook(new Ebook());

Remember the rule about side effects? A PHP file should declare classes, interfaces, functions, and the like; or, it should perform an action. However, it should not do both. This script falls into the taking action category. Crucially, it calls require_once()to include the autoload code generated using the configuration in the composer.json file. Thanks to this, all the classes are located, despite the fact that Ebook has been placed in an entirely separate base directory from the rest.

Why would I want to maintain two separate directories for the same core namespace? One possible reason is for unit tests that you want to keep separate from production code. You may also manage plug-ins and extensions that will not ship with every version of your system.