Caching is probably the most known technique in computer science, it appears everywhere: CPU, disk cache buffers, opcode cache, memcache, SQL cache, etc. Since it is contained everywhere, we can’t extract it into a single place to keep it under our control. So cache invalidation is one of the hardest things. There is a good quote:

There are only two hard things in Computer Science: cache invalidation and naming things.

Let’s have a look at caching in the PHP.

Caching process

Ok, what is caching or cache?

In computing, a cache is a component that transparently stores data so that future requests for that data can be served faster. The data that is stored within a cache might be values that have been computed earlier or duplicates of original values that are stored elsewhere. If requested data is contained in the cache (cache hit), this request can be served by simply reading the cache, which is comparatively faster. Otherwise (cache miss), the data has to be recomputed or fetched from its original storage location, which is comparatively slower. Hence, the greater the number of requests that can be served from the cache, the faster the overall system performance becomes.

So, caching is a technique to optimize the performance of a system by storing data in a fast storage. There is nothing difficult here: just take data from a slow data source and put it into a faster data source. The faster and bigger the cache is, the more performance gain we can receive. A question for self-test: how many types of cache do you know in PHP?

Caching. Elementary.

Imagine that you have a code in a service class that returns information about something:

1
2
3
4
5
6
7
8
9
10
11
12

class ImportantService
{
    /**
     * Returns information about object by its unique identifier
     *
     * @return object
     */
    public function getInformation($uniqueIdentifier)
    {
        return $this->dataSource->getOne($uniqueIdentifier);
    }
}

This service and method is pretty clear, but your boss has just discovered that it takes several seconds to query this information and asks you to fix this. What would you do in order to improve the performance of this method? Of course, the easiest way to do this is to write this data into cache and then just check if there is a record in our cache instead of making hard query to a busy data source server.

At elementary level we can do this easy with memcache extension:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class ImportantService
{
    private $cache = null;

    /**
     * Default constructor
     */
    public function __construct()
    {
        $this->cache = $memcache = new Memcache();
        $memcache->addServer('memcache.local');
    }


    /**
     * Returns information about object by its unique identifier
     *
     * @return object
     */
    public function getInformation($uniqueIdentifier)
    {
        $result = $this->cache->get($uniqueIdentifier);
        if ($result === false) {
            $result = $this->dataSource->getOne($uniqueIdentifier);
            $this->cache->set($uniqueIdentifier, $result);
        }

        return $result;
    }
}

Now we use cache and store results from original data source for future use. On a subsequent query with unique identifier we can take a result from cache and just return it instead of doing hard query. So this code will work faster and this should make your boss happier. However I should put here a warning for beginners not to write code like this. Be more experienced and write code better!

Caching. Pre-Intermediate.

What’s wrong with the previous example with caching? Ok, there are two issues in it. Firstly, we don’t use a Dependency Injection (DI) to inject instance of cache and we hard-coded cache initialization in constructor. Secondly, we put logic of caching into the original service. This implementation violates Single Responsibility Principle (SRP) and can cause a lot of problems with testing, as we won’t be able to query the information directly from a data source without caching. We may as well violate another principle - DRY. This may occur if there are several methods in the class that should be cached, and we write extra lines of code in each method:

1
2
3
4
5
6
7

$result = $this->cache->get($uniqueIdentifier);
if ($result === false) {
    $result = ...
    $this->cache->set($uniqueIdentifier, $result);
}

return $result;

You can notice that we put the same lines of code everywhere where we need to add caching. This is known as cross-cutting concern. Caching is a typical example of it, and traditional object-oriented paradigm offers only few ways to extract this logic into one place. One of them is proxy pattern: define a class with magic __call() method and wrap an object with caching proxy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

class CachingProxy
{
    private $cache = null;
    private $instance = null;

    public function __construct(Memcache $cache, $instance)
    {
        $this->cache    = $cache;
        $this->instance = $instance;
    }

    public function __call($method, $arguments)
    {
        if (substr($method, 0, 3) !== 'get') {
            $result = call_user_func_array($method, $arguments);
        } else {
            $uniqueId = $method . serialize($arguments);
            $result = $this->cache->get($uniqueId);
            if ($result === false) {
                $result = call_user_func_array($method, $arguments);
                $this->cache->set($uniqueId, $result);
            }
        }

        return $result;
    }
}

$service = new ImportantService();
$cachedService = new CachingProxy($memcacheInstance, $service);

$result = $cachedService->getInformation(123); // First call goes to a data source
$more   = $cachedService->getInformation(123); // From cache now

Much better now! We extracted the logic of caching into a separate class and can wrap any instance. Our original service still has transparent logic and doesn’t need any instance of cache to work. But this solution has another two issues. The first issue is that proxy slows down execution of each method due to magic __call() and slow call_user_func_array() function. The second issue is more serious. Proxy violates inheritance and Liskov Substitution Principle (LSP). This means that we can’t pass an instance of proxy everywhere where original class is expected:

1
2
3
4
5
6
7
8
9
10

function expectsImportantService(ImportantService $service)
{
    return $service->getInformation(123);
}

$service = new ImportantService();
expectsImportantService($service); // OK

$cachedService = new CachingProxy($memcacheInstance, $service);
expectsImportantService($cachedService); // Catchable Fatal Error, expecting instance of ImportantService

This example shows that caching proxy is not a perfect solution because it is violating typehints and decreasing performance of application. However, it can be used to extract logic of caching into a single class and to keep original classes clean.

Caching. Intermediate.

At this level developers understand that caching logic should be separated from original code and LSP should be used. This is possible with decorator pattern, when caching class extends an original service class and overwrites methods to introduce an additional logic. Usually, it is done automatically with reflection and code generation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

