Class: PEAR_Delegator

Introduction
It is first necessary to discuss the role of delegates in PEAR. With the advent of PHP 5, a whole host of new programming techniques were introduced. Among them were class interfaces. These interfaces provide much of the benefits of multiple inheritance (with regard to methods) without adulterating the inheritance hierarchy. That is, an object can inherit from a parent class as usual, but still possess methods that qualify it as a member of another group of objects, related by certain behavior but still exclusively separate in the hierarchy. The interfaces, however, only define the protocol to which each adopting class must adhere, but they do not define the implementation. This is very useful in many instances, but for some purposes, the implementation remains viritually the same for all adopting parties. This is where delegation enters.

A delegate is a class that defines methods which are intended to be called by an adopting object as if they were members of that object. For instance,

 class Foo extends PEAR_Delegator

 {
     public function _construct()
     {
         parent::_construct();
     }
 
     public function _destruct()
     {
         parent::_destruct();
     }
 }
 
 $foo = new Foo();
 $foo->bar() //This results in a runtime error,
             //Foo has no such method.
 
 //Now define a delegate
 class Delegate
 {
     public function _construct()
     {
         parent::_construct();
     }
 
     public function _destruct()
     {
         parent::_destruct();
     }
 
     public function bar()
     {
         echo 'bar';
     }
 }
 
 foo->addDelegate(new Delegate);  //add the delegate.
 foo->bar();                      //This will be called as if it
                                  //were a member of Foo.

There are two types of delegates: true delegates and false delegates.

True Delegates
These delegates are designed to be used as delegates. As such, they follow an explicit delegate protocol. To simulate an actual method call, the forwarding mechanism transparently inserts a reference to the calling delgator as a the first argument. Consquently, such a delegate's method signatures must be of the form:

 accesslevel function functionName($owner, ...);

1. $owner can be any suitable variable name.
2. $owner is unncessary if the method takes no variables and does not access the delegator.
3. The user of the method need only consider those parameters that follow the $owner argument.

 $delegator->addDelegate($delegate1, $delegate2, ...);
 //or
 $delegator->addDelegate(true, $delegate1, $delegate2, ...);

False Delegates
These delegates are designed without any intention to be used as delegates. In essence, these are regular objects in themselves that would be useful as delegates. They have no knowledge of delegators and no reason to access a forwarding delegator. Consequently, such a delegate's method signatures are not guaranteed to be of the forme described above. Their signatures can be of any form, but they will not have access to the calling delegator.

Delegates of this kind must be explicitly denoted by passing a false as the preceding argument to a list of false delegates:

 $delegator->addDelegate(false, $delegate1, $delegate2, ...);

Indeed, a mixed list of delegates can be called:

 $delegator->addDelegate($delegate1, $delegate2, false, $delegate3, $delegate4, true $delegate1 ...);

Mixed Delegates
Since delegates can themselves can be delegators, the two kinds of delegates can be mixed. This is achieved by creating a true delegate that has added to it a false delegate. Then, any delegator can make calls to true delegate methods and false delegate methods through the same delegate.\

There are two further categorizations: class delegates and instance delegates.

Class Delegates
These delegates are classes whose methods are to be called statically.

Instance Delegates
These delegates are instances of classes.

Delegate Hierarchies
One of the benefits of this scheme is the ability to have delegate hierarchies. That is, a delegator could have a delegate that is a delegator, and the PEAR_Delegator class recognizes this by viewing such delegates as subdelegates, treating such subdelegates as subclasses would be treated. This allows for such capabilities as pseudo-overriding:

 //In our Foo class we could define a bar() method as follows:

 public function bar()
 {
    $args = func_get_args();
 
    //Note that it may be better to call $this->getDelegateForMethod()
    //instead of $this->hasDelegate(), since the latter may forward
    //the call to a delegate that does not respond.
    if ($this->hasDelegate())
      $this->forwardMethod('bar', $args);
 
    echo 'foobar';
 }

Traditional Delegation
In truth, this mode of delegation is unorthodox. The traditional model of delegation is that an object delegates selected methods, calling its own version unless one delegate is present. This feature is, in fact, a subset of the scheme presented here. In otherwords, you can achieve the same effect by pseudo-overriding as described above.

Implementation

1. Performance Impact In actuality, there should be little extra overhead after the first call to a delegated method. This is due to a caching scheme: When methods are called upon a delegator, the delegator checks an associated array that contains method names as keys and the proper delegates as values. If the key (method name) is cached in this manner, then the method is immediatly invoked on the proper delegate. If it does not exist, then each delegate is searched until one that can respond is found and this relationship is cached, otherwise, a fatal error is produced. Thus no matter how many delegates a class has, all calls after the first should only have a small latency. Note: Subdelegators cache their own delegates, so calls are passed down the hiearchy until the implementing delegate handles the call.
2. Flexibility of Errors. This is not a trouble at all. In fact, the error output of this class is more direct in many cases than PHP's own error output. It will give you the file and line of the error in user code and its messages are modeled after those of PHP.

1. owner : a delegator.
2. subdelegate : A delegator that is a delegate.
3. native delegate : A delegate that is an immediate delegate, not a delegate of a delegate.
4. class delegate : A delegate that is simply the class.
5. instance delegate : A delegate that is an instantiated class.

$_addExtensions =  false

[line 265]

$_delegates = array()

[line 246]

$_delegatesFalse = array()

[line 253]

$_method_map = array()

[line 260]

__construct (Constructor)   [line 270]

__destruct (Destructor)   [line 283]

addDelegate   [line 321]

addExtensions   [line 295]

cacheMethod   [line 849]

filterMethodMapWithDelegate   [line 655]

forwardMethod   [line 872]

getAllDelegates   [line 382]

getDelegate   [line 423]

getDelegateExact   [line 479]

getDelegateForMethod   [line 532]

hasDelegate   [line 592]

hasDelegateExact   [line 564]

is_a   [line 745]

is_aExact   [line 717]

method_exists   [line 797]

method_existsExact   [line 770]

removeAllDelegates   [line 634]

removeDelegate   [line 689]

respondsToMethod   [line 826]

setDelegate   [line 365]

__call   [line 895]