Why We Use Namespaces

Namespaces are important because they let us create sandboxed code that works alongside other developers’ code. This is the cornerstone concept of the modern PHP component ecosystem. Component and framework authors build and distribute code for a large number of PHP developers, and they have no way of knowing or controlling what classes, interfaces, functions, and constants are used alongside their own code. This problem applies to your own in-house projects, too. If you write custom PHP components or classes for a project, that code must work alongside your project’s third-party dependencies.

As I mentioned earlier with the symfony/httpfoundation component, your code and other developers’ code might use the same class, interface, function, or constant names. Without namespaces, a name collision causes PHP to fail. With namespaces, your code and other developers’ code can use the same class, interface, function, or constant name assuming your code lives beneath a unique vendor namespace.

If you’re building a tiny personal project with only a few dependencies, class name collisions probably won’t be an issue. But when you’re working on a team building a large project with numerous third-party dependencies, name collisions become a very real concern. You cannot control which classes, interfaces, functions, and constants are introduced into the global namespace by your project’s dependencies. This is why namespacing your code is important.

Declaration

Every PHP class, interface, function, and constant lives beneath a namespace (or subnamespace). Namespaces are declared at the top of a PHP file on a new line immediately after the opening <?php tag. The namespace declaration begins with namespace, then a space character, then the namespace name, and then a closing semicolon ; character.

Remember that namespaces are often used to establish a top-level vendor name. This example namespace declaration establishes the Oreilly vendor name:

<?php
namespace Oreilly;

All PHP classes, interfaces, functions, or constants declared beneath this namespace declaration live in the Oreilly namespace and are, in some way, related to O’Reilly Media. What if we wanted to organize code related to this book? We use a subnamespace.

Subnamespaces are declared exactly the same as in the previous example. The only difference is that we separate namespace and subnamespace names with the \ character. The following example declares a subnamespace named ModernPHP that lives beneath the topmost Oreilly vendor namespace:

<?php
namespace Oreilly\ModernPHP;

All classes, interfaces, functions, and constants declared beneath this namespace declaration live in the Oreilly\ModernPHP subnamespace and are, in some way, related to this book.

All classes in the same namespace or subnamespace don’t have to be declared in the same PHP file. You can specify a namespace or subnamespace at the top of any PHP file, and that file’s code becomes a part of that namespace or subnamespace. This makes it possible to write multiple classes in separate files that belong to a common namespace.

Import and Alias

Before we had namespaces, PHP developers solved the name collision problem with Zend-style class names. This was a class-naming scheme popularized by the Zend Framework where PHP class names used underscores in lieu of filesystem directory separators. This convention accomplished two things: it ensured class names were unique, and it enabled a naive autoloader implementation that replaced underscores in PHP class names with filesystem directory separators to determine the class file path.

For example, the PHP class Zend_Cloud_DocumentService_Adapter_WindowsAzure_Query corresponds to the PHP file Zend/Cloud/DocumentService/Adapter/WindowsAzure/Query.php. A side effect of the Zend-style naming convention, as you can see, is absurdly long class names. Call me lazy, but there’s no way I’m typing that class name more than once.

Modern PHP namespaces present a similar problem. For example, the full Response class name in the symfony\httpfoundation component is \Symfony\Component\HttpFoundation\Response. Fortunately, PHP lets us import and alias namespaced code.

By import, I mean that I tell PHP which namespaces, classes, interfaces, functions, and constants I will use in each PHP file. I can then use these without typing their full namespaces.

By alias, I mean that I tell PHP that I will reference an imported class, interface, function, or constant with a shorter name.

The code shown in Example 2-1 creates and sends a 400 Bad Request HTTP response without importing and aliasing.

<?php
$response = new \Symfony\Component\HttpFoundation\Response('Oops', 400);
$response->send();

This isn’t terrible, but imagine you have to instantiate a Response instance several times in a single PHP file. Your fingers will get tired quickly. Now look at Example 2-2. It does the same thing with importing.

<?php
use Symfony\Component\HttpFoundation\Response;

$response = new Response('Oops', 400);
$response->send();

We tell PHP we intend to use the Symfony\Component\HttpFoundation\Response class with the use keyword. We type the long, fully qualified class name once. Then we can instantiate the Response class without using its fully namespaced class name. How cool is that?

Some days I feel really lazy. This is a good opportunity to use an alias. Let’s extend Example 2-2. Instead of typing Response, maybe I just want to type Res instead. Example 2-3 shows how I can do that.

<?php
use Symfony\Component\HttpFoundation\Response as Res;

$r = new Res('Oops', 400);
$r->send();

In this example, I changed the import line to import the Response class. I also appended as Res to the end of the import line; this tells PHP to consider Res an alias for the Response class. If we don’t append the as Res alias to the import line, PHP assumes a default alias that is the same as the imported class name.

As of PHP 5.6, it’s possible to import functions and constants. This requires a tweak to the use keyword syntax. To import a function, change use to use func:

<?php
use func Namespace\functionName;

functionName();

To import a constant, change use to use constant:

<?php
use constant Namespace\CONST_NAME;

echo CONST_NAME;

Function and constant aliases work the same as classes.

Helpful Tips

<?php
use Symfony\Component\HttpFoundation\Request,
    Symfony\Component\HttpFoundation\Response,
    Symfony\Component\HttpFoundation\Cookie;

<?php
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Cookie;

<?php
namespace Foo {
    // Declare classes, interfaces, functions, and constants here
}

namespace Bar {
    // Declare classes, interfaces, functions, and constants here
}

<?php
namespace My\App;

class Foo
{
    public function doSomething()
    {
        $exception = new Exception();
    }
}

<?php
namespace My\App;

class Foo
{
    public function doSomething()
    {
        throw new \Exception();
    }
}

Why We Use Traits

The PHP language uses a classical inheritance model. This means you start with a single generalized root class that provides a base implementation. You extend the root class to create more specialized classes that inherit their immediate parent’s implementation. This is called an inheritance hierarchy, and it is a common pattern used by many programming languages.

The classical inheritance model works well most of the time. However, what do we do if two unrelated PHP classes need to exhibit similar behavior? For example, a PHP class RetailStore and another PHP class Car are very different classes and don’t share a common parent in their inheritance hierarchies. However, both classes should be geocodable into latitude and longitude coordinates for display on a map.

Traits were created for exactly this purpose. They enable modular implementations that can be injected into otherwise unrelated classes. Traits also encourage code reuse.

My first (bad) reaction is to create a common parent class Geocodable that both RetailStore and Car extend. This is a bad solution because it forces two otherwise unrelated classes to share a common ancestor that does not naturally belong in either inheritance hierarchy.

My second (better) reaction is to create a Geocodable interface that defines which methods are required to implement the geocoding behavior. The RetailStore and Car classes can both implement the Geocodable interface. This is a good solution that allows each class to retain its natural inheritance hierarchy, but it requires us to duplicate the same geocoding behavior in both classes. This is not a DRY solution.

My third (best) reaction is to create a Geocodable trait that defines and implements the geocodable methods. I can then mix the Geocodable trait into both the RetailStore and Car classes without polluting their natural inheritance hierarchies.

How to Create a Trait

Here’s how you define a PHP trait:

<?php
trait MyTrait {
    // Trait implementation goes here
}

Let’s return to our Geocodable example to better demonstrate traits in practice. We agree both RetailStore and Car classes need to provide geocodable behavior, and we’ve decided inheritance and interfaces are not the best solution. Instead, we create a Geocodable trait that returns latitude and longitude coordinates that we can plot on a map. Our complete Geocodable trait looks like Example 2-12.

<?php
trait Geocodable {
    /** @var string */
    protected $address;

    /** @var \Geocoder\Geocoder */
    protected $geocoder;

    /** @var \Geocoder\Result\Geocoded */
    protected $geocoderResult;

    public function setGeocoder(\Geocoder\GeocoderInterface $geocoder)
    {
        $this->geocoder = $geocoder;
    }

    public function setAddress($address)
    {
        $this->address = $address;
    }

    public function getLatitude()
    {
        if (isset($this->geocoderResult) === false) {
            $this->geocodeAddress();
        }

        return $this->geocoderResult->getLatitude();
    }

    public function getLongitude()
    {
        if (isset($this->geocoderResult) === false) {
            $this->geocodeAddress();
        }

        return $this->geocoderResult->getLongitude();
    }

    protected function geocodeAddress()
    {
        $this->geocoderResult = $this->geocoder->geocode($this->address);

        return true;
    }
}

The Geocodable trait defines only the properties and methods necessary to implement the geocodable behavior. It does not do anything else.

Our Geocodable trait defines three class properties: an address (string), a geocoder object (an instance of \Geocoder\Geocoder from the excellent willdurand/geocoder component by William Durand), and a geocoder result object (an instance of \Geocoder\Result\Geocoded). We also define four public methods and one protected method. The setGeocoder() method is used to inject the Geocoder object. The setAddress() method is used to set an address. The getLatitude() and getLongitude() methods return their respective coordinates. And the geocodeAddress() method passes the address string into the Geocoder instance to retrieve the geocoder result.

How to Use a Trait

Using a PHP trait is easy. Add the code use MyTrait; inside a PHP class definition. Here’s an example. Obviously, replace MyTrait with the appropriate PHP trait name:

<?php
class MyClass
{
    use MyTrait;

    // Class implementation goes here
}

Let’s return to our Geocodable example. We defined the Geocodable trait in Example 2-12. Let’s update our RetailStore class so that it uses the Geocodable trait (Example 2-13). For the sake of brevity, I do not provide the complete RetailStore class implementation.

<?php
class RetailStore
{
    use Geocodable;

    // Class implementation goes here
}

That’s all we have to do. Now each RetailStore instance can use the properties and methods provided by the Geocodable trait, as shown in Example 2-14.

<?php
$geocoderAdapter = new \Geocoder\HttpAdapter\CurlHttpAdapter();
$geocoderProvider = new \Geocoder\Provider\GoogleMapsProvider($geocoderAdapter);
$geocoder = new \Geocoder\Geocoder($geocoderProvider);

$store = new RetailStore();
$store->setAddress('420 9th Avenue, New York, NY 10001 USA');
$store->setGeocoder($geocoder);

$latitude = $store->getLatitude();
$longitude = $store->getLongitude();
echo $latitude, ':', $longitude;

Create a Generator

Generators are easy to create because they are just PHP functions that use the yield keyword one or more times. Unlike regular PHP functions, generators never return a value. They only yield values. Example 2-15 shows a simple generator.

<?php
function myGenerator() {
    yield 'value1';
    yield 'value2';
    yield 'value3';
}

Pretty simple, huh? When you invoke the generator function, PHP returns an object that belongs to the Generator class. This object can be iterated with the foreach() function. During each iteration, PHP asks the Generator instance to compute and provide the next iteration value. What’s neat is that the generator pauses its internal state whenever it yields a value. The generator resumes internal state when it is asked for the next value. The generator continues pausing and resuming until it reaches the end of its function definition or an empty return; statement. We can invoke and iterate the generator in Example 2-15 like this:

<?php
foreach (myGenerator() as $yieldedValue) {
    echo $yieldedValue, PHP_EOL;
}

This outputs:

value1
value2
value3

Use a Generator

I like to demonstrate how a PHP generator saves memory by implementing a simple range() function. First, let’s do it the wrong way (Example 2-16).

<?php
function makeRange($length) {
    $dataset = [];
    for ($i = 0; $i < $length; $i++) {
        $dataset[] = $i;
    }

    return $dataset;
}

$customRange = makeRange(1000000);
foreach ($customRange as $i) {
    echo $i, PHP_EOL;
}

Example 2-16 makes poor use of memory. The makeRange() method in Example 2-16 allocates one million integers into a precomputed array. A PHP generator can do the same thing while allocating memory for only one integer at any given time, as shown in Example 2-17.

<?php
function makeRange($length) {
    for ($i = 0; $i < $length; $i++) {
        yield $i;
    }
}

foreach (makeRange(1000000) as $i) {
    echo $i, PHP_EOL;
}

This is a contrived example. However, just imagine all of the potential data sets that you can compute. Number sequences (e.g., Fibonacci) are an obvious candidate. You can also iterate a stream resource. Imagine you need to iterate a 4 GB comma-separated value (CSV) file and your virtual private server (VPS) has only 1 GB of memory available to PHP. There’s no way you can pull the entire file into memory. Example 2-18 shows how we can use a generator instead!

<?php
function getRows($file) {
    $handle = fopen($file, 'rb');
    if ($handle === false) {
        throw new Exception();
    }
    while (feof($handle) === false) {
        yield fgetcsv($handle);
    }
    fclose($handle);
}

foreach (getRows('data.csv') as $row) {
    print_r($row);
}

This example allocates memory for only one CSV row at a time instead of reading the entire 4 GB CSV file into memory. It also encapsulates the iteration implementation into a tidy package; this lets us quickly change how we get data (e.g., CSV, XML, JSON) without interrupting our application code that iterates the data.

Generators are a tradeoff between versatility and simplicity. Generators are forward-only iterators. This means you cannot use a generator to rewind, fast-forward, or seek a data set. You can only ask a generator to compute and yield its next value. Generators are most useful for iterating large or numerically sequenced data sets with only a tiny amount of system memory. They are also useful for accomplishing the same simple tasks as larger iterators with less code.

Generators do not add functionality to PHP. You can do what generators do without a generator. However, generators greatly simply certain tasks while using less memory. If you require more versatility to rewind, fast-forward, or seek through a data set, you’re better off writing a custom class that implements the Iterator interface, or using one of PHP’s prebuilt Standard PHP Library (SPL) iterators.

Create

So we know PHP closures look like functions. You should not be surprised, then, that you create a PHP closure like Example 2-19.

<?php
$closure = function ($name) {
    return sprintf('Hello %s', $name);
};

echo $closure("Josh");
// Outputs --> "Hello Josh"

That’s it. Example 2-19 creates a closure object and assigns it to the $closure variable. It looks like a standard PHP function: it uses the same syntax, it accepts arguments, and it returns a value. However, it does not have a name.

I typically use PHP closure objects as function and method callbacks. Many PHP functions expect callback functions, like array_map() and preg_replace_callback(). This is a perfect opportunity to use PHP anonymous functions! Remember, closures can be passed into other PHP functions as arguments, just like any other value. In Example 2-20, I use a closure object as a callback argument in the array_map() function.

<?php
$numbersPlusOne = array_map(function ($number) {
    return $number + 1;
}, [1,2,3]);
print_r($numbersPlusOne);
// Outputs --> [2,3,4]

OK, so that wasn’t that impressive. But remember, before closures PHP developers had no choice but to create a separate named function and refer to that function by name. This was slightly slower to execute, and it segregated a callback’s implementation from its usage. Old-school PHP developers used code like this:

<?php
// Named callback implementation
function incrementNumber ($number) {
    return $number + 1;
}

// Named callback usage
$numbersPlusOne = array_map('incrementNumber', [1,2,3]);
print_r($numbersPlusOne);

This code works, but it’s not as succinct and tidy as Example 2-20. We don’t need a separate incrementNumber() named function if we use the function only once as a callback. Closures used as callbacks create more concise and legible code.

Attach State

So far I’ve demonstrated nameless (or anonymous) functions used as callbacks. Let’s explore how to attach and enclose state with a PHP closure. JavaScript developers might be confused by PHP closures because they do not automatically enclose application state like true JavaScript closures. Instead, you must manually attach state to a PHP closure with the closure object’s bindTo() method or the use keyword.

It’s far more common to attach closure state with the use keyword, so let’s look at that first (Example 2-21). When you attach a variable to a closure via the use keyword, the attached variable retains the value assigned to it at the time it is attached to the closure.

<?php
function enclosePerson($name) {
    return function ($doCommand) use ($name) {
        return sprintf('%s, %s', $name, $doCommand);
    };
}

// Enclose "Clay" string in closure
$clay = enclosePerson('Clay');

// Invoke closure with command
echo $clay('get me sweet tea!');
// Outputs --> "Clay, get me sweet tea!"

In Example 2-21, the enclosePerson() named function accepts a $name argument, and it returns a closure object that encloses the $name argument. The returned closure object preserves the $name argument’s value even after the closure exits the enclosePerson() function’s scope. The $name variable still exists in the closure!

Don’t forget, PHP closures are objects. Each closure instance has its own internal state that is accessible with the $this keyword just like any other PHP object. A closure object’s default state is pretty boring; it has a magic __invoke() method and a bindTo() method. That’s it.

However, the bindTo() method opens the door to some interesting possibilities. This method lets us bind a Closure object’s internal state to a different object. The bindTo() method accepts an important second argument that specifies the PHP class of the object to which the closure is bound. This lets the closure access protected and private member variables of the object to which it is bound.

You’ll find the bindTo() method is often used by PHP frameworks that map route URLs to anonymous callback functions. Frameworks accept an anonymous function and bind it to the application object. This lets you reference the primary application object inside the anonymous function with the $this keyword, as shown in Example 2-22.

01. <?php
02. class App
03. {
04.     protected $routes = array();
05.     protected $responseStatus = '200 OK';
06      protected $responseContentType = 'text/html';
07.     protected $responseBody = 'Hello world';
08.
09.     public function addRoute($routePath, $routeCallback)
10.     {
11.         $this->routes[$routePath] = $routeCallback->bindTo($this, __CLASS__);
12.     }
13.
14.     public function dispatch($currentPath)
15.     {
16.         foreach ($this->routes as $routePath => $callback) {
17.             if ($routePath === $currentPath) {
18.                 $callback();
19.             }
20.         }
21.
22.         header('HTTP/1.1 ' . $this->responseStatus);
23.         header('Content-type: ' . $this->responseContentType);
24.         header('Content-length: ' . mb_strlen($this->responseBody));
25.         echo $this->responseBody;
26.     }
27. }

Pay close attention to the addRoute() method. It accepts a route path (e.g., /users/josh) and a route callback. The dispatch() method accepts the current HTTP request path and invokes the matching route callback. The magic happens on line 11 when we bind the route callback to the current App instance. This lets us create a callback function that can manipulate the App instance state:

<?php
$app = new App();
$app->addRoute('/users/josh', function () {
    $this->responseContentType = 'application/json;charset=utf8';
    $this->responseBody = '{"name": "Josh"}';
});
$app->dispatch('/users/josh');

Enable Zend OPcache

Zend OPcache isn’t enabled by default; you must explicitly enable Zend OPcache when you compile PHP.

If you compile PHP yourself (i.e., on a VPS or dedicated server), you must include this option in your PHP ./configure command:

--enable-opcache

After you compile PHP, you must also specify the path to the Zend OPcache extension in your php.ini file with this line:

zend_extension=/path/to/opcache.so

The Zend OPcache extension file path is displayed immediately after PHP compiles successfully. If you forget to look for this as I often do, you can also find the PHP extension directory with this command:

php-config --extension-dir

After you update the php.ini file, restart the PHP process and you’re ready to go. You can confirm Zend OPcache is working correctly by creating a PHP file with this content:

<?php
phpinfo();

View this PHP file in a web browser and scroll down until you see the Zend OPcache extension section shown in Figure 2-2. If you don’t see this section, Zend OPcache is not running.

Figure 2-2. Zend OPcache INI settings

Configure Zend OPcache

When Zend OPcache is enabled, you should configure the Zend OPcache settings in your php.ini configuration file. Here are the OPcache settings I like to use:

opcache.validate_timestamps = 1 // "0" in production
opcache.revalidate_freq = 0
opcache.memory_consumption = 64
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 4000
opcache.fast_shutdown = 1

Use Zend OPcache

This part’s easy because the Zend OPcache works automatically when enabled. Zend OPcache automatically caches precompiled PHP bytecode in memory and executes the bytecode if available.

Be careful if the opcache.validate_timestamps INI directive is false. When this setting is false, the Zend OPcache does not know about changes to your PHP scripts, and you must manually clear Zend OPcache’s bytecode cache before it recognizes changes to your PHP files. This setting is good for production but inconvenient for development. You can enable automatic cache revalidation with these php.ini configuration settings:

opcache.validate_timestamps=1
opcache.revalidate_freq=0

Start the Server

It’s easy to start the PHP web server. Open your terminal application, navigate to your project’s document root directory, and execute this command:

php -S localhost:4000

This command starts a new PHP web server accessible at localhost. It listens on port 4000. Your current working directory is the web server’s document root.

You can now open your web browser and navigate to http://localhost:4000 to preview your application. As you browse your application in your web browser, each HTTP request is logged to standard out in your terminal application so you can see if you application throws 400 or 500 responses.

Sometimes it’s useful to access the PHP web server from other machines on your local network (e.g., for previewing on your iPad or local Windows box). To do this, tell the PHP web server to listen on all interfaces by using 0.0.0.0 instead of localhost:

php -S 0.0.0.0:4000

When you are ready to stop the PHP web server, close your terminal application or press Ctrl+C.

Configure the Server

It’s not uncommon for an application to require its own PHP INI configuration file, especially if it has unique requirements for memory usage, file uploads, profiling, or bytecode caching. You can tell the PHP built-in server to use a specific INI file with the -c option:

php -S localhost:8000 -c app/config/php.ini

Router Scripts

The PHP built-in server has one glaring omission. Unlike Apache or nginx, it doesn’t support .htaccess files. This makes it difficult to use front controllers that are common in many popular PHP frameworks.

The PHP built-in server mitigates this omission with router scripts. The router script is executed before every HTTP request. If the router script returns false, the static asset referenced by the current HTTP request URI is returned. Otherwise, the output of the router script is returned as the HTTP response body. In other words, if you use a router script you’re effectively hardcoding the same functionality as an .htaccess file.

Using a router script is easy. Just pass the PHP script file path as a an argument when you start up the PHP built-in server:

php -S localhost:8000 router.php

Detect the Built-in Server

Sometimes it’s helpful to know if your PHP script is served by PHP’s built-in web server versus a traditional web server like Apache or nginx. Perhaps you need to set specific headers for nginx (e.g., Status:) that should not be set for the PHP web server. You can detect the PHP web server with the php_sapi_name() function. This function returns the string cli-server if the current script is served with the PHP built-in server:

<?php
if (php_sapi_name() === 'cli-server') {
    // PHP web server
} else {
    // Other web server
}

Drawbacks

PHP’s built-in web server should not be used for production. It is for local development only. If you use the PHP built-in web server on a production machine, be prepared for a lot of disappointed users and a flood of Pingdom downtime notifications.

• The built-in server performs suboptimally because it handles one request at a time, and each HTTP request is blocking. Your web application will stall if a PHP file must wait on a slow database query or remote API response.

• The built-in server supports only a limited number of mimetypes.

• The built-in server has limited URL rewriting with router scripts. You’ll need Apache or nginx for more advanced URL rewrite behavior.

Interfaces

PHP frameworks work together via shared interfaces. PHP interfaces allow frameworks to assume what methods are provided by third-party dependencies without worrying about how the dependencies implement the interface.

For example, a framework is happy to share a third-party logger object assuming the shared logger object implements the emergency(), alert(), critical(), error(), warning(), notice(), info(), and debug() methods. Exactly how these methods are implemented is irrelevant. Each framework cares only that the third-party dependency does implement these methods.

Interfaces enable PHP developers to build, share, and use specialized components instead of monolithic frameworks.

Autoloading

PHP frameworks work together via autoloading. Autoloading is the process by which a PHP class is automatically located and loaded on-demand by the PHP interpreter during runtime.