class CachedImportantService extends ImportantService
{
    private $cache = null;

    /**
     * Default constructor
     */
    public function __construct($cache)
    {
        $this->cache = $cache
        parent::__construct();
    }

    /**
     * Returns information about object by its unique identifier
     *
     * @return object
     */
    public function getInformation($uniqueIdentifier)
    {
        $result = $this->cache->get($uniqueIdentifier);
        if ($result === false) {
            $result = parent::getInformation($uniqueIdentifier); // call original parent method
            $this->cache->set($uniqueIdentifier, $result);
        }

        return $result;
    }
}

This solution requires a lot of code generation and it’s still duplicated, because we need to override each method that should be cached with our implementation. It also requires to rewrite the source code or adjust definition of service to use an extended CachedImportantService instead of the original one. But we can use a framework for this, for example, there is a nice one Ocramius/ProxyManager.

Nevertheless, decorators and proxies can’t be used for static methods. Imagine that we have ImportantService::staticGetInformation() method which is used somewhere in the source code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class ImportantService
{
    /**
     * Returns information about object by its unique identifier
     *
     * @return object
     */
    public static function getInformation($uniqueIdentifier)
    {
        return self::$dataSource->getOne($uniqueIdentifier);
    }
}

function testStaticMethod()
{
    return ImportantService::getInformation(123); // no way to cache it or to replace with decorator/proxy
}

So, even advanced proxies can’t help us extract caching logic for static methods into the proxy/decorator. They won’t work for final classes either, because a final class can’t be extended.

Caching. Advanced

In this article we compared all the possible ways to cache a result for method. Each of them has its own advantages and issues, because object-oriented paradigm doesn’t have any instruments for solving cross-cutting problems. Is there a way to get rid of them? We want to achieve the following things:

• extract logic of caching into a single class (like with Proxy pattern)
• use Liskov Substitution and Open-Closed Principles
• have an ability to cache static methods and methods in a final class.

Now you are ready for aspect-oriented paradigm. AOP was designed to solve such cross-cutting issues in an elegant way with advices, aspects and joinpoints. It performs weaving of custom logic into original methods without changing the source code. Caching logic that we extracted for proxy earlier in the article is a typical body of advice in AOP. Our manual check for methods starting with “get” is a definition of pointcut in AOP terms. With AOP we can implement caching as follows:

• intercepting execution of static and dynamic methods declared as “cacheable” in all classes,
• adding an extra check for presence of value in the cache before executing the original method,
• if there isn’t any value in the cache, we invoke an original method and store its result in the cache.

My preferred way to declare method as “cacheable” is to use an annotation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Annotation\Cacheable;

class ImportantService
{
    /**
     * Returns information about object by its unique identifier
     * @Cacheable
     *
     * @return object
     */
    public function getInformation($uniqueIdentifier)
    {
        return $this->dataSource->getOne($uniqueIdentifier);
    }
}

Then we just need to define an aspect for caching, that will intercept all methods with Cacheable annotation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\Around;

/**
 * Caching aspect
 */
class CachingAspect implements Aspect
{
    private $cache = null;

    public function __construct(Memcache $cache)
    {
        $this->cache = $cache;
    }

    /**
     * This advice intercepts the execution of cacheable methods
     *
     * The logic is pretty simple: we look for the value in the cache and if we have a cache miss
     * we then invoke original method and store its result in the cache.
     *
     * @param MethodInvocation $invocation Invocation
     *
     * @Around("@annotation(Annotation\Cacheable)")
     */
    public function aroundCacheable(MethodInvocation $invocation)
    {
        $obj   = $invocation->getThis();
        $class = is_object($obj) ? get_class($obj) : $obj;
        $key   = $class . ':' . $invocation->getMethod()->name;

        $result = $this->cache->get($key);
        if ($result === false) {
            $result = $invocation->proceed();
            $this->cache->set($key, $result);
        }

        return $result;
    }
}

This aspect then will be registered in the AOP kernel. AOP engine will analyze each loaded class during autoloading and if a method matches the @Around("@annotation(Annotation\Cacheable)") pointcut then AOP will change it on the fly to include a custom logic of invoking an advice. Class name will be preserved, so AOP can easily cache static methods and even methods in final classes.

AOP allows us to extract caching logic into a single method (called ‘advice’), it works like a decorator, so we don’t slow down methods that are not cached (compared with proxy pattern), moreover, it doesn’t repeat the code several times (DRY) and it’s an awesome result.

Many developers have doubts about AOP, annotations and pointcut matching ) It’s a typical question, so I want to make some clarifications. First of all, pointcut matching is performed only once, there won’t be any extra checks during a normal execution of an application. Modified classes are stored in the cache and are friendly for opcode cachers, this means that the performance will be good. Annotations are parsed only once during pointcut matching and are also cached (in case you want to read some values from an annotation inside an advice). Bootstrap time for framework is about 20ms, this should be fast enough for your typical applications.

Assuming that we use AOP for caching of methods which can take several hundreds ms or even up to several seconds to complete, AOP overhead is minimal (20ms bootstrap and several ms for calling an advice). This approach gives a new instrument for developers, it can solve annoying cross-cutting concerns, like caching with simple aspect. Use it! Enjoy It!

PS. There is a demo site on Heroku with caching example: http://demo.aopphp.com/?showcase=cacheable You can try it with enabled/disabled AOP (blue button at top).

PSS. If you’re looking for a way to use AOP caching with Laravel, visit an article (Spain): http://blog.carlosgoce.com/realizando-cache-con-aop-en-laravel-4/

Support for custom streams and read-only file systems

lisachenko/go-aop-php#118

This feature is one of the most interesting, because it allows to use framework with any stream filters and wrappers, for example with phar archives. It is possible to generate an AOP cache and put it into the phar archive as a standalone read-only application. Possible usages of aspects in the phar archives are logging, dry-run control and much more. Do you bored with implementation of dry-run option for each command? Just give a try for AOP and define an aspect for that!

Direct advisors

lisachenko/go-aop-php#142

I received a lot of complains about usage of annotations for defining advices instead of pure PHP code. So I decided to give an alternative way for defining advisors with closures:

1
2
3
4
5
6
7
8
9
10
11
12

protected function configureAop(AspectContainer $container)
{
    $container->registerAdvisor(
        new DefaultPointcutAdvisor(
            new TrueMethodPointcut(),
            new MethodBeforeInterceptor(function (MethodInvocation $invocation) {
                echo "Hello", $invocation->getMethod()->name;
            })
        ),
        'test'
    );
}

This patch also optimizes injection of advices (interceptors) into the concrete class, so no more slow serialize()/unserialize() functions, they were replaced by var_export() and direct injection. I’m also thinking about DSL builders for defining pointcuts in a more natural way:

1
2
3
4
5
6
7

protected function configureAop(AspectContainer $container)
{
    $builder = new PointcutBuilder($container);
    $builder->before('execution(public **->get(*)')->do(function (MethodInvocation $invocation) {
        echo "Hello", $invocation->getMethod()->name;
    });
}

But this is not included into the current version, please ping me on github if your want it for the next version.

Annotation class filter

lisachenko/go-aop-php#128

PhpDeal Desing by Contract frameworks requires matching of classes based on presence of annotation in the class docblock. This functionality was missed in the framework. Now it’s possible to use special @within(AnnotationClassName) syntax to match classes that have AnnotationClassName annotation.

Here is an example of pointcut that intercepts execution of all public methods in the class marked with Invariant annotation:

1
2
3
4
5
6
7
8
9
10

    /**
     * Verifies invariants for contract class
     *
     * @Around("@within(PhpDeal\Annotation\Invariant) && execution(public **->*(*))")
     * @param MethodInvocation $invocation
     *
     * @throws ContractViolation
     * @return mixed
     */
    public function invariantContract(MethodInvocation $invocation) {...}

Access to a doctrine annotations from the MethodInvocation class

lisachenko/go-aop-php#66

Some aspects can analyze annotation to perform additional steps. Consider the following class where we define a ttl in the annotation for a method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

use Demo\Annotation\Cacheable;

class General
{
    /**
     * Test cacheable by annotation
     *
     * @Cacheable(time=10)
     * @param float $timeToSleep Amount of time to sleep
     *
     * @return string
     */
    public function cacheMe($timeToSleep)
    {
        usleep($timeToSleep * 1e6);
        return 'Yeah';
    }
}

We can easily define a pointcut and advice that will intercept the execution of methods marked with Cacheable annotation and cache their results in the cache for a specified time. Should be cool, isn’t it? Let’s do this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

use Demo\Annotation\Cacheable;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\Around;

class CacheAspect implements Aspect
{
    /**
     * Cacheable methods
     *
     * @param MethodInvocation $invocation Invocation
     *
     * @Around("@annotation(Demo\Annotation\Cacheable)")
     */
    public function aroundCacheable(MethodInvocation $invocation)
    {
        /** @var Cacheable $cacheable */
        $cacheable = $invocation->getMethod()->getAnnotation(Cacheable::class);
        echo $cacheable->time; // TTL for the cache
        return $invocation->proceed();
    }
}

Simplified pointcut syntax for methods in the same class

lisachenko/go-aop-php#113

Instead of complex pointcut like this:

1
2
3
4

execution(public **\*Controller->create(*) )
|| execution(public **\*Controller->get(*) )
|| execution(public **\*Controller->update(*) )
|| execution(public **\*Controller->delete(*) )

it is possible to use or’ed constructions with | sign:

1

execution(public **\*Controller->create|get|update|delete(*))

Much cleaner and more readable!

Inheritance analysis during load-time

lisachenko/go-aop-php#131

It is not a secret, that framework performs load-time weaving of aspects during loading the source file into PHP. Before PHP will be able to parse it and load, Go! AOP scans tokens and builds reflection to analyze a pointcuts. At that moment of class loading there is no information about full inheritance of class (interfaces, abstract classes, traits). This was known limitation of framework that it wasn’t possible to match parent methods in the children class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class Greeting
{
    public hello($name)
    {
        echo "hello $name";
    }
}

class Example extends Greeting
{
}

// pointcut is @Before("execution(public Example->*(*))")

$e = new Example();
$e->hello("User"); // advice is not applied, because method is defined in the Greeting class

After some research I found a way to recursively load parent classes and scan tokens. This is the major change for a dessert, but it can have an impact on the current aspects that uses within or similar pointcuts.

Let’s start! First of all, we need an empty yii-aspect directory for our project:

1

mkdir yii-aspect && cd yii-aspect

Next step is to install dependencies: Yii and Go! AOP frameworks. Go! AOP is registered on packagist and can be easily installed with composer:

1

composer require lisachenko/go-aop-php:0.4.*

Latest version of Yii framework (1.1.14) is on packagist too! This means that we can install it without any hacks with local repositories:

1

composer require yiisoft/yii:1.1.*

This is a minimum list of dependencies for our first example. Following step is very easy, thanks to the yiic console command. By default, all binaries are installed into ./vendor/bin folder, so yiic console should be there too.

Let’s create a web application:

1

yiic webapp app

Yii will generate a directory app with default project structure and files. This project can be opened in the browser, but AOP isn’t enabled right now. To enable AOP we should prepare our application to have an ability to use it. To enable AOP we need to update the front controller of our application (./app/index.php) in the following way:

