Table Of Content

Let's stay with the example of a Forum for a while. The classes of the forum don't implement security themselves, but somehow we have to make sure that whenever a method deletePost() is called, a security check takes place. The class containing the delete method is called the target class. We have a new aspect called "security" which we'd like to weave into that class. Whenever the method deletePost() is called, a method interceptor defined by an around advice will intercept the target method and only proceed if the operation is allowed in the current security context.

At the first (and the second, third, ...) glance, the terms used in the AOP context are not really intuitive. But, similar to most of the other AOP frameworks, we better stick to them, to keep a common language between developers. Here they are:

The following terms are related to advices:

Aspect-Oriented Programming was, of course, not invented by us^[2]. Since the initial release of the concept, dozens of implementations for various programming languages evolved. Although a few PHP-based AOP frameworks do exist, they followed concepts which did not match the goals of FLOW3 (to provide a powerful, yet developer-friendly solution) when the development of TYPO3 5.0 began. We therefore decided to create a sophisticated but pragmatic implementation which adopts the concepts of AOP but takes PHP's specialities and the requirements of typical FLOW3 applications into account. In a few cases this even lead to new features or simplifications because they were easier to implement in PHP compared to Java.

FLOW3 pragmatically implements a reduced subset of AOP, which satisfies most needs of web applications. The join point model allows for intercepting method executions but provides no special support for advising field access^[3]. For the sake of simplicity and performance, pointcuts don't allow criteria which have to be evaluated at runtime (such as matching argument values of a method) and pointcut expressions are based on well-known regular expressions instead of requiring the knowledge of a dedicated expression language. Pointcut filters and join point types are modularized and can be extended if more advanced requirements should arise in the future.

FLOW3's AOP framework does not require a pre-processor or an aspect-aware PHP interpreter to weave in advices. It is implemented and based on pure PHP and doesn't need any specific PHP extension. However, it does require the Component Manager to fulfill its task.

FLOW3 uses PHP's reflection capabilities to analyze declarations of aspects, pointcuts and advices and implements method interceptors as a dynamic proxy. In accordance to the GoF patterns^[4], the proxy classes act as a placeholders for the target object. They are true subclasses of the original and override adviced methods by implementing a interceptor method. The proxy classes are generated automatically by the AOP framework and cached in their own files. If a class has been adviced by some aspect, the Component Manager will only deliver instances of the proxy class instead of the original.

The approach of storing generated proxy classes in files provides the whole advantage of dynamic weaving with a minimum performance hit. Debugging of proxied classes is still easy as they truly exist in real files.

As already mentioned, the pointcut expression configures the filters which are used to match against join points. It is comparable to an if condition in PHP: Only if the whole condition evaluates to TRUE, the statement is executed - otherwise it will be just ignored. If a pointcut expression evaluates to TRUE, the pointcut matches and advices which refer to this poincut become active.

A pointcut expression always consists of two parts: The poincut designator and its parameter(s). The following designators are supported by FLOW3:

method(public|protected|private ClassName->methodName())

class(classname)

within(type)

classTaggedWith(tag)

All pointcut expressions mentioned in previous sections can be combined into a whole expression, just like you may combine parts to an overall condition in an if construct. The supported operators are “&&”, “||” and “!” and they have the same meaning as in PHP. Nesting expressions with parentheses is not supported but you may refer to other pointcuts by specifying their full name (ie. class- and method name). This final example shows how to combine and reuse pointcuts and ultimately build a hierarchy of pointcuts which can be used conveniently in advice declarations:

/**
 * Fixture class for testing poincut definitions
 * 
 * @package TestPackage
 * @aspect
 */
class F3_TestPackage_PointcutTestingAspect {

   /**
    * Pointcut which includes all method executions in pointcutTestingTargetClasses except those from Target Class number 3.
    *
    * @pointcut method(F3_TestPackage_PointcutTestingTargetClass.*->.*()) && !method(F3_TestPackage_PointcutTestingTargetClass3->.*())
    */
   public function pointcutTestingTargetClasses() {}
   
   /**
    * Pointcut which consists of only the F3_TestPackage_OtherPointcutTestingTargetClass.
    *
    * @pointcut method(F3_TestPackage_OtherPointcutTestingTargetClass->.*())
    */
   public function otherPointcutTestingTargetClass() {}
   
   /**
    * A combination of both above pointcuts
    * 
    * @pointcut F3_TestPackage_PointcutTestingAspect->pointcutTestingTargetClasses || F3_TestPackage_PointcutTestingAspect->otherPointcutTestingTargetClass
    * @author Robert Lemke <robert@typo3.org>
    */
   public function bothPointcuts() {}
   
   /**
    * A pointcut which matches all classes from the service layer
    *
    * @pointcut within(F3_FLOW3_ServiceLayerInterface)
    */
   public function serviceLayerClasses() {}
   
   /**
    * A pointcut which matches any method from the BasicClass and all classes from the service layer
    *
    * @pointcut method(F3_TestPackage_Basic.*->.*()) || within(F3_FLOW3_Service.*)
    */
   public function basicClassOrServiceLayerClasses() {}
}

A before advice allows for executing code before the target method is invoked. However, the advice cannot prevent the target method from being executed, nor can it take influence on other before advices at the same join point.

   /**
    * Before advice which is invoked before any method call within the News package
    *
    * @before class(F3_News_.*->.*())
    */
   public function myBeforeAdvice(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
   }