Before PHP standards, PHP components and frameworks implemented their own unique autoloaders using the magic \__autoload() method or the more recent spl_autoload_register() method. This required us to learn and use a unique autoloader for each component and framework. Nowadays, most modern PHP components and frameworks are compatible with a common autoloader standard. This means we can mix and match multiple PHP components with only one autoloader.

Style

PHP frameworks work together via code style. Your code style determines spacing, capitalization, and bracket placement (among other things). If PHP frameworks agree on a standard code style, PHP developers don’t need to learn a new style every time they use a new PHP framework. Instead, PHP framework code is immediately familiar. A standard code style also lowers the barrier for new project contributors, who can spend more time squashing bugs and less time learning an unfamiliar style.

Standard code style also improves our own projects. Every developer has a unique style with more than a few idiosyncrasies, and these become a problem when multiple developers work on the same codebase. A standard code style helps all team members immediately understand the same codebase regardless of its author.

Write a PSR-3 Logger

A PHP logger component compatible with the PSR-3 recommendation must include a PHP class that implements the interface named Psr\Log\LoggerInterface. The PSR-3 interface replicates the RFC 5424 syslog protocol and prescribes nine methods:

<?php
namespace Psr\Log;

interface LoggerInterface
{
    public function emergency($message, array $context = array());
    public function alert($message, array $context = array());
    public function critical($message, array $context = array());
    public function error($message, array $context = array());
    public function warning($message, array $context = array());
    public function notice($message, array $context = array());
    public function info($message, array $context = array());
    public function debug($message, array $context = array());
    public function log($level, $message, array $context = array());
}

Each interface method maps to a corresponding RFC 5424 protocol level and accepts two arguments. The first $message argument must be a string or an object with a __toString() method. The second $context argument is optional and provides an array of placeholder values that replace tokens in the first argument.

To write a PSR-3 logger, create a new PHP class that implements the Psr\Log\LoggerInterface interface and provide a concrete implementation for each interface method.

Use a PSR-3 Logger

If you are creating your own PSR-3 logger, stop and reconsider if you are spending your time wisely. I strongly discourage you from writing your own logger. Why? Because there are some truly amazing PHP logger components already available!

If you need a PSR-3 logger, just use monolog/monolog. Don’t waste time looking elsewhere. The Monolog PHP component fully implements the PSR-3 interface, and it’s easily extended with custom message formatters and handlers. Monolog’s message handlers let you send log messages to text files, syslog, email, HipChat, Slack, networked servers, remote APIs, databases, and pretty much anywhere else you can imagine. In the very unlikely event Monolog does not provide a handler for your desired output destination, it’s super-easy to write and integrate your own Monolog message handler. Example 3-1 demonstrates how easy it is to setup Monolog and log messages to a text file.

<?php
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Prepare logger
$log = new Logger('myApp');
$log->pushHandler(new StreamHandler('logs/development.log', Logger::DEBUG));
$log->pushHandler(new StreamHandler('logs/production.log', Logger::WARNING));

// Use logger
$log->debug('This is a debug message');
$log->warning('This is a warning message');

Why Autoloaders Are Important

How often have you seen code like this at the top of your PHP files?

<?php
include 'path/to/file1.php';
include 'path/to/file2.php';
include 'path/to/file3.php';

All too often, right? You’re probably familiar with the require(), require_once(), include(), and include_once() functions. These functions load an external PHP file into the current script, and they work wonderfully if you have only a few PHP scripts. However, what if you need to include a hundred PHP scripts? What if you need to include a thousand PHP scripts? The require() and include() functions do not scale well, and this is why PHP autoloaders are important. An autoloader is a strategy for finding a PHP class, interface, or trait and loading it into the PHP interpreter on-demand at runtime, without explicitly including files as the example does.

Before the PHP-FIG introduced its PSR-4 recommendation, PHP component and framework authors used the __autoload() and spl_autoload_register() functions to register custom autoloader strategies. Unfortunately, each PHP component and framework used a unique autoloader, and every autoloader used different logic to locate and load PHP classes, interfaces, and traits. Developers using these components and frameworks were obliged to invoke each component’s autoloader when bootstrapping a PHP application. I use Sensio Labs’ Twig template component all the time. It’s awesome. Without PSR-4, however, I have to read Twig’s documentation and figure out how to register its custom autoloader in my application’s bootstrap file, like this:

<?php
require_once '/path/to/lib/Twig/Autoloader.php';
Twig_Autoloader::register();

Imagine having to research and register unique autoloaders for every PHP component in your application. The PHP-FIG recognized this problem and proposed the PSR-4 autoloader recommendation to facilitate component interoperability. Thanks to PSR-4, we can autoload all of our application’s PHP components with only one autoloader. This is amazing. Most modern PHP components and frameworks are compatible with PSR-4. If you write and distribute your own components, make sure they are compatible with PSR-4, too! Participating components include Symfony, Doctrine, Monolog, Twig, Guzzle, SwiftMailer, PHPUnit, Carbon, and many others.

The PSR-4 Autoloader Strategy

Like any PHP autoloader, PSR-4 describes a strategy to locate and load PHP classes, interfaces, and traits during runtime. The PSR-4 recommendation does not require you to change your code’s implementation. Instead, PSR-4 only suggests how your code is organized into filesystem directories and PHP namespaces. The PSR-4 autoloader strategy relies on PHP namespaces and filesystem directories to locate and load PHP classes, interfaces, and traits.

The essence of PSR-4 is mapping a top-level namespace prefix to a specific filesystem directory. For example, I can tell PHP that classes, interfaces, or traits beneath the \Oreilly\ModernPHP namespace live beneath the src/ physical filesystem directory. PHP now knows that any classes, interfaces, or traits that use the \Oreilly\ModernPHP namespace prefix correspond to directories and files beneath the src/ directory. For example, the \Oreilly\ModernPHP\Chapter1 namespace corresponds to the src/Chapter1 directory, and the \Oreilly\ModernPHP\Chapter1\Example class corresponds to the src/Chapter1/Example.php file.

Remember when we talked about vendor namespaces in Chapter 2? The PSR-4 autoloader strategy is most relevant to component and framework authors who distribute code to other developers. A PHP component’s code lives beneath a unique vendor namespace, and the component’s author specifies which filesystem directory corresponds to the component’s vendor namespace—exactly as I demonstrated earlier. We’ll explore this concept more in Chapter 4.

How to Write a PSR-4 Autoloader (and Why You Shouldn’t)

We know that PSR-4 compatible code has a namespace prefix that maps to a base filesystem directory. We also know that subnamespaces beneath the namespace prefix map to subdirectories beneath the base filesystem directory. Example 3-2 shows an autoloader implementation, borrowed from the PHP-FIG website, that finds and loads classes, interfaces, and traits based on the PSR-4 autoloader strategy.

<?php
/**
 * An example of a project-specific implementation.
 *
 * After registering this autoload function with SPL, the following line
 * would cause the function to attempt to load the \Foo\Bar\Baz\Qux class
 * from /path/to/project/src/Baz/Qux.php:
 *
 *      new \Foo\Bar\Baz\Qux;
 *
 * @param string $class The fully qualified class name.
 * @return void
 */
spl_autoload_register(function ($class) {

    // project-specific namespace prefix
    $prefix = 'Foo\\Bar\\';

    // base directory for the namespace prefix
    $base_dir = __DIR__ . '/src/';

    // does the class use the namespace prefix?
    $len = strlen($prefix);
    if (strncmp($prefix, $class, $len) !== 0) {
        // no, move to the next registered autoloader
        return;
    }

    // get the relative class name
    $relative_class = substr($class, $len);

    // replace the namespace prefix with the base directory, replace namespace
    // separators with directory separators in the relative class name, append
    // with .php
    $file = $base_dir . str_replace('\\', '/', $relative_class) . '.php';

    // if the file exists, require it
    if (file_exists($file)) {
        require $file;
    }
});

Copy and paste this into your application, change the $prefix and $base_dir variables, and you have yourself a working PSR-4 autoloader. However, if you find yourself writing your own PSR-4 autoloader, stop and ask yourself if what you are doing is really necessary. Why? Because we can use PSR-4 autoloaders that are automagically generated by the Composer dependency manager. Conveniently enough, that’s exactly what we’ll talk about next in Chapter 4.

Not All Frameworks Are Bad

So far I’ve spoken only about the downsides of frameworks. Frameworks are not all bad. Symfony is an excellent example of a modern PHP framework. Fabien Potencier and Sensio Labs built the Symfony Framework as an amalgam of smaller and decoupled Symfony components. These components can be used together as a framework or piecemeal in custom applications.

Other, older frameworks are making a similar transition to modern PHP components. The Drupal content management framework is another example. Drupal 7 is written with procedural PHP code that lives in the global PHP namespace. It ignores modern PHP practices to support its legacy codebase. However, Drupal 8 is a ginormous and commendable leap into modern PHP. Drupal 8 leverages the comparative advantages of many different PHP components to build a modern content management platform.

Laravel is also a popular PHP framework written by Taylor Otwell. Like Symfony, Laravel is built atop its own Illuminate component library. However (at time of publishing), Laravel’s components are not easily decoupled for use in non-Laravel applications. Laravel does not use the PSR-2 community standards, and Laravel does not adhere to the Semantic Versioning scheme. Don’t let this dissuade you though. Laravel is still an amazing framework that can create very powerful applications.

Use the Right Tool for the Job

Should you use components or a framework? Use the right tool for the job. Most modern PHP frameworks are only a set of conventions built atop smaller PHP components.

If you are working on a smaller project that can be solved with a precise collection of PHP components, then use components. Components make it super-easy to shop for and use existing tools so we can focus less on boilerplate and more on the larger task at hand. Components also help our code remain lightweight and nimble. We use only the code we need, and it’s super-easy to swap one component with another that may be better suited for our project.

If you are working on a large project with multiple team members and can benefit from the conventions, discipline, and structure provided by a framework, then use a framework. However, frameworks make many decisions for us and require us to adhere to its set of conventions. Frameworks are less flexible, but we do get far more out-of-the-box than we do with a collection of PHP components. If these tradeoffs are acceptable, by all means use a framework to guide and expedite your project development.

Shop

Do not waste your time solving problems that are already solved. Do you need to send or receive HTTP messages? Go to Packagist and search for http; Guzzle is the first result. Use it. Do you need to parse a CSV file? Go to Packagist and search for csv; pick a CSV component and use it. Think of Packagist as a grocery store for PHP components where you can shop for the best ingredients. Packagist probably has a PHP component that solves your problem.

Choose

What if there are multiple PHP components on Packagist that do what you need? How do you pick the best one? Packagist keeps statistics about each PHP component. Packagist tells you how many times each PHP component has been downloaded and starred (Figure 4-2). More downloads and stars indicate a component may be a good option (this is not always true). That being said, don’t discount newer packages with fewer downloads. Many new components are added every day.

It can be difficult to find the perfect PHP component if your Packagist keyword search returns a large number of results. You can’t always rely on download statistics, because crowds are not always right. This is a problem that Packagist must address as it becomes more popular. I recommend you rely on word of mouth and peer recommendations to confirm your PHP component selection.

Figure 4-2. Packagist website search results

Leave Feedback

If you find a PHP component that you like, star the PHP component on Packagist and share it with your fellow PHP developers on Twitter, Facebook, IRC, Slack, and your other communication channels. This helps the best PHP components bubble up so they are discovered by other developers.

How to Install Composer

Composer is easy to install. Open a terminal and execute this command:

curl -sS https://getcomposer.org/installer | php

This command downloads the Composer installer script with curl, executes the installer script with php, and creates a composer.phar file in the current working directory. The composer.phar file is the Composer binary.

I prefer to move and rename the downloaded Composer binary to /usr/local/bin/composer with this command:

sudo mv composer.phar /usr/local/bin/composer

Be sure you run this command to make the composer binary executable:

sudo chmod +x /usr/local/bin/composer

Finally, add the /usr/local/bin directory to your environment PATH by appending this line to your ~/.bash_profile file:

PATH=/usr/local/bin:$PATH