Add this lines to the top of file before original content:

1
2
3
4
5
6
7
8

<?php
use Go\Instrument\Transformer\FilterInjectorTransformer;

// Load the composer autoloader
include __DIR__ . '/../vendor/autoload.php';

// Load AOP kernel
include __DIR__ . '/aspect.php';

And replace initialization of Yii at the bottom of file from require_once($yii) to require_once(FilterInjectorTransformer::rewrite($yii)). This is needed to give a hook for the Go! AOP framework to weave aspects into classes. Aspects are defined as separated classes and included in the ./aspect.php file. Let’s move to it and to the aspect kernel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

include __DIR__ . '/protected/extensions/go-aop-php/ApplicationAspectKernel.php';

// Prevent an error about nesting level
ini_set('xdebug.max_nesting_level', 500);

// Initialize an application aspect container
$applicationAspectKernel = ApplicationAspectKernel::getInstance();
$applicationAspectKernel->init(array(
    'debug' => true,
    // Application root directory
    'appDir'   => __DIR__ . '/../',
    // Cache directory
    'cacheDir' => __DIR__ . './protected/aspect',
    'excludePaths' => array(
        __DIR__ . './protected/aspect'
    )
));

This is typical configuration of Go! AOP framework where we can adjust some directories and paths. I think that this config is pretty clear to understand. Only debug parameter is really important. For production mode it should be false, but for development mode it should be enabled to enable better debugging and cache refreshing.

In this file we also include a strange file ApplicationAspectKernel.php. This file contains definition of aspect kernel for our application and it’s very simple:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Go\Core\AspectKernel;
use Go\Core\AspectContainer;

/**
 * Application Aspect Kernel
 */
class ApplicationAspectKernel extends AspectKernel
{

    /**
     * Configure an AspectContainer with advisors, aspects and pointcuts
     *
     * @param AspectContainer $container
     *
     * @return void
     */
    protected function configureAop(AspectContainer $container)
    {
        // todo: register aspects, advisors, pointcuts, etc
    }
}

There is only one method to define: configureAop that is used for AOP configuration. We can create an aspect now and register it in the kernel:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<?php
// app/protected/extensions/go-aop-php/TestMonitorAspect.php

namespace Aspect;

use Go\Aop\Aspect;
use Go\Aop\Intercept\FieldAccess;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\After;
use Go\Lang\Annotation\Before;
use Go\Lang\Annotation\Around;
use Go\Lang\Annotation\Pointcut;

/**
 * Monitor aspect
 */
class TestMonitorAspect implements Aspect
{

    /**
     * Method that will be called before real method
     *
     * @param MethodInvocation $invocation Invocation
     * @Before("within(**)")
     */
    public function beforeMethodExecution(MethodInvocation $invocation)
    {
        $obj = $invocation->getThis();
        echo 'Calling Before Interceptor for method: ',
        is_object($obj) ? get_class($obj) : $obj,
        $invocation->getMethod()->isStatic() ? '::' : '->',
        $invocation->getMethod()->getName(),
        '()',
        ' with arguments: ',
        json_encode($invocation->getArguments()),
        "<br>\n";
    }
}

… and registration in the kernel:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?php
// app/protected/extensions/go-aop-php/ApplicationAspectKernel.php

require_once 'TestMonitorAspect.php';

use Aspect\TestMonitorAspect;
use Go\Core\AspectKernel;
use Go\Core\AspectContainer;

/**
 * Application Aspect Kernel
 */
class ApplicationAspectKernel extends AspectKernel
{

    /**
     * Configure an AspectContainer with advisors, aspects and pointcuts
     *
     * @param AspectContainer $container
     *
     * @return void
     */
    protected function configureAop(AspectContainer $container)
    {
        $container->registerAspect(new TestMonitorAspect());
    }
}

That’s all )

Just have recreated https://t.co/FqlECETHO7 to use latest #yii 1.1.x and Go! AOP with #composer /cc @afdiaz @sam_dark

— Alexander Lisachenko (@lisachenko) September 26, 2013

Just refresh the page in the browser to see a result. All methods will be intercepted by our advice beforeMethodExecution:

PS. If you want to create an empty project with single line you can run:

1

composer create-project lisachenko/yii-aspect --prefer-source --stability=dev

Ok, let’s have some experiments with PHP. Suppose, that we have a nice code that uses the file_get_contents() function to load the content of a file and then prints it to the screen:

1
2
3
4
5
6
7
8
9

namespace Test;

class FilePrinter
{
    public function show($filename)
    {
        echo '<pre>', htmlspecialchars(file_get_contents($filename)), '</pre>';
    }
}

Is it possible to test this class and method? Of course, yes! We can create a unit test that will generate a temporary file and then just check that content is correct:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

namespace Test;

use PHPUnit_Framework_TestCase as TestCase;

class FilePrinterTest extends TestCase
{
    protected $printer;

    public function setUp()
    {
        $this->printer = new FilePrinter();
    }

    public function testShow()
    {
        $file = tempnam("/tmp", "PHP");
        file_put_contents($file, 'test');
        ob_start();
        $this->printer->show($file);
        $content = ob_end_clean();
        $this->assertEqual('test', $content);
        unlink($file);
    }
}

Not so cool to use a real filesystem. Real programmers should use virtual file system! But is it possible to intercept system functions like file_get_contents() in PHP?

I can suppose that most of programmers will argue that it’s impossible to intercept system function without extensions such as runkit. Yes, it’s absolutely true that we can not change the function that already loaded into the memory of PHP. However there is a small loophole in the PHP that can be exploited for free.

Namespace magic