The after returning advice becomes active after the target method normally returns from execution (ie. it doesn't throw an exception). After returning advices may read the result of the target method, but can't modify it.

   /**
    * After returning advice
    *
    * @afterreturning method(public F3_News_FeedAgregator->[import|update].*()) || F3_MyPackage_MyAspect->someOtherPointcut
    */
   public function myAfterReturningAdvice(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
   }

Similar to the “after returning” advice, the after throwing advice is invoked after method execution, but only if an exception was thrown.

   /**
    * After throwing advice
    *
    * @afterthrowing within(F3_News_ImportantLayer)
    */
   public function myAfterThrowingAdvice(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
   }

The after advice is a combination of “after returning” and “after throwing”: These advices become active after method execution, no matter if an exception was thrown or not.

   /**
    * After advice
    *
    * @after F3_MyPackage_MyAspect->justAPointcut
    */
   public function myAfterAdvice(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
   }

Finally, the around advice takes total control over the target method and intercepts it completely. It may decide to call the original method or not and even modify the result of the target method or return a completely different one. Obviously the around advice is the most powerful and should only be used if the concern can't be implemented with the alternative advice types. You might already guess how an around advice is declared:

   /**
    * Around advice
    *
    * @around F3_MyPackage_MyAspect->justAPointcut
    */
   public function myAroundAdvice(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
   }

As you have seen in the previous section, advice methods always expect an argument of the type F3_FLOW3_AOPJoinPointInterface. This join point object contains all important information about the current join point. Methods like getClassName() or getMethodArguments() let the advice method classify the current context and enable you to implement advices in a way that they can be reused in different situations. For a full description of the join point object refer to the API documentation.

Around advices are a special advice type in that they have the power to completely intercept the target method. For any other advice type, the advice methods are called by the proxy class one after another. In case of the around advice, the methods form a chain where each link is responsible to pass over control to the next.

Figure 1.3. Control flow of an advice chain

Let's put our knowledge into practice and start with a simple example. First we would like to log each access to methods within certain package. The following code will just do that:

/**
 * A logging aspect
 *
 * @package MyPackage
 * @aspect
 */
class F3_MyPackage_LoggingAspect {

   /**
    * @var F3_Log_LoggerInterface A logger implementation
   protected $logger;

   /**
    * Constructor of this aspect. For logging we need a logger, which we will get
    * injected automatically by the Component Manager
    *
    * @param  F3_Log_LoggerInterface $logger: An instance of a logger
    * @return void
    */
   public function __construct(F3_Log_LoggerInterface $logger) {
      $this->logger = $logger;
   }

   /**
    * Before advice, logs all access to methods of our package
    *
    * @param  F3_FLOW3_AOPJoinPointInterface $joinPoint: The current join point
    * @return void
    * @before method(F3_MyPackage_.*->.*())
    */
   public function logMethodExecution(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
      $logMessage = 'The method ' . $joinPoint->getMethodName() . ' in class ' . $joinPoint->getClassName() . ' has been called.';
      $this->logger->log($logMessage, 'F3_MyPackage_LoggingAspect');
   }

}

Note that we are using dependency injection for getting a logger instance to stay independent from any specific logging implementation. We don't have to care about the kind of logger (file based, syslog, ...) and where it comes from.

Finally an example for the implementation of an around advice: For a guestbook, we want to reject the last name “Sarkosh” (because it should be “Skårhøj”), every time it is submitted. Admittedly you probably wouldn't implement this great feature as an aspect, but it's easy enough to demonstrate the idea. For illustration purposes, we don't define the pointcut expression in place but refer to a named pointcut.

/**
 * A lastname rejection aspect
 *
 * @package MyPackage
 * @aspect
 */
class F3_MyPackage_LastNameRejectionAspect {

   /**
    * A pointcut which matches all guestbook submission method invocations
    *
    * @pointcut method(F3_Guestbook_SubmissionHandlingThingy->submit())
    */
   public function guestbookSubmissionPointcut() {}

   /**
    * Around advice, rejects the lastname "Sarkosh"
    *
    * @param  F3_FLOW3_AOPJoinPointInterface $joinPoint: The current join point
    * @return mixed Result of the target method
    * @around F3_MyPackage_LastNameRejectionAspect->guestbookSubmissionPointcut
    */
   public function rejectLastName(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
      if ($joinPoint->getMethodArgument('lastName') == 'Sarkosh') {
         throw new Exception('Sarkosh is not a valid lastname - should be Skårhøj!');
      }
      $result = $joinPoint->getAdviceChain()->proceed($joinPoint);
      return $result;
   }
}

Please note that if the last name is correct, we proceed with the remaining links in the advice chain. This is very important to assure that the original (target-) method is finally called. And don't forget to return the result of the advice chain ...

Like advices, introductions are declared by annotations. But in contrast to advices, the anchor for an introduction declaration is a property of the aspect class. The annotation tag follows this syntax:

@introduce NewInterfaceName, PointcutExpression

Although the PoincutExpression is just a normal pointcut expression, which may also refer to named pointcuts, be aware that only expressions filtering for classes make sense. You cannot use the method() pointcut designator in this context and will typically take the class() designator instead.

The following example introduces a new interface NewInterface to the class OldClass and also provides an implementation of the method newMethod.

/**
 * An aspect for demonstrating introductions
 *
 * @package MyPackage
 * @aspect
 */
class F3_MyPackage_IntroductionAspect {

   /**
    * Introduces F3_MyPackage_NewInterface to the class F3_MyPackage_OldClass:
    *
    * @introduce F3_MyPackage_NewInterface, class(F3_MyPackage_OldClass)
    */
   public $newInterface;

   /**
    * Around advice, implements the new method "newMethod" of the "NewInterface" interface
    *
    * @param  F3_FLOW3_AOPJoinPointInterface $joinPoint: The current join point
    * @return void
    * @around method(F3_MyPackage_OldClass->newMethod())
    */
   public function newMethod(F3_FLOW3_AOPJoinPointInterface $joinPoint) {
         // We call the advice chain, in case any other advice is declared for this method,
         // but we don't care about the result. 
      $someResult = $joinPoint->getAdviceChain->proceed($joinPoint);

      $a = $joinPoint->getMethodArgument('a');
      $b = $joinPoint->getMethodArgument('b');
      return $a + $b;
   }
}

The following diagram illustrates the building process of a proxy class:

Figure 1.4. Proxy building process