DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Utilities

In addition to services, you can use other utilities provided by the API. They do not require a service to work, and can be used very easily in any class of a configuration (sub)object.

Array conversion

The trait ArrayConversionTrait provides the function toArray() which will recursively convert the object and its potential sub-objects into a plain array.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\ConfigurationObjectFactory;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;
use Romm\ConfigurationObject\Traits\ConfigurationObject\ArrayConversionTrait;

class MyObject implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;
    use ArrayConversionTrait;

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

$myConfigurationObject = ConfigurationObjectFactory::convert(
    MyObject::class,
    $someConfigurationArray
);
$myConfigurationArray = $myConfigurationObject->getObject()->toArray();

Store array index

In some cases, a sub-object of a configuration object can be stored in an array, at a given index. In this case, you may want to access to this index directly from within the sub-object. If you need to, just use the trait StoreArrayIndexTrait in the class which needs it. You then have access to the function getArrayIndex() which returns the index in which the object was stored.

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
use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\ConfigurationObjectFactory;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;
use Romm\ConfigurationObject\Traits\ConfigurationObject\StoreArrayIndexTrait;

class MyObject implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;

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

    /**
     * @return SubObject[]
     */
    public function getSubObjects()
    {
        return $this->subObjects;
    }
}

class MySubObject
{
    use StoreArrayIndexTrait;

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

$someConfigurationArray = [
    'someIndex'      => ['foo' => 'bar'],
    'someOtherIndex' => ['foo' => 'bar']
]

$myConfigurationObject = ConfigurationObjectFactory::convert(
    MyObject::class,
    $someConfigurationArray
);
$myObject = $myConfigurationObject->getObject();

foreach ($myObject->getSubObjects() as $subObject) {
    // Should display `someIndex`, then `someOtherIndex`.
    var_dump($subObject->getArrayIndex());
}

Magic setters/getters

Setting up getter/setter functions in an object is often the same boring basic logic, consisting in two one-line functions which do nothing more than just setting/returning a property of the object.

Because objects can have a lot of properties, you may want not to be forced to write down these functions for every property. You can then use the trait MagicMethodsTrait which will handle magic calls to the setters/getters of the object’s properties.

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
use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;
use Romm\ConfigurationObject\Traits\ConfigurationObject\MagicMethodsTrait;

class MyObject implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;
    use MagicMethodsTrait;

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

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

    // No setter/getter in here...
}

$myConfigurationObject = ConfigurationObjectFactory::convert(
    MyObject::class,
    $someConfigurationArray
);
$myObject = $myConfigurationObject->getObject();
$foo = $myObject->getFoo(); // Will work.
$bar = $myObject->getBar(); // Will work as well.
$bar = $myObject->setBar('bar'); // You got it? :)

Note

If for some reason you want to disable the magic methods for a given property, you need to tag it with @disableMagicMethods.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;
use Romm\ConfigurationObject\Traits\ConfigurationObject\MagicMethodsTrait;

class MyObject implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;
    use MagicMethodsTrait;

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

    /**
     * This property will not be accessible by magic setter/getter.
     *
     * @var string
     * @disableMagicMethods
     */
    protected $bar;
}

Hint

The usage of this trait will not provide auto-completion in IDEs like PhpStorm. But you can still use the class annotation @method (see phpDoc official documentation) to simulate it.

For instance, the example above would look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/**
 * @method setFoo(string $foo)
 * @method string getFoo()
 * @method setBar(string $bar)
 * @method string getBar()
 */
class MyObject implements ConfigurationObjectInterface
{
    // ...
}

Silent exceptions in getter methods

In some cases you may need to throw an exception in a generic getter method of an object property. For instance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class MyObject
{
    /**
     * @var SomeOtherObject
     */
    protected $foo;

    /**
     * @return SomeOtherObject
     * @throws SomeException
     */
    public function getFoo()
    {
        if (null === $this->foo) {
            throw MyException('foo has not been filled!');
        }

        return $this->foo;
    }
}

With this kind of implementation, you probably will be annoyed by the Configuration Object API which will throw the exception while trying to access the property at a very early stage in the object creation.

To avoid this, you need to make the exception implement the interface \Romm\ConfigurationObject\Exceptions\SilentExceptionInterface (see below). This will indicate to the API that the exceptions that implement this interface can be catch during early processes, meaning the return value of the getter method will be considered as null.

1
2
3
4
5
use \Romm\ConfigurationObject\Exceptions\SilentExceptionInterface;

class MyException extends \Exception implements SilentExceptionInterface
{
}

Check if the factory is processing

You can check at any moment if the configuration object factory is currently processing (an object is being created). This can be useful for instance if you want to allow magic methods for an object only when it is being converted.

if (\Romm\ConfigurationObject\ConfigurationObjectFactory::getInstance()->isRunning()) {
    // ...
}