All modern code is using namespaces to organize the better structure, to encapsulate a classes into a group and to avoid name collisions for functions, classes and constants. There are special namespace resolution rules that are used for resolving relative names to fully-qualified names. Let’s have a careful look to the rule number 5:

Inside namespace (say A\B), calls to unqualified functions are resolved at run-time. Here is how a call to function foo() is resolved:
1. It looks for a function from the current namespace: A\B\foo().
2. It tries to find and call the global function foo().

Wow! Inside namespace calls to unqualified functions are resolved at run-time! This means that we can create a function with the same name as system function in a namespace and it will be used instead of system one. Let’s check this fact:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

namespace Test;

use PHPUnit_Framework_TestCase as TestCase;

function file_get_contents($filename) {
    return 'Wow!';
}

class FilePrinterTest extends TestCase
{
    protected $printer;

    public function setUp()
    {
        $this->printer = new FilePrinter();
    }

    public function testShow()
    {
        $file = tempnam("/tmp", "PHP");
        file_put_contents($file, 'test');
        ob_start();
        $this->printer->show($file);
        $content = ob_end_clean();
        $this->assertEqual('test', $content);
        unlink($file);
    }
}

Pay an attention that we define the function file_get_contents() in the namespace Test. If we run our test we will see that it is broken, because we expecting ‘test’ but got ‘Wow!’. Very promising ) Small demo is also available at http://3v4l.org/K1b9k

Moreover, if we need to call an original function we can easily do this by using qualified name:

1
2
3
4
5
6

namespace Test;

function file_get_contents($filename) {
    echo 'Wow!';
    return \file_get_contents($filename);
}

Aspect-oriented programming with functions

Go! AOP framework has an experimental support for system function interception from the version 0.4.0. This means that there is an ability to create an advice for system functions!

Function interception can be very-very slow, so please do not try to intercept all system functions in all namespaces. However it’s so amazing. Let’s try:

• Enable function interception in the kernel by setting ‘interceptFunctions’ => true for the kernel.
• Create an advice within aspect to intercept functions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

use Go\Aop\Aspect;
use Go\Aop\Intercept\FunctionInvocation;
use Go\Lang\Annotation\Around;

/**
 * Function interceptor aspect
 */
class FunctionInterceptorAspect implements Aspect
{

    /**
     * @param FunctionInvocation $invocation
     *
     * @Around("execution(Test\*(*))")
     *
     * @return mixed
     */
    public function aroundFunction(FunctionInvocation $invocation)
    {
        echo 'Calling Around Interceptor for function: ',
            $invocation->getFunction()->getName(),
            '()',
            ' with arguments: ',
            json_encode($invocation->getArguments()),
            PHP_EOL;

        return $invocation->proceed();
    }
}

• Register this aspect in the kernel

Here we define an advice with an around pointcut execution(Test\*(*)). Pointcut can be translated as “around execution of any (*) system functions inside the Test namespace”. Body of this method is an advice that will be invoked around the original function. So we have a full control over the return value and original invocation by calling $invocation->proceed() at the end. Look at the screenshot from ZF2 framework:

If you want to try this by hand, feel free to install the Go! AOP framework with composer and open the demos/ folder in the browser:

1

composer require lisachenko/go-aop-php:0.4.0

Thank you for attention!

It’s not a secret that every business application requires logging of different actions in different places of the code. Why we need this logging? Is it possible not to use it? The answer is obvious. No, we can’t, we should write logs to be able to analyze them in case something goes wrong. Logs can give us the answers: what happened, when it happened and why it happened.

Let’s have a look at a typical class which is doing some important job for us:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class Account
{
    protected $amount = 0;

    public function depositMoney($amount)
    {
        $this->amount += $amount;
    }

    public function withdrawMoney($amount)
    {
        $this->amount -= $amount;
    }
}

Of course, it’s the simplest implementation and real class can contain much more lines of code. Suppose that we deployed this code to the production server and after a while our project manager says that sometimes deposit withdrawal is not working. Oops!

Best solution in that case is to add logging to all the important methods to be sure that everything is working as expected. To detect an error we should write log before and after method execution. Then we can look into log and just count pairs “before-after”. If there isn’t “after” log record then we have an error and corresponding “before” record will give us an idea why we have this error.

To write the logs we need a logger instance in our class and it’s another disadvantage of OOP version of logging. Injecting logger adds a dependency which is not really needed by our class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class Account
{
    /**
     * @var LoggerInterface
     */
    protected $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    // source code here
}

Cross-cutting concerns such as logging can not be easily extracting on OOP level into the single class and this means that we should add logging to each method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

class Account
{
    protected $amount = 0;

    /**
     * @var LoggerInterface
     */
    protected $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function depositMoney($amount)
    {
        $this->logger->info("Preparing to deposit money", array('amount' => $amount));
        try {
            $this->amount += $amount;
            $this->logger->info("Deposit money successful", array('amount' => $amount));
        } catch (Exception $e) {
            $this->logger->info("Deposit money error: " . $e, array('amount' => $amount));
            throw $e;
        }
    }

    public function withdrawMoney($amount)
    {
        $this->logger->info("Preparing to withdraw money", array('amount' => $amount));
        try {
            $this->amount -= $amount;
            $this->logger->info("Withdraw money successful", array('amount' => $amount));
        } catch (Exception $e) {
            $this->logger->info("Withdraw money error: " . $e, array('amount' => $amount));
            throw $e;
        }
    }
}

Wow! Logging is so annoying! Instead of single line of useful code we have 6! For each important method! In my previous article we refactored logging to the aspect class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\After;
use Go\Lang\Annotation\Before;
use Go\Lang\Annotation\Around;

class LoggingAspect implements Aspect
{
    /**
     * Instance of logger (injected in constructor or by setter)
     */
    protected $logger;

