Валідація значень конфігурації

Після завантаження значень конфігурації з усіх типів джерел, значення та їх структура можуть бути валідовані з використанням частини "Визначення" компонента Конфігурація. Значення конфігурації зазвичай мають відображати якусь ієрархію. Також, значення мають бути печного типу, бути обмежені у кіькості або бути одним з заданих наборів значень. Наприклад, наступна конфігурація (на YAML) відображає чітку ієрархію та деякі правила валідації, які мають бути застосовані до неї (на кшталт: "значення для auto_connect повинно бути булевим"):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

auto_connect: true
default_connection: mysql
connections:
    mysql:
        host:     localhost
        driver:   mysql
        username: user
        password: pass
    sqlite:
        host:     localhost
        driver:   sqlite
        memory:   true
        username: user
        password: pass

При завантаженні декількох файлів конфігурації, повинна бути можилвість обʼєденувати та перезаписувати деякі значення. Інші значення не повинні бути обʼєднані і залишаються в тому виді, в якому вони були при першому виявленні. Також деякі ключі доступні лише тоді, коли інший ключ має певне значення (у прикладі конфігурації вище: ключ memory має сенс лише тоді, коли driver - sqlite).

Визначення ієрархії значень конфігурації з використанням TreeBuilder

Всі правила, що стосуються значень конфігурації, можуть бути визначені, використовуючи TreeBuilder.

Екземпляр TreeBuilder має бути повернено з користувацького класу Configuration, що реалізує ConfigurationInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

namespace Acme\DatabaseConfiguration;

use Symfony\Component\Config\Definition\ConfigurationInterface;
use Symfony\Component\Config\Definition\Builder\TreeBuilder;

class DatabaseConfiguration implements ConfigurationInterface
{
    public function getConfigTreeBuilder()
    {
        $treeBuilder = new TreeBuilder();
        $rootNode = $treeBuilder->root('database');

        // ... додвйте визначення вузлів у корінь дерева
        
        return $treeBuilder;
    }
}

Додавання визначення вузлів у дерево

1
2
3
4
5
6
7
8
9
10

$rootNode
    ->children()
        ->booleanNode('auto_connect')
            ->defaultTrue()
        ->end()
        ->scalarNode('default_connection')
            ->defaultValue('default')
        ->end()
    ->end()
;

1
2
3
4
5
6
7
8
9
10
11
12
13

$rootNode
    ->children()
        ->integerNode('positive_value')
            ->min(0)
        ->end()
        ->floatNode('big_value')
            ->max(5E45)
        ->end()
        ->integerNode('value_inside_a_range')
            ->min(-50)->max(50)
        ->end()
    ->end()
;

1
2
3
4
5
6
7

$rootNode
    ->children()
        ->enumNode('delivery')
            ->values(array('standard', 'expedited', 'priority'))
        ->end()
    ->end()
;

1
2
3
4
5
6
7
8
9
10
11
12

$rootNode
    ->children()
        ->arrayNode('connection')
            ->children()
                ->scalarNode('driver')->end()
                ->scalarNode('host')->end()
                ->scalarNode('username')->end()
                ->scalarNode('password')->end()
            ->end()
        ->end()
    ->end()
;

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$rootNode
    ->children()
        ->arrayNode('connections')
            ->arrayPrototype()
                ->children()
                    ->scalarNode('driver')->end()
                    ->scalarNode('host')->end()
                    ->scalarNode('username')->end()
                    ->scalarNode('password')->end()
                ->end()
            ->end()
        ->end()
    ->end()
;

1
2
3
4

->arrayNode('hosts')
    ->beforeNormalization()->castToArray()->end()
    // ...
->end()

1
2
3
4
5
6
7
8

$node
    ->fixXmlConfig('driver')
    ->children()
        ->arrayNode('drivers')
            ->scalarPrototype()->end()
        ->end()
    ->end()
;

1

drivers: ['mysql', 'sqlite']

1
2

<driver>mysql</driver>
<driver>sqlite</driver>

1
2
3
4