You should now be able to execute composer in your terminal application to see a list of Composer options (Figure 4-3).

Figure 4-3. Composer command-line options

How to Use Composer

Now that Composer is installed, let’s download some PHP components. Composer is typically used to download PHP components on a per-project basis.

Component names

First, you should make a list of the components you need for your project. Specifically, note each component’s vendor and package names. Each PHP component has a vendor name and a package name. For example, the popular league/flysystem component’s vendor name is league and its package name is flysystem. The vendor and package names are separated with a / character. Together, the vendor and package names form the full component name league/flysystem.

The vendor name is globally unique and provides the global identity to which its encompassed packages belong. The package name uniquely identifies a single package beneath a given vendor name. Composer and Packagist use the vendor/package naming convention to avoid name collisions among PHP components from different vendors. You can find a PHP component’s vendor and package names on the component’s Packagist directory listing (Figure 4-4).

Figure 4-4. Packagist vendor and package name

composer require vendor/package

composer require league/flysystem

Example Project

Let’s reinforce our Composer skills by building an example PHP application that scans URLs from a CSV file and reports all inaccessible URLs. Our project will send an HTTP request to each URL. If a URL returns an HTTP response with a status code greater than or equal to 400, we’ll send the inaccessible URL to standard out. Our project will be a command-line application, and the path to the CSV file will be the first and only command-line argument. Ultimately, we’ll execute our script, pass it the CSV file path, and see a list of inaccessible URLs on standard out:

php scan.php /path/to/urls.csv

Our project directory looks like Figure 4-5.

Figure 4-5. Component directory structure

The first thing I do when starting a new PHP project is determine what tasks can be solved with existing PHP components. The scan.php script opens and iterates a CSV file, so we’ll need a PHP component that can read and iterate CSV data. The scan.php script also sends an HTTP request to each URL in the CSV file, so we’ll need a PHP component that can send HTTP requests and inspect HTTP responses. It is certainly possible to write our own code to iterate a CSV file or send HTTP requests, but why should we waste our time if these problems are already solved? Remember, our goal is to scan a list of URLs. Our job is not to build HTTP and CSV parser libraries.

After browsing Packagist, I find the guzzlehttp/guzzle and league/csv PHP components. The former handles HTTP messages and the latter parses and iterates CSV data. Let’s install these components with Composer using these commands in the project’s topmost directory:

composer require guzzlehttp/guzzle;
composer require league/csv;

These commands instruct Composer to download these two components into a new vendor/ directory in the project’s topmost directory. It also creates a composer.json file and a composer.lock file.

<?php
require 'vendor/autoload.php';

<?php
// 1. Use Composer autoloader
require 'vendor/autoload.php';

// 2. Instantiate Guzzle HTTP client
$client = new \GuzzleHttp\Client();

// 3. Open and iterate CSV
$csv = new \League\Csv\Reader($argv[1]);
foreach ($csv as $csvRow) {
    try {
        // 4. Send HTTP OPTIONS request
        $httpResponse = $client->options($csvRow[0]);

        // 5. Inspect HTTP response status code
        if ($httpResponse->getStatusCode() >= 400) {
            throw new \Exception();
        }
    } catch (\Exception $e) {
        // 6. Send bad URLs to standard out
        echo $csvRow[0] . PHP_EOL;
    }
}

php scan.php urls.csv

Composer and Private Repositories

So far I’ve assumed you are using open source PHP components that are publicly available. As much as I create and use open source software, I recognize that using only open source PHP components may not always be possible. Sometimes we have to mix open source and proprietary components in the same application. This is especially true for companies that use internally developed PHP components that cannot be open sourced due to licensing or security concerns. Composer makes this a nonissue.

Composer can manage private PHP components whose repositories require authentication. When you run composer install or composer update, Composer prompts you if a component’s repository requires authentication credentials. Composer also asks if you want to save the repository authentication credentials in a local auth.json file (created adjacent to the composer.json file). An example auth.json file looks like this:

{
    "http-basic": {
        "example.org": {
            "username": "your-username",
            "password": "your-password"
        }
    }
}

In most cases, you should not version control the auth.json file. Instead, let project developers create their own auth.json file with their own authentication credentials.

If you’d rather not wait for Composer to request authentication credentials, you can manually tell Composer your authentication credentials for a remote machine with this command:

composer config http-basic.example.org your-username your-password

In this example, http-basic lets Composer know we are adding authentication details for a given domain. The example.org hostname identifies the remote machine that contains the private component repository. The final two arguments are the username and password credentials. By default, this command saves credentials in the current project’s auth.json file.

You can also save authentication credentials system-wide by using the --global flag. This flag lets Composer use your credentials for all projects on your local machine:

composer config --global http-basic.example.org your-username your-password

Global credentials are saved in the ~/.composer/auth.json file. If you are using Windows, global credentials are saved in %APPDATA%/Composer.

Vendor and Package Names

Before I build a PHP component, I choose the component’s vendor and package name. Remember, each PHP component uses a globally unique vendor and package name combination to avoid name collisions with other components. I recommend you use only lowercase letters for your vendor and package names.

A vendor name is the brand or identity to which a component belongs. Many of my own PHP components use the codeguy vendor name because this is my online identity. Choose a vendor name that best represents you or your component’s brand.

A package name identifies a PHP component beneath a given vendor name. Many components can live beneath a single vendor name. For this example, I’ll use modernphp as the vendor name and scanner as the package name.

Namespaces

As we discussed in Chapter 2, each component lives beneath its own PHP namespace so that it does not pollute the global namespace or collide with other components that use the same PHP class names.

A common misconception is that the component’s PHP namespace must match the component’s vendor and package names. This is not true. The component’s PHP namespace is unrelated to the component’s vendor and package names. The vendor and package names are only used by Packagist and Composer to identify a component. You use the component’s namespace when using the component in your PHP code.

For this tutorial, we’ll create our component beneath the PHP namespace Oreilly\ModernPHP. This namespace does not exist yet. I just pulled this out of thin air for this particular component.

Filesystem Organization

PHP components have largely standardized on this filesystem structure:

src/

This directory contains the component’s source code (e.g., PHP class files).

tests/

This directory contains the component’s tests. We will not use this directory in this example.

composer.json

This is the Composer configuration file. This file describes the component and tells Composer’s autoloader to map your component’s PSR-4 namespace to the src/ directory.

README.md

This Markdown file provides helpful information about this component, including its name, description, author, usage, contributor guidelines, software license, and credits.

CONTRIBUTING.md

This Markdown file describes how others can contribute to this component.

LICENSE

This plain-text file contains the component’s software license.

CHANGELOG.md

This Markdown file lists changes introduced in each new component version.

The composer.json File

The composer.json file is required and must contain valid JSON. It includes information used by Composer to find, install, and autoload the PHP component. It also contains information for the component’s Packagist directory listing.

Example 4-2 shows a composer.json file for our URL scanner component. It includes all of the composer.json properties that I use most often for my own PHP components.

{
    "name": "modernphp/scanner",
    "description": "Scan URLs from a CSV file and report inaccessible URLs",
    "keywords": ["url", "scanner", "csv"],
    "homepage": "http://example.com",
    "license": "MIT",
    "authors": [
        {
            "name": "Josh Lockhart",
            "homepage": "https://github.com/codeguy",
            "role": "Developer"
        }
    ],
    "support": {
        "email": "help@example.com"
    },
    "require": {
        "php" : ">=5.4.0",
        "guzzlehttp/guzzle": "~5.0"
    },
    "require-dev": {
        "phpunit/phpunit": "~4.3"
    },
    "suggest": {
        "league/csv": "~6.0"
    },
    "autoload": {
        "psr-4": {
            "Oreilly\\ModernPHP\\": "src/"
        }
    }
}

This is admittedly a lot to digest, so let’s step through each composer.json property in detail:

name

This is the component’s vendor and package name, separated with a / character. This value is displayed on Packagist.

description

This contains a few sentences that succinctly describe the component. This description is displayed on Packagist.

keywords

This contains an appropriate number of keywords that describe the component. These keywords help others find this component on Packagist.

homepage

This is the URL of the component’s website.

license

This is the software license with which the PHP component is released. I prefer to use the MIT Public License. You can read more about software licenses at http://choosealicense.com. Remember to always release your code with a license.

authors

This is an array of information for each project author. You should include at least a name and URL for each author.

support

This is how the component’s users find technical support. I prefer to include an email address and support forum URL. You could also list an IRC channel, for example.

require

This lists the PHP component’s own component dependencies. You should list each dependency’s vendor/package name and minimum version number. I also like to list the minimum PHP version required by this component. All dependencies listed beneath this property are installed for both development and production project installations.

require-dev

This acts like the require property, but it lists only the dependencies required to develop this component. For example, I often list phpunit as a dev dependency so that other component contributors can write and run tests. These dependencies are installed only during development. They are not installed in production projects.

suggest

This acts like the require property, but it merely suggests other components because they may be useful when used with our component. Unlike the require property, this object’s values are free text fields that describe each suggested component. Composer does not install suggested components.

autoload

This tells the Composer autoloader how to autoload this component. I recommend you use the PSR-4 autoloader, as demonstrated in Example 4-2. Beneath the psr-4 property, you map the component’s namespace prefix to a filesystem path relative to the component’s root directory. This makes our component compatible with a standard PSR-4 autoloader. In Example 4-2, I map the Oreilly\ModernPHP namespace to the src/ directory. The mapping’s namespace must end with two back slash characters (\\) to avoid conflicts with other components that use a namespace with a similar sequence of characters. Based on the example mapping, if we instantiate a hypothetical Oreilly\ModernPHP\Url\Scanner class, Composer will autoload the PHP class file at src/Url/Scanner.php.

The README file

The README file is often the component’s first introduction to its users. This is especially true for components hosted on GitHub and Bitbucket. Therefore, it’s important that the component’s README file provides, at a minimum, this information:

• Component name and description

• Install instructions

• Usage instructions

• Testing instructions

• Contributing instructions

• Support resources

• Author credits

• Software license

Component Implementation

And now we arrive at the component’s meat and potatoes—its implementation. This is where you write the PHP classes, interfaces, and traits that form the PHP component. What classes you write, and how many, depends entirely on the PHP component’s purpose. However, all component classes, interfaces, and traits must live in the src/ directory and exist beneath the component’s namespace prefix listed in the composer.json file.

For this demonstration, I’ll create a single PHP class named Scanner that exists beneath the Url subnamespace beneath the Oreilly\ModernPHP namespace listed in the composer.json file. The Scanner class file lives at src/Url/Scanner.php. The Scanner class implements the same logic as our earlier URL scanner example application, except it encapsulates the URL scanning behavior in a PHP class (Example 4-3).

<?php
namespace Oreilly\ModernPHP\Url;

class Scanner
{
    /**
     * @var array An array of URLs
     */
    protected $urls;

    /**
     * @var \GuzzleHttp\Client
     */
    protected $httpClient;

    /**
     * Constructor
     * @param array $urls An array of URLs to scan
     */
    public function __construct(array $urls)
    {
        $this->urls = $urls;
        $this->httpClient = new \GuzzleHttp\Client();
    }

    /**
     * Get invalid URLs
     * @return array
     */
    public function getInvalidUrls()
    {
        $invalidUrls = [];
        foreach ($this->urls as $url) {
            try {
                $statusCode = $this->getStatusCodeForUrl($url);
            } catch (\Exception $e) {
                $statusCode = 500;
            }

            if ($statusCode >= 400) {
                array_push($invalidUrls, [
                    'url' => $url,
                    'status' => $statusCode
                ]);
            }
        }

        return $invalidUrls;
    }

    /**
     * Get HTTP status code for URL
     * @param string $url The remote URL
     * @return int The HTTP status code
     */
    protected function getStatusCodeForUrl($url)
    {
        $httpResponse = $this->httpClient->options($url);

        return $httpResponse->getStatusCode();
    }
}