    /**
     * @Before("within(**)")
     */
    public function beforeMethodExecution(MethodInvocation $invocation)
    {
        $this->logger->info(
            "Executing " . $invocation->getMethod()->name,
            $invocation->getArguments()
        );
    }
}

This aspect is cool but it is too global due to the within(**) pointcut that matches all public and protected methods in every class. But what should we do if we want to log only specific methods in the application? We definitely need some markers for loggable methods. In the Java world we can use native annotations to mark the methods, but for PHP there isn’t native support for annotations. However, there is a cool Doctrine Annotations library that can be used in our own application to implement doc block annotations.

Let’s create an annotation class for @Loggable marker:

1
2
3
4
5
6
7
8
9
10
11
12
13

namespace Annotation;

use Doctrine\Common\Annotations\Annotation;

/**
 * Loggable marker
 *
 * @Annotation
 */
class Loggable extends Annotation
{

}

The next step is to register this annotation in the registry of Doctrine (this is only needed if you did not register an autoloader previously):

1
2
3

use Doctrine\Common\Annotations\AnnotationRegistry;

AnnotationRegistry::registerFile(__DIR__ . './Annotation/Loggable.php');

Now we can modify an aspect by writing a pointcut expression that will match only specific methods. A pointcut expression is an expression that specifies where in the code the advice will be applied. With Go! AOP, you can create a pointcut by specifying namespace, class and method attributes among other things. But the easiest way to specify a pointcut for the logging aspect is by matching methods that have a specific Annotation\Loggable annotation marker in the phpDoc-block

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\Around;
use Go\Lang\Annotation\Pointcut;

class LoggingAspect implements Aspect
{
    /**
     * Instance of logger (injected in constructor or by setter)
     */
    protected $logger;

    /**
     * @Pointcut("@annotation(Annotation\Loggable)")
     */
    protected function loggablePointcut() {}

    /**
     * @Around("$this->loggablePointcut")
     * @return mixed
     */
    public function aroundLoggable(MethodInvocation $invocation)
    {
        $method = $invocation->getMethod()->name;
        $this->logger->info("Entering " . $method, $invocation->getArguments());
        try {
            $result = $invocation->proceed();
            $this->logger->info("Success: " . $method);
        } catch (Exception $e) {
            $this->logger->error("Error: " . $method . ' details: ' . $e);
            throw $e;
        }
        return $result;
    }
}

Using the annotation means that developers never need to alter the pointcut expression to add or remove methods to the pointcut. A developer only has to add the annotation to a method to have the logging aspect applied. Let’s refactor our original class to use only annotation for loggable methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

use Annotation\Loggable;

class Account
{
    protected $amount = 0;

    /**
     * @var LoggerInterface
     */
    protected $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    /**
     * @Loggable
     */
    public function depositMoney($amount)
    {
        $this->amount += $amount;
    }

    /**
     * @Loggable
     */
    public function withdrawMoney($amount)
    {
        $this->amount -= $amount;
    }
}

We can also remove logger dependency, as there is no need in it any more:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

use Annotation\Loggable;

class Account
{
    protected $amount = 0;

    /**
     * @Loggable
     */
    public function depositMoney($amount)
    {
        $this->amount += $amount;
    }

    /**
     * @Loggable
     */
    public function withdrawMoney($amount)
    {
        $this->amount -= $amount;
    }
}

We just finished our refactoring to use transparent logging with Go! AOP and Doctrine annotations. By having @Loggable marker we still have a good understanding that this method should be logged and have a nice aspect that do logging in one place.

No. You can never be absolutely sure. That is why you need a log file to see if there where some errors. Well, if you are the kind of person that doesn’t care if some jerks who behaved wrong on you website get error messages, then you probably don’t need an error log file.

If you decide to to write the logs, then you definitely choose the best tool for this - Monolog. Monolog is used by such frameworks as Symfony2, Silex, Laravel4, PPI and can be easily integrated into custom application.

But even such a great tool like Monolog can not help us with encapsulating the logging into separate class, because logging is a cross-cutting concern. This means that logging do not fit cleanly into object-oriented programming. As a result, the code addressing the logging must be scattered, or duplicated, across the various related locations, resulting in a loss of modularity.

Aspect-oriented programming aims to encapsulate cross-cutting concerns into aspects to retain modularity. This allows for the clean isolation and reuse of code addressing the cross-cutting concern. By basing designs on cross-cutting concerns, software engineering benefits are effected, including modularity and simplified maintenance. This article will show you how to combine the power of AOP with the ease of use of Monolog to implement application-level logging just in few lines.

Installation

First of all, we need to install Monolog (if it isn’t available). Monolog is available on Packagist (monolog/monolog) and as such installable via Composer:

1

$ composer require monolog/monolog

If you do not use Composer, you can grab the code of Monolog from GitHub, and use any PSR-0 compatible autoloader (e.g. the Symfony2 ClassLoader component) to load Monolog classes.

Next tool that we need is Go! Aspect-Oriented Framework. You can find more information about installation and configuration in the documentation section.

If you use a Composer, then installation is quite easy:

1

$ composer require lisachenko/go-aop-php

Small configuration is required to prepare the AOP kernel for work. Detailed instructions are available here. After installation and configuration we are ready for the dark power of AOP

Implementing logging aspect

So, what is aspect?

In computer science, an aspect of a program is a feature linked to many other parts of the program, but which is not related to the program’s primary function.

Go! framework defines an aspect as a typical class with methods-advices. Each advice contains a specific logic that can be invoked before, after or around specific part of code in your application. Let’s try to describe an advice for logging.

Suppose, that we want to log an execution of methods. We want to write a method name and an arguments before execution of a method. Typically this is looking like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
class Example
{
    /**
     * Instance of logger (injected in constructor or by setter)
     */
    protected $logger;

