DEPRECATION WARNING

This documentation is not using the current rendering mechanism and will be deleted by December 31st, 2020. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Parents service

This service will allow an object inside the full configuration object tree to fetch its parent object(s). For example, an object A has a property containing several instances of B, if the parent service is activated for the class B, then every instance of this class can access to its parents (in this example A).

A good usage instance with this service is managing very easily default configuration. Imagine an object which has an optional property: if this property is not filled in the configuration array, then a default one must be used. You can then fetch the default object instance by going back to the parent which contains it. See the function getFoo() in the example below.

Usage

You can activate this service for a given configuration object by attaching it to the ServiceFactory in the static function getConfigurationObjectServices(). Use the constant ServiceInterface::SERVICE_PARENTS as an identifier for this service (see example below).

You then have to import the trait ParentsTrait in every class which needs to have access to its parents. It gives you access to the following functions:

Name Description
hasParent($class) Will return true if the object does have a parent of the given class.
getFirstParent($class) Returns the first parent matching the given class name. Returns null if no parent with that class was found.
withFirstParent($class, $callback, $notFoundCallback) Allows executing a callback function with the first parent found which is of the wanted type. If not parent with this class is found, $notFoundCallback is called.

Example

 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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
use Romm\ConfigurationObject\Service\ServiceInterface;
use Romm\ConfigurationObject\Service\ServiceFactory;
use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;
use Romm\ConfigurationObject\Service\Items\Parents\ParentsTrait;

class MyObject implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;

    /**
     * @var SubObject[]
     */
    protected $subObjects;

    /**
     * @var SubObject
     */
    protected $defaultSubObject;

    /**
     * @return ServiceFactory
     */
    public static function getConfigurationObjectServices()
    {
        return ServiceFactory::getInstance()
            ->attach(ServiceInterface::SERVICE_PARENTS);
    }

    /**
     * @return SubObject
     */
    public function getDefaultSubObject()
    {
        return $this->defaultSubObject();
    }
}

class MySubObject
{
    const DEFAULT_FOO = 'foo';

    use ParentsTrait;

    /**
     * @var string
     */
    protected $foo;

    /**
     * @var string
     */
    protected $bar;

    /**
     * @return string
     */
    public function getFoo()
    {
        if (null === $this->foo) {
            $this->foo = $this->withFirstParent(
                MyObject::class,
                function(MyObject $myObject) {
                    return $myObject->getDefaultSubObject()->getFoo();
                },
                function() {
                    return (null === $this->foo)
                        ? MySubObject::DEFAULT_FOO
                        : $this->foo;
                }
            )
        }

        return $this->foo;
    }

    /**
     * @return string
     */
    public function getBar()
    {
        if ($this->hasParent(MyObject::class)
            && null === $this->bar
        ) {
            $this->bar = SomeRandomClass::runSomeExternalService();
        }

        return $this->bar;
    }
}