Instead of parsing and iterating a CSV file, we inject an array of URLs into the Scanner class constructor. We want our URL scanner class to be as generic as possible. If we demand a CSV file, we inherently limit our component’s usefulness. If we accept an array of URLs, we let the end user decide how to fetch an array of URLs (from a PHP array, a CSV file, an iterator, etc). That being said, we still recommend the league/csv component because it can be helpful for developers using our component. We include the league/csv component in the composer.json manifest’s suggest property.

The Scanner class has a hard dependency on the guzzlehttp/guzzle component. However, we isolate each URL’s HTTP request in the getStatusCodeForUrl() method. This lets us stub (or override) this method’s implementation in our component’s unit tests so that our tests do not rely on a working Internet connection.

Version Control

We’re almost done. Before we submit our component to Packagist, we must publish it to a public code repository. I prefer to publish my open source PHP components to GitHub. However, any public Git repository is fine (I have published this component to GitHub).

It’s also a good idea to tag each component release using the Semantic Versioning scheme. This lets component consumers request specific versions of your component (e.g., ~1.2). I’ll create a 1.0.0 tag for the URL scanner component.

Packagist Submission

Now we’re ready to submit the component to Packagist. If you don’t use GitHub, go ahead and create a Packagist account. You can also log in to Packagist with your GitHub credentials.

Once logged in, click the big green Submit Package button at the top right of the website. Enter the full Git repository URL into the Repository URL text field and click the Check button. Packagist verifies the repository URL and prompts you to confirm your submission. Click Submit to finalize your component submission. Packagist creates and redirects you to the component listing, which looks Figure 4-6.

Figure 4-6. Packagist component listing

You’ll notice it pulls the component name, description, keywords, dependencies, and suggestions from the component’s composer.json file. You’ll also notice that it shows the repository branches and tags, too. Packagist establishes a direct correlation between repository tags and semantic version numbers. This is why I recommend your repository tags be valid version numbers like 1.0.0, 1.1.0, and so on. However, we still have that big red alert message that reads:

This package is not auto-updated. Please set up the GitHub Service Hook for
Packagist so that it gets updated whenever you push!

We can activate a GitHub or Bitbucket hook that notifies Packagist whenever the component repository is updated. Learn how to setup this repository hook at https://packagist.org/profile/.

Using the Component

We’re done! Now anyone can install the URL scanner component with Composer and use it in their PHP applications. Run this command in your terminal to install the URL scanner component with Composer:

composer require modernphp/scanner

Then you can use the URL scanner component, as shown in Example 4-4.

<?php
require 'vendor/autoload.php';

$urls = [
    'http://www.apple.com',
    'http://php.net',
    'http://sdfssdwerw.org'
];
$scanner = new \Oreilly\ModernPHP\Url\Scanner($urls);
print_r($scanner->getInvalidUrls());

Sanitize Input

When you sanitize input (i.e., data from any of the sources listed previously), you escape or remove unsafe characters. It’s important to sanitize input data before it reaches your application’s storage layer (e.g., Redis or MySQL). This is your first line of defense. For example, assume your website comment form accepts HTML. By default, nothing prevents a visitor from adding a devious <script> tag to the comment text like this:

<p>
    This was a helpful article!
</p>
<script>window.location.href='http://example.com';</script>

If you don’t sanitize this comment, you’ll inject malevolent code into your database that can be rendered into your website’s markup. When your website visitors go to a page with this unsanitized comment, they’re redirected to a website that does bad things. This is one example why you must sanitize input data that you do not control. In my experience, there are several types of input data that you’ll run into most often: HTML, SQL queries, and user profile information (i.e., email addresses and phone numbers).

<?php
$input = '<p><script>alert("You won the Nigerian lottery!");</script></p>';
echo htmlentities($input, ENT_QUOTES, 'UTF-8');

$sql = sprintf(
    'UPDATE users SET password = "%s" WHERE id = %s',
    $_POST['password'],
    $_GET['id']
);

POST /user?id=1 HTTP/1.1
Content-Length: 17
Content-Type: application/x-www-form-urlencoded

password=abc";--

<?php
$email = 'john@example.com';
$emailSafe = filter_var($email, FILTER_SANITIZE_EMAIL);

<?php
$string = "\nIñtërnâtiônàlizætiøn\t";
$safeString = filter_var(
    $string,
    FILTER_SANITIZE_STRING,
    FILTER_FLAG_STRIP_LOW|FILTER_FLAG_ENCODE_HIGH
);

Validate Data

It is also important to validate data. Unlike sanitization, validation does not remove information from input data. Validation only confirms that input data meets your expectations. If you expect an email address, make sure the input data is an email address. If you expect a phone number, make sure the input data is a phone number. That’s all there is to it. Validation ensures that you persist accurate and well-formatted information in your application’s storage layer. If you encounter invalid data, you can abort the data persistence operation and surface an appropriate error message to your application’s user. Validation also prevents potential database errors. For example, if MySQL expects a DATETIME value but is given the string next year, MySQL will either error out or use a default (and incorrect) value. Either way, your application’s data integrity is compromised by invalid data.

You can validate user input with the filter_var() function with any of the FILTER_VALIDATE_* flags. PHP provides flags to validate Booleans, emails, floats, integers, IP addresses, regular expressions, and URLs. Example 5-5 demonstrates how to validate an email address.

<?php
$input = 'john@example.com';
$isEmail = filter_var($input, FILTER_VALIDATE_EMAIL);
if ($isEmail !== false) {
    echo "Success";
} else {
    echo "Fail";
}

Pay close attention to the filter_var() function’s return value. If the validation succeeds, the return value is the original validated value. If the validation fails, the return value is false.

Although the filter_var() function provides a number of validation flags, it cannot validate everything. I recommend these additional validation components, too:

• aura/filter

• respect/validation

• symfony/validator

Escape Output

When it’s time to render output to a web page or API response, it is very important that you escape your output. This is one more layer of protection that prevents malicious code from being rendered and inadvertently executed by your application’s users.

Escape output with the PHP htmlentities() function that we mentioned earlier. Be sure you use ENT_QUOTES as the second argument so that it escapes both single and double quotes. Specify the appropriate character encoding (usually UTF-8) as the third argument. Example 5-6 demonstrates how to escape HTML output before it is rendered.

<?php
$output = '<p><script>alert("NSA backdoor installed");</script>';
echo htmlentities($output, ENT_QUOTES, 'UTF-8');

Some PHP template engines like twig/twig (my favorite) or smarty/smarty escape output automatically. The Twig template engine by Sensio Labs, for example, escapes all output by default unless you tell it otherwise. This is a brilliant default and provides a nice safety net for your PHP web applications.

Never Know User Passwords

You should never know your users’ passwords. You should never be able to know your users’ passwords. If your application’s database is hacked, you don’t want plain-text or decryptable passwords sitting in your database. Leaked passwords are a serious breach of trust, and they dump a mountain of legal liability on you or your company. The less you know, the safer you are.

Never Restrict User Passwords

It frustrates me when a website requires my account password to satisfy a specific format. It makes me even angrier when my account password cannot be longer than {N} number of characters. Why!? I understand that password formats may be restricted for compatibility with legacy applications or databases, but this is not an excuse for poor security practices.

Never restrict your users’ passwords. If you require passwords to fit a particular pattern, you are effectively providing a roadmap for bad guys to hack your application. If you must restrict user passwords, I recommend you only require a minimum length. It is not unreasonable to blacklist commonly used or dictionary-based passwords, too.

Never Email User Passwords

Never send passwords via email. If you send my password via email, I know three things: you know my password; you are storing my password in plain text or in a decryptable format; and you have no qualms sending my password over the Internet in plain text.

Instead, send an email with a URL where I can choose or change my own password. Web applications often generate a unique token that can only be used once to choose or change a password. For example, suppose I forget my account password for your web application. I click the “Forgot password” link on your login form, and I am directed to a form where I enter my email address to request a new password. Your application generates a unique token, and it associates this token with the account identified by my email address. Your application sends an email to the account’s email address with a URL that includes the unique token as a URL segment or a query-string parameter. When I visit the URL, your application validates the token and, if the token is valid, allows me to choose a new password for my account. After I choose a new password, your application invalidates the token.

Hash User Passwords with bcrypt

You should hash user passwords. Do not encrypt user passwords. Encryption and hashing are not synonymous. Encryption is a two-way algorithm, meaning what is encrypted can later be decrypted by design. Hashing is a one-way algorithm. Hashed data cannot be reverted to its original form, and identical data always produces the same hash values.

When you store a user password in your database, you hash the password first and store the password hash in your database. If hackers break into your database, they see only meaningless password hashes that require a massive amount of time and NSA resources to crack.

Many hashing algorithms are available (e.g., MD5, SHA1, bcrypt, scrypt). Some are fast and designed to verify data integrity. Others are slow and designed to be safe and secure. Slow, safe, and secure are what we want when it comes to password generation and storage.

The most secure peer-reviewed hashing algorithm known today is bcrypt. Unlike MD5 and SHA1, bcrypt is designed to be very slow. The bcrypt algorithm automatically salts data to foil potential rainbow table attacks. The bcrypt algorithm also consumes a large amount of time (measured in seconds) while iteratively hashing data to generate a super-secure final hash value. The number of hash iterations is called the work factor. A higher work factor makes it exponentially more expensive for a bad guy to crack password hashes. The bcrypt algorithm is future-proof, too, because you can simply increase its work factor as computers become faster.

The bcrypt algorithm is extensively peer-reviewed. Minds far greater than my own have reviewed the bcrypt algorithm for potential exploits, and so far none has been found. It is very important that you rely on peer-reviewed hashing algorithms. Never create your own. There is safety in numbers, and odds are you are not a cryptography expert (unless you are, in which case tell Bruce Schneier I said hello).

Password Hashing API

As you can see, there are a lot of considerations to make when working with user passwords. However, Anthony Ferrara was kind enough to build the native password hashing API available in PHP 5.5.0. PHP’s native password hashing API provides easy-to-use functions that drastically simplify password hashing and verification. The password hashing API also uses the bcrypt hashing algorithm by default.

You’ll encounter two scenarios when building web applications: user registration and user login. Let’s explore how the PHP password hashing API simplifies both scenarios.

POST /register.php HTTP/1.1
Content-Length: 43
Content-Type: application/x-www-form-urlencoded

email=john@example.com&password=sekritshhh!

01 <?php
02 try {
03     // Validate email
04     $email = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);
05     if (!$email) {
06         throw new Exception('Invalid email');
07     }
08
09     // Validate password
10     $password = filter_input(INPUT_POST, 'password');
11     if (!$password || mb_strlen($password) < 8) {
12         throw new Exception('Password must contain 8+ characters');
13     }
14
15     // Create password hash
16     $passwordHash = password_hash(
17        $password,
18        PASSWORD_DEFAULT,
19        ['cost' => 12]
20     );
21     if ($passwordHash === false) {
22         throw new Exception('Password hash failed');
23     }
24
25     // Create user account (THIS IS PSUEDO-CODE)
26     $user = new User();
27     $user->email = $email;
28     $user->password_hash = $passwordHash;
29     $user->save();
30
31     // Redirect to login page
32     header('HTTP/1.1 302 Redirect');
33     header('Location: /login.php');
34 } catch (Exception $e) {
35     // Report error
36     header('HTTP/1.1 400 Bad request');
37     echo $e->getMessage();
38 }

POST /login.php HTTP/1.1
Content-Length: 43
Content-Type: application/x-www-form-urlencoded

email=john@example.com&password=sekritshhh!