    public function test($arg1, $arg2)
    {
        $this->logger->info("Executing " . __METHOD__, func_get_args());
        // ... logic of method here
    }

    public function anotherTest($arg1)
    {
        $this->logger->info("Executing " . __METHOD__, func_get_args());
        // ... logic of method here
    }
}

We can notice that the code addressing the logging is scattered and duplicated. To solve this issue we can extract this code into the separate “before” advice:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php
use Go\Aop\Aspect;

class LoggingAspect implements Aspect
{
    /**
     * Instance of logger (injected in constructor or by setter)
     */
    protected $logger;

    public function beforeMethodExecution()
    {
        $this->logger->info("Executing " . __METHOD__, func_get_args());
        // return the control to original code
    }
}

Ok, we have extracted the advice itself, but how we get a method name and arguments? Go! framework contains a specific class, that implements MethodInvocation interface. This interface gives an information about joinpoint by providing an access to the reflection object. Each advice is receiving an instance of this class as an argument:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;

class LoggingAspect implements Aspect
{
    /**
     * Instance of logger (injected in constructor or by setter)
     */
    protected $logger;

    public function beforeMethodExecution(MethodInvocation $invocation)
    {
        $this->logger->info("Executing " . $invocation->getMethod()->name, $invocation->getArguments());
    }
}

There is one more question to solve: “how to specify concrete methods?”. This is known as a pointcut - the term given to the point of execution in the application at which cross-cutting concern needs to be applied.

Go! framework uses annotations for defining pointcuts. Pointcut syntax is like an SQL for the source code. To intercept each public and protected method in the class we can use “within” pointcut:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?php
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\After;
use Go\Lang\Annotation\Before;
use Go\Lang\Annotation\Around;

class LoggingAspect implements Aspect
{
    /**
     * Instance of logger (injected in constructor or by setter)
     */
    protected $logger;

    /**
     * @Before("within(**)")
     */
    public function beforeMethodExecution(MethodInvocation $invocation)
    {
        $this->logger->info("Executing " . $invocation->getMethod()->name, $invocation->getArguments());
    }
}

Pointcut syntax allows many constructions, for example: “within(My\Super\Class)”, “execution(public ClassName->())”, “@annotation(Annotation\Class\Name)” and more. You can play with pointcuts to look at result )

To register the aspect just add an instance of it in the configureAop() method of the kernel:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
// app/ApplicationAspectKernel.php

use LoggingAspect;

//...

    protected function configureAop(AspectContainer $container)
    {
        $container->registerAspect(new LoggingAspect());
    }

//...

If you don’t know how to inject a logger, you can try to initialize it in the aspect constructor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<?php
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\After;
use Go\Lang\Annotation\Before;
use Go\Lang\Annotation\Around;

use Monolog;

/**
 * Logging aspect
 */
class LoggingAspect implements Aspect
{
    protected $logger;

    public function __construct()
    {
        $this->logger = new Monolog\Logger('test');
        $this->logger->pushHandler(new Monolog\Handler\StreamHandler('php://output'));
    }

    /**
     * @Before("within(**)")
     */
    public function beforeMethodExecution(MethodInvocation $invocation)
    {
        $obj   = $invocation->getThis();
        $class = $obj === (object)$obj ? get_class($obj) : $obj;
        $this->logger->info("Executing " . $class.'->'.$invocation->getMethod()->name, $invocation->getArguments());
    }
}

If you run an application you can get an output like this (example for a Go! demo):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Want to eat something, let's have a breakfast!<br>
[2013-06-02 11:50:14] test.INFO: Executing Example\Human->eat [] []
[2013-06-02 11:50:14] test.INFO: Executing Example\Human->washUp [] []
Washing up...<br>
Eating...<br>
[2013-06-02 11:50:14] test.INFO: Executing Example\Human->cleanTeeth [] []
Cleaning teeth...<br>
I should work to earn some money<br>
[2013-06-02 11:50:14] test.INFO: Executing Example\Human->work [] []
Working...<br>
It was a nice day, go to bed<br>
[2013-06-02 11:50:14] test.INFO: Executing Example\Human->cleanTeeth [] []
Cleaning teeth...<br>
[2013-06-02 11:50:14] test.INFO: Executing Example\Human->sleep [] []
Go to sleep...<br>
[2013-06-02 11:50:14] test.INFO: Executing Example\User->setName ["test"] []
[2013-06-02 11:50:14] test.INFO: Executing Example\User->setSurname ["a"] []
[2013-06-02 11:50:14] test.INFO: Executing Example\User->setPassword ["root"] []

So, we have implemented logging without changes in the original source code! Have a nice experiments!

Evolution. From simple to complex.

Every programmer starts with the language by writing a trivial “Hello, world!”. After that, it takes several years to learn the language and to make clumsy attempts to write his own ORM / CMS / Framework (underline one or several). I think that everyone has the code which is better to hide. But without understanding of simple things you will not be able to understand the complex ones, so let’s start with a simple example and get to the implementation of the “fluent” interface as a separate class using AOP. Those who know this pattern can safely move on to the last part of the article, where you can get excellent food for thoughts.

Let’s start!

Let’s take a simple user entity, which has the following properties: name, last name and the password:

1
2
3
4
5
6
7

<?php
class User
{
    public $name;
    public $surname;
    public $password;
}

An excellent class that is easy to use:

1
2
3
4
5
6

<?php
$user = new User;

$user->name = 'John';
$user->surname = 'Doe';
$user->password = 'root';

It is easy to notice that we have no validation and somebody can set a blank password, which is not very good. In addition, it would be nice to know that the field values are immutable. These several considerations lead us to the idea that properties should be protected or private and access to them should be carried out with a pair of getter / setter.

