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.

Usage

Setting up a configuration object

Create your model classes

First of all, you have to create the skeleton of your configuration object. It means creating the several classes representing your configuration, add their properties, and indicate their types.

Please note that a configuration object root class (first level of the tree) needs to implement the interface ConfigurationObjectInterface. To implement directly the functions needed by the interface, you may use the trait DefaultConfigurationObjectTrait.

Example:

// my_extension/Classes/Configuration/Company.php

namespace MyVendor\MyExtension\Configuration;

use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;

class Company implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;

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

    /**
     * @var \MyVendor\MyExtension\Configuration\Employee[]
     */
    protected $employees;
}
// my_extension/Classes/Configuration/Employee.php

namespace MyVendor\MyExtension\Configuration;

class Employee
{
    /**
     * @var string
     */
    protected $name;

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

Tip

There are three ways to declare an array object property:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
/**
 * @var \MyVendor\MyExtension\Configuration\Employee[]
 *
 * OR
 *
 * @var \ArrayObject<\MyVendor\MyExtension\Configuration\Employee>
 *
 * OR
 *
 * @var array<\MyVendor\MyExtension\Configuration\Employee>
 */
protected $employees;

Get your configuration object

You should now be able to get your configuration object. The basic workflow of the configuration object usage is the following:

  1. First, the configuration plain array is fetched in whatever way. It can be an array created from scratch, but it can also be the conversion result of a serialized/JSON string, or come from the TypoScript tree.

  2. The plain array is sent to the extension API, like in the following code:

    $myConfigurationObject = \Romm\ConfigurationObject\ConfigurationObjectFactory::convert(
        MyVendor\MyExtension\Configuration\Company::class,
        $myConfigurationArray
    );
    
  3. The script above will return an instance of ConfigurationObjectInstance. It contains two important things: the actual converted object, and the possible errors which occurred during conversion.

    In most cases, you will want to know if there have been errors, before allowing your script to continue its execution. This way, you can inform whoever you want of the errors, and prevent your script from failing later on because the configuration was not right.

    You can find a basic usage below:

    $companyArray = [
        0 => [
            'name'      => 'My Company',
            'employees' => [
                [
                    'name'  => 'John Doe',
                    'email' => 'john.doe@my-company.com'
                ],
                [
                    'name'  => 'Jane Doe',
                    'email' => 'jane.doe@my-company.com'
                ]
            ]
        ]
    ];
    
    $companyObject = \Romm\ConfigurationObject\ConfigurationObjectFactory::convert(
        \MyVendor\MyExtension\Configuration\Company::class,
        $companyArray
    );
    
    $validationResult = $companyObject->getValidationResult();
    if ($validationResult->hasErrors()) {
        $errors = $validationResult->getFlattenedErrors();
    
        /*
         * Here you can do whatever you want, like sending a mail to someone,
         * or listing the errors in your template.
         */
    } else {
        // Getting the true instance of your converted object.
        $companyObject = $companyObject->getObject();
    
        // Keep up your script here...
    }
    

Properties and validation

To make sure that the data array used to build the configuration object is correct, you can attach validation rules on properties. For instance, you may want the name of an employee not to be empty, and its email to be a valid email address.

You can learn how to use the validation API in the chapter “Validators”.

Example for the field email of the class Employee:

/**
 * @var string
 * @validate NotEmpty
 * @validate EmailAddress
 */
protected $email;

Attaching services to a configuration object

In order to use advanced functionality and/or change a configuration object rendering behaviours, you can activate services. Several services are provided by the extension, with different goals.

You can learn how to use validators, and the list of already available ones in the chapter “Services”.

Example of a service declaration:

class Company implements ConfigurationObjectInterface
{

    const CACHE_NAME = 'company';

    /**
     * @return ServiceFactory
     */
    public static function getConfigurationObjectServices()
    {
        return ServiceFactory::getInstance()
            ->attach(ServiceInterface::SERVICE_CACHE)
            ->setOption(CacheService::OPTION_CACHE_NAME, self::CACHE_NAME);
    }
}