01 <?php
02 session_start();
03 try {
04     // Get email address from request body
05     $email = filter_input(INPUT_POST, 'email');
06
07     // Get password from request body
08     $password = filter_input(INPUT_POST, 'password');
09
10     // Find account with email address (THIS IS PSUEDO-CODE)
11     $user = User::findByEmail($email);
12
13     // Verify password with account password hash
14     if (password_verify($password, $user->password_hash) === false) {
15         throw new Exception('Invalid password');
16     }
17
18     // Re-hash password if necessary (see note below)
19     $currentHashAlgorithm = PASSWORD_DEFAULT;
20     $currentHashOptions = array('cost' => 15);
21     $passwordNeedsRehash = password_needs_rehash(
22         $user->password_hash,
23         $currentHashAlgorithm,
24         $currentHashOptions
25     );
26     if ($passwordNeedsRehash === true) {
27         // Save new password hash (THIS IS PSUEDO-CODE)
28         $user->password_hash = password_hash(
29             $password,
30             $currentHashAlgorithm,
31             $currentHashOptions
32         );
33         $user->save();
34     }
35
36     // Save login status to session
37     $_SESSION['user_logged_in'] = 'yes';
38     $_SESSION['user_email'] = $email;
39
40     // Redirect to profile page
41     header('HTTP/1.1 302 Redirect');
42     header('Location: /user-profile.php');
43 } catch (Exception $e) {
44     header('HTTP/1.1 401 Unauthorized');
45     echo $e->getMessage();
46 }

Password Hashing API for PHP < 5.5.0

If you cannot use PHP 5.5.0 or newer, fear not. You can use Anthony Ferrara’s ircmaxell/password-compat component. It implements all of these PHP password hashing API functions:

• password_hash()

• password_get_info()

• password_needs_rehash()

• password_verify()

Ferrara’s ircmaxell/password-compat component is a drop-in replacement for the modern PHP password hashing API. Include the component in your application with Composer and you’re off and running.

Set a Default Time Zone

The first thing you should do is declare a default time zone for PHP’s date and time functions. If you don’t set a default time zone, PHP shows an E_WARNING message. There are two ways to set the default time zone. You can declare the default time zone in the php.ini file like this:

date.timezone = 'America/New_York';

You can also declare the default time zone during runtime with the date_default_timezone_set() function (Example 5-9).

<?php
date_default_timezone_set('America/New_York');

Either solution requires a valid time-zone identifier. You can find a complete list of PHP time-zone identifiers at http://php.net/manual/timezones.php.

The DateTime Class

The DateTime class provides an object-oriented interface to manage date and time values. A single DateTime instance represents a specific date and time. The DateTime class constructor (Example 5-10) is the simplest way to create a new DateTime instance.

<?php
$datetime = new DateTime();

Without arguments, the DateTime class constructor creates an instance that represents the current date and time. You can pass a string argument into the DateTime class constructor to specify a custom date and time (Example 5-11). The string argument must use one of the valid date and time formats listed at http://php.net/manual/datetime.formats.php.

<?php
$datetime = new DateTime('2014-04-27 5:03 AM');

In an ideal world, you are given date and time data in a format that PHP understands. Unfortunately, this is not always the case. Sometimes you must work with date and time values in different and unexpected formats. I experience this problem on a daily basis. Many of my clients send Excel spreadsheets with data to import into an application, and each client provides date and time values in wildly different formats. The DateTime class makes this a nonissue.

Use the DateTime::createFromFormat() static method to create a DateTime instance with a date and time string that uses a custom format. This method’s first argument is the date and time string format. The second argument is the date and time string that uses said format (Example 5-12).

<?php
$datetime = DateTime::createFromFormat('M j, Y H:i:s', 'Jan 2, 2014 23:04:12');

The DateInterval Class

The DateInterval class is pretty much prerequisite knowledge for manipulating DateTime instances. A DateInterval instance represents a fixed length of time (e.g., “two days”) or a relative length of time (e.g., “yesterday”). You use DateInterval instances to modify DateTime instances. For example, the DateTime class provides add() and sub() methods to manipulate a DateTime instance’s value. Both methods accept a DateInterval argument that specifies the amount of time added to or subtracted from a DateTime instance.

Instantiate the DateInterval class with its constructor. The DateInterval class constructor accepts a string argument that provides an interval specification. Interval specifications are a little tricky at first, but there’s not much to them. First, an interval specification is a string that begins with the letter P. Next, you append an integer. And last, you append a period designator that qualifies the preceding integer value. Valid period designators are:

• Y (years)

• M (months)

• D (days)

• W (weeks)

• H (hours)

• M (minutes)

• S (seconds)

An interval specification can include both date and time values. If you include a time value, separate the date and time parts with the letter T. For example, the interval specification P2D means two days. The interval specification P2DT5H2M means two days, five hours, and two minutes.

Example 5-13 demonstrates how to modify a DateTime instance by a given interval of time using the add() method.

<?php
// Create DateTime instance
$datetime = new DateTime('2014-01-01 14:00:00');

// Create two weeks interval
$interval = new DateInterval('P2W');

// Modify DateTime instance
$datetime->add($interval);
echo $datetime->format('Y-m-d H:i:s');

You can create an inverted DateInterval, too (Example 5-14). This lets you traverse a DatePeriod instance in reverse chronology!

$dateStart = new \DateTime();
$dateInterval = \DateInterval::createFromDateString('-1 day');
$datePeriod = new \DatePeriod($dateStart, $dateInterval, 3);
foreach ($datePeriod as $date) {
    echo $date->format('Y-m-d'), PHP_EOL;
}

This outputs:

2014-12-08
2014-12-07
2014-12-06
2014-12-05

The DateTimeZone Class

If your application caters to an international clientele, you’ve probably wrestled with time zones. Time zones are tricky, and they are a constant source of confusion for many PHP developers.

PHP represents time zones with the DateTimeZone class. All you have to do is pass a valid time-zone identifier into the DateTimeZone class constructor:

<?php
$timezone = new DateTimeZone('America/New_York');

You often use DateTimeZone instances when creating DateTime instances. The DateTime class constructor’s optional second argument is a DateTimeZone instance. The DateTime instance’s value, and all modifications to its value, are now relative to the specified time zone. If you omit the constructor’s second argument, the time zone is determined by your default time-zone setting:

<?php
$timezone = new DateTimeZone('America/New_York');
$datetime = new DateTime('2014-08-20', $timezone);

You can change a DateTime instance’s time zone after instantiation with the setTimezone() method (Example 5-15).

<?php
$timezone = new DateTimeZone('America/New_York');
$datetime = new \DateTime('2014-08-20', $timezone);
$datetime->setTimezone(new DateTimeZone('Asia/Hong_Kong'));

I find it easiest if I always work in the UTC time zone. My server’s time zone is UTC, and my PHP default time zone is UTC. If I persist date and time values into a database, I save them as the UTC timezone. I convert the UTC date and time values to the appropriate time zone when I display the data to application users.

The DatePeriod Class

Sometimes you need to iterate a sequence of dates and times that recur over a specific interval of time. Repeating calendar events are a good example. The DatePeriod class solves this problem. The DatePeriod class constructor accepts three required arguments:

• A DateTime instance that represents the date and time from which iteration begins

• A DateInterval instance that represents the interval of time between subsequent dates and times

• An integer that represents the number of total iterations

A DatePeriod instance is an iterator, and each iteration yields a DateTime instance. Example 5-16 yields three dates and times separated by two-week intervals.

<?php
$start = new DateTime();
$interval = new DateInterval('P2W');
$period = new DatePeriod($start, $interval, 3);

foreach ($period as $nextDateTime) {
    echo $nextDateTime->format('Y-m-d H:i:s'), PHP_EOL;
}

The DatePeriod class constructor accepts an optional fourth argument that specifies the period’s explicit end date and time. If you want to exclude the start date from the period’s iteration, pass the DatePeriod::EXCLUDE_START_DATE constant as the final constructor argument (Example 5-17).

<?php
$start = new DateTime();
$interval = new DateInterval('P2W');
$period = new DatePeriod(
    $start,
    $interval,
    3,
    DatePeriod::EXCLUDE_START_DATE
);

foreach ($period as $nextDateTime) {
    echo $nextDateTime->format('Y-m-d H:i:s'), PHP_EOL;
}

The nesbot/carbon Component

If you work with dates and times more often than not, you should use Brian Nesbitt’s nesbot/carbon PHP component. Carbon provides a simple user interface with many useful methods for working with date and time values.

The PDO Extension

This is exactly why PHP provides the native PDO extension. PDO (or PHP data objects) is a collection of PHP classes that communicate with many different SQL databases via a single user interface. Database implementations are abstracted away. Instead, we can write and execute database queries with a single interface regardless of the particular database system we happen to be using at the time.

Database Connections and DSNs

First, select the database system most appropriate for your application. Install the database, create the schema, and optionally load an initial dataset. Next, instantiate the PDO class in PHP. The PDO instance establishes a connection between PHP and the database.

The PDO class constructor accepts a string argument called a DSN, or data source name, that provides database connection details. A DSN begins with the database driver name (e.g., mysql or sqlite), a :, and the remainder of the connection string. The DSN connection string is different for each database, but it typically includes:

• Hostname or IP address

• Port number

• Database name

• Character set

The PDO class constructor’s second and third arguments are a username and password for your database. Provide these arguments if your database requires authentication.

Example 5-18 establishes a PDO connection to a MySQL database named acme. The database is available at IP address 127.0.0.1, and it listens on the standard MySQL port 3306. The database username is josh, and the database password is sekrit. The connection character set is utf8.

<?php
try {
    $pdo = new PDO(
        'mysql:host=127.0.0.1;dbname=books;port=3306;charset=utf8',
        'USERNAME',
        'PASSWORD'
    );
} catch (PDOException $e) {
    // Database connection failed
    echo "Database connection failed";
    exit;
}

The PDO class constructor’s first argument is the DSN. The DSN begins with mysql:. This instructs PDO to use the PDO MySQL driver to connect to a MySQL database. After the : character, we specify a semicolon-delimited list of keys and values. Specifically, we specify the host, dbname, port, and charset settings.

[project_root]
    settings.php
    public_html/ <-- document root
        index.php

<?php
$settings = [
    'host' => '127.0.0.1',
    'port' => '3306',
    'name' => 'acme',
    'username' => 'USERNAME',
    'password' => 'PASSWORD',
    'charset' => 'utf8'
];

<?php
include('../settings.php');

$pdo = new PDO(
    sprintf(
        'mysql:host=%s;dbname=%s;port=%s;charset=%s',
        $settings['host'],
        $settings['name'],
        $settings['port'],
        $settings['charset']
    ),
    $settings['username'],
    $settings['password']
);

Prepared Statements

We now have a PDO connection to a database, and we can use this connection to read from and write to the database with SQL statements. We’re not done yet. When I build PHP applications, I often need to customize SQL statements with dynamic information from the current HTTP request. For example, the URL /user?email=john@example.com shows profile information for a specific user account. The SQL statement for this URL might be:

SELECT id FROM users WHERE email = "john@example.com";

A beginner PHP developer might build the SQL statement like this:

$sql = sprintf(
    'SELECT id FROM users WHERE email = "%s"',
    filter_input(INPUT_GET, 'email')
);

This is bad because the SQL string uses raw input from the HTTP request query string. It provides a welcome mat for hackers to do bad things to your PHP application. Haven’t you heard of little Bobby Tables? It is extremely important to sanitize user input that is used in a SQL statement. Fortunately, the PDO extension makes input sanitization super-easy with prepared statements and bound parameters.

A prepared statement is a PDOStatement instance. However, I rarely instantiate the PDOStatement class directly. Instead, I fetch a prepared statement object with the PDO instance’s prepare() method. This method accepts a SQL statement string as its first argument, and it returns a PDOStatement instance:

<?php
$sql = 'SELECT id FROM users WHERE email = :email';
$statement = $pdo->prepare($sql);

Pay close attention to the SQL statement. The :email is a named placeholder to which I can safely bind any value. In Example 5-20, I bind the HTTP request query string to the :email placeholder with the $statement instance’s bindValue() method.

<?php
$sql = 'SELECT id FROM users WHERE email = :email';
$statement = $pdo->prepare($sql);