Suit the action to the word:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<?php
class User
{
    protected $name;
    protected $surname;
    protected $password;

    public function setName($name)
    {
        $this->name = $name;
    }

    public function setSurname($surname)
    {
        $this->surname = $surname;
    }

    public function setPassword($password)
    {
        if (!$password) {
            throw new InvalidArgumentException("Password shouldn't be empty");
        }
        $this->password = $password;
    }
}

For the new class the configuration has changed a little and now we are using setters:

1
2
3
4
5
6

<?php
$user = new User;

$user->setName('John');
$user->setSurname('Doe');
$user->setPassword('root');

Not a big deal, right? But what if we need to set up 20 properties? 30 properties? This code will be flooded with setter calls and $user variable references. If the variable name will be $superImportantUser then readability of the source code deteriorates further. What can be done to get rid of the copy of the code?

Fluent interface to the rescue!

So, we came to the Fluent Interface pattern, which was coined by Eric Evans and Martin Fowler to increase readability of source code by simplifying multiple calls to the same object. It is implemented by a chain of methods, transmitting the calling context to the following method in the chain. The context is the return value of the method and this value can be any object, including the current one.

To implement a fluent interface, we need all the methods-setters to return the current object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<?php
class User
{
    protected $name;
    protected $surname;
    protected $password;

    public function setName($name)
    {
        $this->name = $name;
        return $this;
    }

    public function setSurname($surname)
    {
        $this->surname = $surname;
        return $this;
    }

    public function setPassword($password)
    {
        if (!$password) {
            throw new InvalidArgumentException("Password shouldn't be empty");
        }
        $this->password = $password;
        return $this;
    }
}

This approach will allow us to make the call chain:

1
2
3

<?php
$user = new User;
$user->setName('John')->setSurname('Doe')->setPassword('root');

As you can see, the configuration of the object now takes up less space and is much easier to read. We achieved our goal! At this point, many developers will ask: “So what?” Ok, then try to answer the question: “What’s wrong with fluent interface in this way?” before reading the next section.

So what’s bad in it?

Perhaps you’ve failed to find an answer and you’ve decided to read further? ) Well, I can reassure you that it’s all fine with fluent interface in OOP. However, if you think about it, you can find out that it can’t be implemented as a separate class, interface or trait. So it can’t be reused. This results in the fact that we have to put down “return $this” at the end of each method to implement fluent interface. If we have a couple dozen classes with a couple dozen methods that we want to do “fluent” then we have to manually deal with this unpleasant operation. This is the classic crosscutting.

Let’s make it in a separate class

Since we have a crosscutting, we must rise to the level above OOP to describe this pattern. Specification is pretty simple: when calling public methods in a class, original object should be returned as the result of the method invocation. Of course, we do not want unexpected effects, so let’s be clear: methods should be public setters starting with “set” and they should be inside classes that implement FluentInterface marker only . Let’s describe this with AOP and Go! AOP library.

First of all, our marker interface:

1
2
3
4
5
6
7
8

<?php
/**
 * Fluent interface marker
 */
interface FluentInterface
{

}

Fluent interface implementation in the form of advice within aspect:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<?php
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Annotation\Around;

class FluentInterfaceAspect implements Aspect
{
    /**
     * Fluent interface advice
     *
     * @Around("within(FluentInterface+) && execution(public **->set*(*))")
     *
     * @param MethodInvocation $invocation
     * @return mixed|null|object
     */
    protected function aroundMethodExecution(MethodInvocation $invocation)
    {
        $result = $invocation->proceed();
        return $result!==null ? $result : $invocation->getThis();
    }
}

Just a quick explanation - “Around” advice sets the hook “around” the original method and is fully responsible for whether the original method will be called or not, and is responsible for the result that will be returned. In the advice, we call original method (setter invocation) and if it doesn’t return anything we just return the original object $invocation->getThis(). That is all ) That is a useful pattern implementation just in a few lines of code. Using the fluent interface is now easy and sexy :)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<?php
class User implements FluentInterface
{
    protected $name;
    protected $surname;
    protected $password;

    public function setName($name)
    {
        $this->name = $name;
    }

    public function setSurname($surname)
    {
        $this->surname = $surname;
    }

    public function setPassword($password)
    {
        if (!$password) {
            throw new InvalidArgumentException("Password shouldn't be empty");
        }
        $this->password = $password;
    }
}

And usage:

1
2
3

<?php
$user = new User;
$user->setName('John')->setSurname('Doe')->setPassword('root');

No more copying “return $this” for hundreds of methods, only pure source code, intuitive FluentInterface and implementation of FluentInterface in the form of a simple aspect.

Go! doesn’t require any PECL-extentions, it neither uses any dark magic of Runkit nor evals, the library doesn’t use DI-containers. The code with weaved aspects is fully readable and native, it can be easily debugged with XDebug. You can debug either classes or aspects. The main advantage of Go! is that potentially it can be installed in every PHP-application, because you don’t have to change the application source code at all. As an example, with the help of 10-20 lines of code we can intercept all the public, protected and static methods in all the classes of application and display the name and the arguments of each method during its execution.

What is AOP?

AOP (Aspect-Oriented Programming) is an approach to cross-cutting concerns, where the concerns are designed and implemented in a “modular” way (that is, with appropriate encapsulation, lack of duplication, etc.), then integrated into all the relevant execution points in a succinct and robust way, e.g. through declarative or programmatic means.

In AOP terms, the execution points are called join points, a particular set of them is called a pointcut and the new behavior that is executed before, after, or “around” a join point is called advice. You can read more about AOP in Introduction section.

PHP traits can be used to implement some aspect-like functionality.