Array(
    [0] => 'mysql'
    [1] => 'sqlite'
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$node
    ->fixXmlConfig('connection')
    ->children()
        ->arrayNode('connections')
            ->arrayPrototype()
                ->children()
                    ->scalarNode('table')->end()
                    ->scalarNode('user')->end()
                    ->scalarNode('password')->end()
                ->end()
            ->end()
        ->end()
    ->end()
;

1
2
3

connections:
    - { table: symfony, user: root, password: ~ }
    - { table: foo, user: root, password: pa$$ }

1
2

<connection table="symfony" user="root" password="null" />
<connection table="foo" user="root" password="pa$$" />

1
2
3
4
5
6
7
8
9
10
11
12

Array(
    [0] => Array(
        [table] => 'symfony'
        [user] => 'root'
        [password] => null
    )
    [1] => Array(
        [table] => 'foo'
        [user] => 'root'
        [password] => 'pa$$'
    )
)

1
2
3
4
5
6
7
8
9

connections:
    sf_connection:
        table: symfony
        user: root
        password: ~
    default:
        table: foo
        user: root
        password: pa$$

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$node
    ->fixXmlConfig('connection')
    ->children()
        ->arrayNode('connections')
            ->useAttributeAsKey('name')
            ->arrayPrototype()
                ->children()
                    ->scalarNode('table')->end()
                    ->scalarNode('user')->end()
                    ->scalarNode('password')->end()
                ->end()
            ->end()
        ->end()
    ->end()
;

1
2
3
4

<connection name="sf_connection"
    table="symfony" user="root" password="null" />
<connection name="default"
    table="foo" user="root" password="pa$$" />

1
2
3
4
5
6
7
8
9
10
11
12

Array(
    [sf_connection] => Array(
        [table] => 'symfony'
        [user] => 'root'
        [password] => null
    )
    [default] => Array(
        [table] => 'foo'
        [user] => 'root'
        [password] => 'pa$$'
    )
)

Потрібні значення та значення за замовчуванням

Для всіх типів вузлів можливо визначити значення за замовчуванням та заміщувальні значення у випадку, якщо вузол має визначене значення:

defaultValue()

Встановити значення за замовчуванням

isRequired()

Має бути визначено (але може бути порожнім)

cannotBeEmpty()

Не може містити порожнє значення

default*()

(null, true, false), скорочення для defaultValue()

treat*Like()

(null, true, false), надати заміщувальне значення у випадку, якщо значення - *.

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

$rootNode
    ->children()
        ->arrayNode('connection')
            ->children()
                ->scalarNode('driver')
                    ->isRequired()
                    ->cannotBeEmpty()
                ->end()
                ->scalarNode('host')
                    ->defaultValue('localhost')
                ->end()
                ->scalarNode('username')->end()
                ->scalarNode('password')->end()
                ->booleanNode('memory')
                    ->defaultFalse()
                ->end()
            ->end()
        ->end()
        ->arrayNode('settings')
            ->addDefaultsIfNotSet()
            ->children()
                ->scalarNode('name')
                    ->isRequired()
                    ->cannotBeEmpty()
                    ->defaultValue('value')
                ->end()
            ->end()
        ->end()
    ->end()
;

Старіння опції

Ви можете зробити опцію застарілою, використовуючи метод setDeprecated():

1
2
3
4
5
6
7
8
9
10
11
12

$rootNode
    ->children()
        ->integerNode('old_option')
            // виводить наступне загальне повідомлення про старіння:
            // Дочірній вузол "old_option" за шляхом "..." застарів.
            ->setDeprecated()

            // ви також можете передати користувацьке повідомлення про старіння (доступні заповнювачі %node% та %path%):
            ->setDeprecated('Опция "%node%" устарела. Используйте "new_config_option" вместо неё.')
        ->end()
    ->end()
;

Якщо ви використовуєте Панель інструментів веб-налагодження, ці сповіщення про старіння відображаються при перебудові конфігурації.

Документування опції

Всі опції можна документувати за допомогою методу info():

1
2
3
4
5
6
7
8

$rootNode
    ->children()
        ->integerNode('entries_per_page')
            ->info('Это значение используетсятолько для для страницы результатов поиска.')
            ->defaultValue(25)
        ->end()
    ->end()
;

Інформація буде відображена у вигляді коментаря при скиданні дерева конфігурації за допомогою команди config:dump-reference.

В YAML у вас може бути:

1
2

# Це значення використовується лише для сторінки результатів пошуку.
entries_per_page:     25

А в XML:

1
2

<!-- entries-per-page: Це значення використовується лише для сторінки результатів пошуку. -->
<config entries-per-page="25" />

Опціональні розділи

Якщо у вас є цілі розділи, які є необовʼязковими, і можуть бути включені та виключені, ви можете скористатися перевагами методів скорочення canBeEnabled() і canBeDisabled():

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$arrayNode
    ->canBeEnabled()
;

// еквівалентно

$arrayNode
    ->treatFalseLike(array('enabled' => false))
    ->treatTrueLike(array('enabled' => true))
    ->treatNullLike(array('enabled' => true))
    ->children()
        ->booleanNode('enabled')
            ->defaultFalse()
;

Метод canBeDisabled() виглядає приблизно так само, крім того, що розділ буде включено за замовчуванням.

Обʼєднання опцій

Можуть бути надані додаткові опції, що стосуються обʼєднання. Для масивів:

performNoDeepMerging()

Коли значення також визначено у другому масиві конфігурації, не намагайтеся обʼєднувати масив, а повністю перепишіть його.

Для всіх вузлів:

cannotBeOverwritten()

Не дозволяйте іншим масивам конфігурації перезаписувати існуюче значення для цього вузла.

Додавання розділів

Якщо ви валідуєте складну конфігурацію, то дерево може сильно зрости, і ви можете захотіти поділити його на розділи. Ви можете зробити це, створивши окремий вузол для розділу, а потім додавши його в основне дерево за допомогою append():

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

public function getConfigTreeBuilder()
{
    $treeBuilder = new TreeBuilder();
    $rootNode = $treeBuilder->root('database');

    $rootNode
        ->children()
            ->arrayNode('connection')
                ->children()
                    ->scalarNode('driver')
                        ->isRequired()
                        ->cannotBeEmpty()
                    ->end()
                    ->scalarNode('host')
                        ->defaultValue('localhost')
                    ->end()
                    ->scalarNode('username')->end()
                    ->scalarNode('password')->end()
                    ->booleanNode('memory')
                        ->defaultFalse()
                    ->end()
                ->end()
                ->append($this->addParametersNode())
            ->end()
        ->end()
    ;

    return $treeBuilder;
}

public function addParametersNode()
{
    $treeBuilder = new TreeBuilder();
    $node = $treeBuilder->root('parameters');

    $node
        ->isRequired()
        ->requiresAtLeastOneElement()
        ->useAttributeAsKey('name')
        ->arrayPrototype()
            ->children()
                ->scalarNode('value')->isRequired()->end()
            ->end()
        ->end()
    ;

    return $node;
}

Це також корисно для того, щоб ви уникнули повторення самих себе, якщо у вас є розділи конфігурації, які повторюються у різних міцях.

Приклад призводить до наступного:

1
2
3
4
5
6
7
8
9
10
11
12

database:
    connection:
        driver:               ~ # Required
        host:                 localhost
        username:             ~
        password:             ~
        memory:               false
        parameters:           # Required

            # Prototype
            name:
                value:                ~ # Required

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<database>
    <!-- driver: Required -->
    <connection
        driver=""
        host="localhost"
        username=""
        password=""
        memory="false"
    >

        <!-- prototype -->
        <!-- value: Required -->
        <parameters
            name="parameters name"
            value=""
        />

    </connection>
</database>

Нормалізація

Коли обробляються файли конфігурації, вони спочатку нормалізуються, потім обʼєднуються і врешті-решт використовується дерево для валідації підсумкового масиву. Процес нормалізації використовується для видалення деяких розбіжностей, які виходять з різних форматів конфігурації, в основному, розбіжності між YAML та XML.

Розділювач, використовуваний у ключах, зазвичай _ в YAML, і - в XML. Наприклад, auto_connect в YAML і auto-connect в XML. Нормалізація перетворить обидва на auto_connect.

Ше однією відмінністю між YAML і XML є те, як можуть бути представлені значення масивів. В YAML у вас може бути:

1
2

twig:
    extensions: ['twig.extension.foo', 'twig.extension.bar']

А в XML:

1
2
3
4

<twig:config>
    <twig:extension>twig.extension.foo</twig:extension>
    <twig:extension>twig.extension.bar</twig:extension>
</twig:config>

Ця розбіжність може бути видалена у норамлізації, шляхом розмноження ключа, використовуваного в XML. Ви можете вказати, що ви хочете таким чином розмножити ключ, використовуючи fixXmlConfig():

1
2
3
4
5
6
7
8

$rootNode
    ->fixXmlConfig('extension')
    ->children()
        ->arrayNode('extensions')
            ->scalarPrototype()->end()
        ->end()
    ->end()
;

Якщо це нерегулярне розмноження, то ви можете вказати використовувану множину в якості другого аргумента:

1
2
3
4
5
6
7
8

$rootNode
    ->fixXmlConfig('child', 'children')
    ->children()
        ->arrayNode('children')
            // ...
        ->end()
    ->end()
;

Окрім виправлення цьог, fixXmlConfig() гарантує, що одиничні елементи XML все одно будуть перетворені на масиви. Тому у вас може бути:

1
2

<connection>default</connection>
<connection>extra</connection>

А іноді тільки:

1

<connection>default</connection>

За замовчуванням, connection буде масивом у першому випадку, і рядком - у другому, що призведе до складностей валідації. Ви можете гарантувати, щоб він завжди був масивом, за допомогою fixXmlConfig().

Ви можете це більше контролювати процес нормалізації, якщо вам потрібно. Наприклад, ви можете захотіти дозволити установку та використання рядку в якості конкретного ключа або чіткої установки декількох ключів. Так, як якщо б все, окрім name, у цій конфігурації було необовʼязковим:

1
2
3
4
5
6

connection:
    name:     my_mysql_connection
    host:     localhost
    driver:   mysql
    username: user
    password: pass

Ви також можете дозволити наступне:

1

connection: my_mysql_connection

Змінивши значення рядку на асоціативний масив з name в якості ключа:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$rootNode
    ->children()
        ->arrayNode('connection')
            ->beforeNormalization()
                ->ifString()
                ->then(function ($v) { return array('name' => $v); })
            ->end()
            ->children()
                ->scalarNode('name')->isRequired()
                // ...
            ->end()
        ->end()
    ->end()
;

Правила валідації

Просунутіші правила валідації можна надати, використовуючи ExprBuilder. Цей конструктор реалізує поточний інтерфейс для широковідомої структури контролю. Конструктор використовується для додавання просунутих правил валідації до визначень вузлів, на кшталт:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$rootNode
    ->children()
        ->arrayNode('connection')
            ->children()
                ->scalarNode('driver')
                    ->isRequired()
                    ->validate()
                        ->ifNotInArray(array('mysql', 'sqlite', 'mssql'))
                        ->thenInvalid('Invalid database driver %s')
                    ->end()
                ->end()
            ->end()
        ->end()
    ->end()
;

Правило валідації завжди має частину "if" ("якщо"). Ви можете вказати цю частину наступнимм чином:

• ifTrue()
• ifString()
• ifNull()
• ifEmpty() (починаючи з Symfony 3.2)
• ifArray()
• ifInArray()
• ifNotInArray()
• always()

Правило валідації також вимагає частини "then" ("то"):

• then()
• thenEmptyArray()
• thenInvalid()
• thenUnset()

Зазвичай, "then" є замикаючим. Його зворотне значення буде використано в якості нового значення для вузла, замість початкового значення вузла.

Конфігурація роздільника шляху вузла

Розгляньте наступний приклад конструктора конфігурації:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$treeBuilder = new TreeBuilder();
$rootNode = $treeBuilder->root('database');

$treeBuilder = new TreeBuilder('database');

$treeBuilder->getRootNode()
    ->children()
        ->arrayNode('connection')
            ->children()
                ->scalarNode('driver')->end()
            ->end()
        ->end()
    ->end()
;

За замовчуванням, ієрархія вузлів у шляху конфігурації визначається за допомогою символу крапки (.):

1
2
3
4
5
6
7

// ...

$node = $treeBuilder->buildTree();
$children = $node->getChildren();
$childChildren = $children['connection']->getChildren();
$path = $childChildren['driver']->getPath();
// $path = 'database.connection.driver'

Використайте метод setPathSeparator() у конструкторі конфігурації, щоб змінити роздільник шляху:

1
2
3
4
5
6
7
8

// ...

$treeBuilder->setPathSeparator('/');
$node = $treeBuilder->buildTree();
$children = $node->getChildren();
$childChildren = $children['connection']->getChildren();
$path = $childChildren['driver']->getPath();
// $path = 'database/connection/driver'

Обробка значень конфігурації

Processor використовує дерево, так як він був побудований, використовуючи TreeBuilder, щоб обробляти декільлка масивів значень конфігурації, які повинні бути обʼєднані. Якщо будь-яке значення не має очікуваного типу, обовʼязкове, але не визначене, або не може бути валідоване будь-яким іншим способом, буде викикане виключення. Інакше, результатом буде чистий масив значень конфігурації:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use Acme\DatabaseConfiguration;
use Symfony\Component\Config\Definition\Processor;
use Symfony\Component\Yaml\Yaml;

$config = Yaml::parse(
    file_get_contents(__DIR__.'/src/Matthias/config/config.yaml')
);
$extraConfig = Yaml::parse(
    file_get_contents(__DIR__.'/src/Matthias/config/config_extra.yaml')
);

$configs = [$config, $extraConfig];

$processor = new Processor();
$databaseConfiguration = new DatabaseConfiguration();
$processedConfiguration = $processor->processConfiguration(
    $databaseConfiguration,
    $configs
);