1: <?php
 2: 
 3: namespace Charcoal\Config;
 4: 
 5: /**
 6:  * Provides an object with the ability to perform lookups in other objects.
 7:  *
 8:  * A "delegate object" acts as a fallback when the current object does not have a requested value.
 9:  *
10:  * This is a full implementation of {@see DelegatesAwareInterface}.
11:  */
12: trait DelegatesAwareTrait
13: {
14:     /**
15:      * Holds a list of all delegate objects.
16:      *
17:      * @var EntityInterface[]
18:      */
19:     private $delegates = [];
20: 
21:     /**
22:      * Assigns a collection of delegare objects.
23:      *
24:      * @param  EntityInterface[] $delegates One or more delegate objects to register.
25:      * @return self
26:      */
27:     final public function setDelegates(array $delegates)
28:     {
29:         $this->delegates = [];
30:         foreach ($delegates as $delegate) {
31:             $this->addDelegate($delegate);
32:         }
33:         return $this;
34:     }
35: 
36:     /**
37:      * Appends a delegare object onto the delegate stack.
38:      *
39:      * @param  EntityInterface $delegate A delegate object to register.
40:      * @return self
41:      */
42:     final public function addDelegate(EntityInterface $delegate)
43:     {
44:         $this->delegates[] = $delegate;
45:         return $this;
46:     }
47: 
48:     /**
49:      * Prepends a delegare object onto the delegate stack.
50:      *
51:      * @param  EntityInterface $delegate A delegate object to register.
52:      * @return self
53:      */
54:     final public function prependDelegate(EntityInterface $delegate)
55:     {
56:         array_unshift($this->delegates, $delegate);
57:         return $this;
58:     }
59: 
60:     /**
61:      * Determines if a delegate object contains the specified key and if its value is not NULL.
62:      *
63:      * Iterates over each object in the delegate stack and stops on
64:      * the first match containing the specified key.
65:      *
66:      * @param  string $key The data key to check.
67:      * @return boolean TRUE if $key exists and has a value other than NULL, FALSE otherwise.
68:      */
69:     final protected function hasInDelegates($key)
70:     {
71:         foreach ($this->delegates as $delegate) {
72:             if (isset($delegate[$key])) {
73:                 return true;
74:             }
75:         }
76:         return false;
77:     }
78: 
79:     /**
80:      * Returns the value from the specified key found on the first delegate object.
81:      *
82:      * Iterates over each object in the delegate stack and stops on
83:      * the first match containing a value that is not NULL.
84:      *
85:      * @param  string $key The data key to retrieve.
86:      * @return mixed Value of the requested $key on success, NULL if the $key is not set.
87:      */
88:     final protected function getInDelegates($key)
89:     {
90:         foreach ($this->delegates as $delegate) {
91:             if (isset($delegate[$key])) {
92:                 return $delegate[$key];
93:             }
94:         }
95:         return null;
96:     }
97: }
98: