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.