$email = filter_input(INPUT_GET, 'email');
$statement->bindValue(':email', $email);

The prepared statement automatically sanitizes the $email value, and it protects our database from SQL injection attacks. You can include multiple named placeholders in a SQL statement string and invoke the prepared statement’s bindValue() method for each placeholder.

In Example 5-20, the :email named placeholder represents a string value. What if we change our SQL statement to find a user by a numeric ID? In this case, we must pass a third argument to the prepared statement’s bindValue() method to specify the type of data bound to the placeholder. Without the third argument, a prepared statement assumes bound data is a string.

Example 5-21 shows a modification of Example 5-20 that finds a user by numeric ID instead of an email address. The numeric ID is pulled from the HTTP query string parameter named id.

<?php
$sql = 'SELECT email FROM users WHERE id = :id';
$statement = $pdo->prepare($sql);

$userId = filter_input(INPUT_GET, 'id');
$statement->bindValue(':id', $userId, PDO::PARAM_INT);

We use the PDO::PARAM_INT constant as the third argument. This tells PDO that the bound data is an integer. There are several PDO constants you can use to specify various data types:

PDO::PARAM_BOOL
PDO::PARAM_NULL
PDO::PARAM_INT
PDO::PARAM_STR (default)

Query Results

We now have a prepared statement, and we’re ready to execute SQL queries against the database. The prepared statement’s execute() method executes the statement’s SQL statement with any bound data. If you are executing INSERT, UPDATE, or DELETE statements, invoke the execute() method and you’re done. If you execute a SELECT statement, you probably expect the database to return matching records. You can fetch query results with the prepared statement’s fetch(), fetchAll(), fetchColumn(), and fetchObject() methods.

The PDOStatement instance’s fetch() method returns the next row from the result set. I use this method to iterate large result sets, especially if the entire result set cannot fit in available memory (Example 5-22).

<?php
// Build and execute SQL query
$sql = 'SELECT id, email FROM users WHERE email = :email';
$statement = $pdo->prepare($sql);
$email = filter_input(INPUT_GET, 'email');
$statement->bindValue(':email', $email, PDO::PARAM_INT);
$statement->execute();

// Iterate results
while (($result = $statement->fetch(PDO::FETCH_ASSOC)) !== false) {
    echo $result['email'];
}

In this example, I use the PDO::FETCH_ASSOC constant as the first argument in the statement instance’s fetch() method. This argument determines how the fetch() and fetchAll() methods return query results. You can use any of these constants:

PDO::FETCH_ASSOC

Prompts the fetch() or fetchAll() method to return an associative array. The array keys are database column names.

PDO::FETCH_NUM

Prompts the fetch() or fetchAll() method to return a numeric array. The array keys are the numeric index of database columns in your query result.

PDO::FETCH_BOTH

Prompts the fetch() or fetchAll() method to return an array that contains both associative and numeric array keys. This is a combination of PDO::FETCH_ASSOC and PDO::FETCH_NUM.

PDO::FETCH_OBJ

Prompts the fetch() or fetchAll() method to return an object whose properties are database column names.

If you are working with smaller result sets, you can fetch all query results with the prepared statement’s fetchAll() method (Example 5-23). I typically discourage this method unless you are absolutely sure the complete query result is small enough to fit in available memory.

<?php
// Build and execute SQL query
$sql = 'SELECT id, email FROM users WHERE email = :email';
$statement = $pdo->prepare($sql);
$email = filter_input(INPUT_GET, 'email');
$statement->bindValue(':email', $email, PDO::PARAM_INT);
$statement->execute();

// Iterate results
$results = $statement->fetchAll(PDO::FETCH_ASSOC);
foreach ($results as $result) {
    echo $result['email'];
}

If you are concerned only with a single column in your query result, you can use the prepared statement’s fetchColumn() method. This method, similar to the fetch() method, returns the value of a single column from the next row of the query result (Example 5-24). The fetchColumn() method’s one and only argument is the index of the desired column.

<?php
// Build and execute SQL query
$sql = 'SELECT id, email FROM users WHERE email = :email';
$statement = $pdo->prepare($sql);
$email = filter_input(INPUT_GET, 'email');
$statement->bindValue(':email', $email, PDO::PARAM_INT);
$statement->execute();

// Iterate results
while (($email = $statement->fetchColumn(1)) !== false) {
    echo $email;
}

In Example 5-24, the email column is listed second in the SQL query. It therefore becomes the second column in each query result row, and I pass the number 1 into the fetchColumn() method (columns are zero-indexed).

You can also use the prepared statement’s fetchObject() method to fetch the next query result row as an object whose property names are the SQL query result columns (Example 5-25).

<?php
// Build and execute SQL query
$sql = 'SELECT id, email FROM users WHERE email = :email';
$statement = $pdo->prepare($sql);
$email = filter_input(INPUT_GET, 'email');
$statement->bindValue(':email', $email, PDO::PARAM_INT);
$statement->execute();

// Iterate results
while (($result = $statement->fetchObject()) !== false) {
    echo $result->name;
}

Transactions

The PDO extension also supports transactions. A transaction is a set of database statements that execute atomically. In other words, a transaction is a collection of SQL queries that are either all executed successfully or not executed at all. Transaction atomicity encourages data consistency, safety, and durability. A nice side effect of transactions is improved performance, because you are effectively queuing multiple queries to be executed together at one time.

Transactions are simple to use with the PDO extension. You build and execute SQL statements exactly as demonstrated in Example 5-25. There is only one difference. You surround SQL statement executions with the PDO instance’s beginTransaction() and commit() methods. The beginTransaction() method causes PDO to queue subsequent SQL query executions rather than execute them immediately. The commit() method executes queued queries in an atomic transaction. If a single query in the transaction fails, none of the transaction queries is applied. Remember, a transaction is all or nothing.

Atomicity is important when data integrity is paramount. Let’s explore example code that handles bank account transactions. Our code can deposit funds into an account. It can also withdraw funds from an account assuming there are sufficient funds. The code in Example 5-26 transfers $50 from one account to another account. It does not use a database transaction.

<?php
require 'settings.php';

// PDO connection
try {
    $pdo = new PDO(
        sprintf(
            'mysql:host=%s;dbname=%s;port=%s;charset=%s',
            $settings['host'],
            $settings['name'],
            $settings['port'],
            $settings['charset']
        ),
        $settings['username'],
        $settings['password']
    );
} catch (PDOException $e) {
    // Database connection failed
    echo "Database connection failed";
    exit;
}

// Statements
$stmtSubtract = $pdo->prepare('
    UPDATE accounts
    SET amount = amount - :amount
    WHERE name = :name
');
$stmtAdd = $pdo->prepare('
    UPDATE accounts
    SET amount = amount + :amount
    WHERE name = :name
');

// Withdraw funds from account 1
$fromAccount = 'Checking';
$withdrawal = 50;
$stmtSubtract->bindParam(':name', $fromAccount);
$stmtSubtract->bindParam(':amount', $withDrawal, PDO::PARAM_INT);
$stmtSubtract->execute();

// Deposit funds into account 2
$toAccount = 'Savings';
$deposit = 50;
$stmtAdd->bindParam(':name', $toAccount);
$stmtAdd->bindParam(':amount', $deposit, PDO::PARAM_INT);
$stmtAdd->execute();

This seems fine, right? It’s not. What happens if our server suddenly shuts down after we withdraw $50 from account 1 and before we deposit $50 into account 2? Perhaps our hosting company had a power outage or a fire or a flood or was afflicted by some other calamity. What happens to the $50 withdrawn from account 1? The funds are not deposited into account 2. The funds disappear. We can protect data integrity with a database transaction (Example 5-27).

<?php
require 'settings.php';

// PDO connection
try {
    $pdo = new PDO(
        sprintf(
            'mysql:host=%s;dbname=%s;port=%s;charset=%s',
            $settings['host'],
            $settings['name'],
            $settings['port'],
            $settings['charset']
        ),
        $settings['username'],
        $settings['password']
    );
} catch (PDOException $e) {
    // Database connection failed
    echo "Database connection failed";
    exit;
}

// Statements
$stmtSubtract = $pdo->prepare('
    UPDATE accounts
    SET amount = amount - :amount
    WHERE name = :name
');
$stmtAdd = $pdo->prepare('
    UPDATE accounts
    SET amount = amount + :amount
    WHERE name = :name
');

// Start transaction
$pdo->beginTransaction();

// Withdraw funds from account 1
$fromAccount = 'Checking';
$withdrawal = 50;
$stmtSubtract->bindParam(':name', $fromAccount);
$stmtSubtract->bindParam(':amount', $withDrawal, PDO::PARAM_INT);
$stmtSubtract->execute();

// Deposit funds into account 2
$toAccount = 'Savings';
$deposit = 50;
$stmtAdd->bindParam(':name', $toAccount);
$stmtAdd->bindParam(':amount', $deposit, PDO::PARAM_INT);
$stmtAdd->execute();

// Commit transaction
$pdo->commit();

Example 5-27 wraps the withdrawal and deposit into a single database transaction. This ensures that both execute successfully or not at all. Our data remains consistent.

Character Encoding

Use UTF-8. If you leave this section with one piece of advice, this is it. All modern web browsers understand UTF-8 character encoding. A character encoding is a method of packaging Unicode data in a format that can be stored in memory or sent over the wire between a server and client. The UTF-8 character encoding is just one of many available character encodings. UTF-8, however, is the most popular character encoding and is supported by all modern web browsers.

Character encoding is complex and confuses a lot of developers. When you work with multibyte strings, keep this advice in mind:

1. Always know the character encoding of your data.

2. Store data with the UTF-8 character encoding.

3. Output data with the UTF-8 character encoding.

The mbstring extension doesn’t just manipulate Unicode strings. It also converts multibyte strings between various character encodings. This is useful when clients export Excel spreadsheet data with a Windows-specific character encoding when what I really want is UTF-8 encoded data. Use the mb_detect_encoding() and mb_convert_encoding() functions to convert Unicode strings from one character encoding to another.

Output UTF-8 Data

When you work with multibyte characters, it is important that you tell PHP you are working with the UTF-8 character encoding. It’s easiest to do this in your php.ini file like this:

default_charset = "UTF-8";

The default character set is used by many PHP functions, including htmlentities(), html_entity_decode(), htmlspecialchars(), and the mbstring functions. This value is also added to the default Content-Type header returned by PHP unless explicitly specified with the header() function like this:

<?php
header('Content-Type: application/json;charset=utf-8');

I also recommend you include this meta tag in your HTML document header:

<meta charset="UTF-8"/>

Stream Wrappers

There are different types of streamable data that require unique protocols for reading and writing data. We call these protocols stream wrappers. For example, we can read and write data to the filesystem. We can talk with remote web servers via HTTP, HTTPS, or SSH (secure shell). We can open, read, and write ZIP, RAR, or PHAR archives. All of these communication methods imply the same generic process:

1. Open communication.

2. Read data.

3. Write data.

4. Close communication.

Although the process is the same, reading and writing a filesystem file is different from sending or receiving HTTP messages. Stream wrappers, however, encapsulate these differences behind a common interface.

Every stream has a scheme and a target. We specify the scheme and target in the stream’s identifier using this familiar format:

<scheme>://<target>

The <scheme> identifies the stream’s wrapper. The <target> identifies the stream data source. Example 5-28 creates a PHP stream to/from the Flickr API. It uses the HTTP stream wrapper.

<?php
$json = file_get_contents(
    'http://api.flickr.com/services/feeds/photos_public.gne?format=json'
);

Don’t be fooled by what appears to be a traditional website URL. The file_get_contents() function’s string argument is actually a stream identifier. The http scheme prompts PHP to use the HTTP stream wrapper. The argument’s remainder is the stream target. The stream target looks like a traditional website URL only because that’s what the HTTP stream wrapper expects. This may not be true for other stream wrappers.

<?php
$handle = fopen('/etc/hosts', 'rb');
while (feof($handle) !== true) {
    echo fgets($handle);
}
fclose($handle);

<?php
$handle = fopen('file:///etc/hosts', 'rb');
while (feof($handle) !== true) {
    echo fgets($handle);
}
fclose($handle);

Stream Context

Some PHP streams accept an optional set of parameters, or a stream context, to customize the stream’s behavior. Different stream wrappers expect different context parameters. You create a stream context with the stream_context_create() function. The returned context object can be passed into and used by most PHP filesystem and stream functions.

For example, did you know that you can send an HTTP POST request with the file_get_contents() function? You can with a stream context object (Example 5-31).

<?php
$requestBody = '{"username":"josh"}';
$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json;charset=utf-8;\r\n" .
                    "Content-Length: " . mb_strlen($requestBody),
        'content' => $requestBody
    )
));
$response = file_get_contents('https://my-api.com/users', false, $context);

The stream context is an associative array whose topmost array key is the stream wrapper name. The stream context’s array values are specific to each stream wrapper. Consult the appropriate PHP stream wrapper’s documentation for a list of valid settings.

Stream Filters

So far we’ve talked about opening, reading from, and writing to PHP streams. However, the true power of PHP streams is filtering, transforming, adding, or removing stream data in transit. Imagine opening a stream to a Markdown file and converting it into HTML automatically as you read the file into memory.

You attach a filter to an existing stream with the stream_filter_append() function. Example 5-32 uses the string.toupper filter to read data from a text file on the local filesystem and convert its content to uppercase characters. I don’t encourage using this particular stream filter. I’m only demonstrating how to attach a filter to a stream.

<?php
$handle = fopen('data.txt', 'rb');
stream_filter_append($handle, 'string.toupper');
while(feof($handle) !== true) {
    echo fgets($handle); // <-- Outputs all uppercase characters
}
fclose($handle);

You can also attach a filter to a stream with the php://filter stream wrapper. This only works if you attach the filter when you first open the PHP stream. Example 5-33 accomplishes the same task as the previous example, except it attaches the filter with php://filter strategy.

<?php
$handle = fopen('php://filter/read=string.toupper/resource=data.txt', 'rb');
while(feof($handle) !== true) {
    echo fgets($handle); // <-- Outputs all uppercase characters
}
fclose($handle);

Pay close attention to the fopen() function’s first argument. The argument is a stream identifier that uses the php:// stream wrapper. This is the stream identifier target:

filter/read=<filter_name>/resource=<scheme>://<target>

This strategy may appear superfluous compared to the stream_filter_append() function. However, some PHP filesystem functions like file() or fpassthru() do not give you the opportunity to attach filters after the function is called. The php://filter stream wrapper is the only way to attach stream filters with these functions.

Let’s look at a more realistic stream filter example. At New Media Campaigns, our in-house content management system archives nginx access logs to rsync.net. We keep one log file per day, and each log file is compressed with bzip2. Log filenames use the format YYYY-MM-DD.log.bz2. I was asked to extract access data for a specific domain for the past 30 days. This seems like a lot of work, right? I need to calculate a date range, determine log filenames, FTP into rsync.net, download files, decompress files, iterate each file line-by-line, extract appropriate lines, and write access data to an output destination. Believe it or not, PHP streams let me do all of this in fewer than 20 lines of code (Example 5-34).

01 <?php
02 $dateStart = new \DateTime();
03 $dateInterval = \DateInterval::createFromDateString('-1 day');
04 $datePeriod = new \DatePeriod($dateStart, $dateInterval, 30);
05 foreach ($datePeriod as $date) {
06     $file = 'sftp://USER:PASS@rsync.net/' . $date->format('Y-m-d') . '.log.bz2';
07     if (file_exists($file)) {
08         $handle = fopen($file, 'rb');
09         stream_filter_append($handle, 'bzip2.decompress');
10         while (feof($handle) !== true) {
11             $line = fgets($handle);
12             if (strpos($line, 'www.example.com') !== false) {
13                 fwrite(STDOUT, $line);
14             }
15         }
16         fclose($handle);
17     }
18 }

In Example 5-34:

• Lines 2–4 create a DatePeriod instance that spans the past 30 days using an inverted, one-day interval.

• Line 6 creates a log filename using the DateTime instance returned by each DatePeriod iteration.

• Lines 8–9 open a stream resource to the log file on rsync.net with the SFTP stream wrapper. We decompress the bzip2 log file on the fly by appending the bzip2.decompress stream filter to the log file stream resource.

• Lines 10–15 iterate the decompressed log file contents using PHP’s standard filesystem functions.

• Lines 12–14 inspect each line for a given domain. If the domain is present, the line is written to standard output.

The bzip2.decompress stream filter lets us automatically decompress log files as we read them. The alternative solution is manually decompressing log files into a temporary directory with shell_exec() or bzdecompress(), iterating the decompressed files, and cleaning up the decompressed files when our PHP script completes. PHP streams are a simpler, more elegant solution.

Custom Stream Filters

It’s possible to write custom stream filters, too. In fact, custom stream filters are the primary reason you use stream filters. Custom stream filters are PHP classes that extend the php_user_filter built-in class. The custom stream class must implement the filter(), onCreate(), and onClose() methods. You must register custom stream filters with the stream_filter_register() function.

Let’s create a custom stream filter that censors dirty words from a stream as its data is read into memory (Example 5-35). First, we must create a PHP class that extends php_user_filter. This class must implement a filter() method that acts as a sieve through which stream buckets pass. It receives a bucket brigade from upstream, it manipulates each bucket object in the brigade, and it sends each bucket into the downstream bucket brigade toward the stream destination. This is our DirtyWordsFilter custom stream class.

class DirtyWordsFilter extends php_user_filter
{
    /**
     * @param resource $in       Incoming bucket brigade
     * @param resource $out      Outgoing bucket brigade
     * @param int      $consumed Number of bytes consumed
     * @param bool     $closing  Last bucket brigade in stream?
     */
    public function filter($in, $out, &$consumed, $closing)
    {
        $words = array('grime', 'dirt', 'grease');
        $wordData = array();
        foreach ($words as $word) {
            $replacement = array_fill(0, mb_strlen($word), '*');
            $wordData[$word] = implode('', $replacement);
        }
        $bad = array_keys($wordData);
        $good = array_values($wordData);

        // Iterate each bucket from incoming bucket brigade
        while ($bucket = stream_bucket_make_writeable($in)) {
            // Censor dirty words in bucket data
            $bucket->data = str_replace($bad, $good, $bucket->data);

            // Increment total data consumed
            $consumed += $bucket->datalen;

            // Send bucket to downstream brigade
            stream_bucket_append($out, $bucket);
        }

        return PSFS_PASS_ON;
    }
}

The filter() method receives, manipulates, and forwards buckets of stream data. Inside the filter() function, we iterate the buckets in the $in bucket brigade and replace dirty words with their censored values. This method returns the PSFS_PASS_ON constant to indicate successful operation. This method accepts four arguments:

$in

A brigade of one or more upstream buckets that contains stream data from the stream origin

$out

A brigade of one or more buckets that continue downstream toward the stream destination

&$consumed

The total number of stream bytes consumed by our custom filter

$closing

Is the filter() method receiving the last available bucket brigade?

We must register the DirtWordsFilter custom stream filter with the stream_filter_register() function (Example 5-36).

<?php
stream_filter_register('dirty_words_filter', 'DirtyWordsFilter');

The first argument is the filter name that identifies our custom filter. The second argument is our custom filter’s class name. We can now use our custom stream filter (Example 5-37).

<?php
$handle = fopen('data.txt', 'rb');
stream_filter_append($handle, 'dirty_words_filter');
while (feof($handle) !== true) {
    echo fgets($handle); // <-- Outputs censored text
}
fclose($handle);

Exceptions

An exception is an object of class Exception that is thrown when you encounter an irreparable situation from which you cannot recover (e.g., a remote API is unresponsive, a database query fails, or a precondition is not satisfied). I call these exceptional situations. Exceptions are used offensively to delegate responsibility when a problem occurs, and they are used defensively to anticipate and mitigate potential problems.

You instantiate an Exception object with the new keyword just like any other PHP object. An Exception object has two primary properties: a message and a numeric code. The message describes what went wrong. The numeric code is optional and can be used to provide context for a given exception. You provide the message and optional numeric code when you instantiate an Exception object like this:

<?php
$exception = new Exception('Danger, Will Robinson!', 100);

You can inspect an Exception object with its getCode() and getMessage() public instance methods like this:

<?php
$code = $exception->getCode(); // 100
$message = $exception->getMessage(); // 'Danger...'

<?php
throw new Exception('Something went wrong. Time for lunch!');

<?php
try {
    $pdo = new PDO('mysql://host=wrong_host;dbname=wrong_name');
} catch (PDOException $e) {
    // Inspect the exception for logging
    $code = $e->getCode();
    $message = $e->getMessage();

    // Display a nice message to the user
    echo 'Something went wrong. Check back soon, please.';
    exit;
}

<?php
try {
    throw new Exception('Not a PDO exception');
    $pdo = new PDO('mysql://host=wrong_host;dbname=wrong_name');
} catch (PDOException $e) {
    // Handle PDO exception
    echo "Caught PDO exception";
} catch (Exception $e) {
    // Handle all other exceptions
    echo "Caught generic exception";
} finally {
    // Always do this
    echo "Always do this";
}

Exception Handlers

You may be thinking how am I supposed to catch every possible exception? And that’s a good question. PHP lets you register a global exception handler to catch otherwise uncaught exceptions. You should always set a global exception handler. An exception handler is a final safety net that lets you show an appropriate error message to your PHP application’s users if you otherwise fail to catch and handle an exception. For my own PHP applications, I use exception handlers to show debugging information during development and a user-friendly message during production.

An exception handler is anything that is callable. I prefer to use an anonymous function, but you can also use a class method. Whatever you choose, it must accept one argument of class Exception. You register your exception handler with the set_exception_handler() function like this:

<?php
set_exception_handler(function (Exception $e) {
    // Handle and log exception
});

In some situations, you may need to replace an existing exception handler with your own exception handler. PHP etiquette suggests you restore the existing exception handler when your code is finished. You can restore a previous exception handler with the restore_exception_handler() function (Example 5-40).

<?php
// Register your exception handler
set_exception_handler(function (Exception $e) {
    // Handle and log exception
});

// Your code goes here...

// Restore previous exception handler
restore_exception_handler();

Errors

PHP provides error-reporting functions in addition to exceptions. This confuses many PHP developers. PHP can trigger different types of errors, including fatal errors, runtime errors, compile-time errors, startup errors, and (more rarely) user-triggered errors. You’ll most often encounter PHP errors caused by syntax mistakes or uncaught exceptions.

The difference between errors and exceptions is subtle. Errors are often triggered when a PHP script cannot fundamentally run as expected for whatever reason (e.g., there is a syntax mistake). It is also possible to trigger your own errors with the trigger_error() function and handle them with a custom error handler, but it is better to use exceptions when writing userland code. Unlike errors, PHP exceptions can be thrown and caught at any level of your PHP application. Exceptions provide more contextual information than PHP errors. And you can extend the topmost Exception class with your own custom exception subclasses. Exceptions and a good logger like Monolog are a far more versatile solution than PHP errors. However, modern PHP developers must anticipate and handle both PHP errors and PHP exceptions.

You can instruct PHP which errors to report, and which to ignore, with the error_reporting() function or the error_reporting directive in your php.ini file. Both accept named E_* constants that determine which errors are reported and which are ignored.

PHP error reporting can be as sensitive or stoic as you tell it to be. In development, I prefer PHP to obnoxiously display and log all error messages. In production, I instruct PHP to log most error messages but not display them. Whatever you do, you should always follow these four rules:

• Always turn on error reporting.

• Display errors during development.

• Do not display errors during production.

• Log errors during development and production.