Creare una classe Extension¶

Se si sceglie di esporre una configurazione semantica per il proprio bundle, si avrà prima bisogno di creare una nuova classe "Extension", per gestire il processo. Tale classe va posta nella cartella DependencyInjection del proprio bundle e il suo nome va costruito sostituendo il postfisso Bundle del nome della classe del bundle con Extension. Per esempio, la classe Extension di AcmeHelloBundle si chiamerebbe AcmeHelloExtension:

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

// Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
namespace Acme\HelloBundle\DependencyInjection;

use Symfony\Component\HttpKernel\DependencyInjection\Extension;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class AcmeHelloExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container)
    {
        // qui sta tutta la logica
    }

    public function getXsdValidationBasePath()
    {
        return __DIR__.'/../Resources/config/';
    }

    public function getNamespace()
    {
        return 'http://www.example.com/symfony/schema/';
    }
}

La presenza della classe precedente vuol dire che si può definire uno spazio dei nomi acme_hello in un qualsiasi file di configurazione. Lo spazio dei nomi acme_hello viene dal nome della classe Extension, a cui è stata rimossa la parola Extension e posto in minuscolo e con trattini bassi il resto del nome. In altre parole, AcmeHelloExtension diventa acme_hello.

Si può iniziare specificando la configurazione sotto questo spazio dei nomi:

Analisi dell'array $configs¶

Ogni volta che un utente include lo spazio dei nomi acme_hello in un file di configurazione, la configurazione sotto di esso viene aggiunta a un array di configurazioni e passata al metodo load() dell'estensione (Symfony2 converte automaticamente XML e YAML in array).

Si prenda la seguente configurazione:

L'array passato al metodo load() sarà simile a questo:

1
2
3
4
5
6

array(
    array(
        'pippo' => 'valoreDiPippo',
        'pluto' => 'valoreDiPluto',
    )
)

Si noti che si tratta di un array di array, non di un semplice array di valori di configurazione. È stato fatto intenzionalmente. Per esempio, se acme_hello appare in un altro file di configurazione, come config_dev.yml, con valori diversi sotto di esso, l'array in uscita sarà simile a questo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

array(
    array(
        'pippo' => 'valoreDiPippo',
        'pluto' => 'valoreDiPluto',
    ),
    array(
        'pippo' => 'valoreDevDiPippo',
        'baz' => 'nuovaVoceDiConfig',
    ),
)

L'ordine dei due array dipende da quale è stato definito prima.

È compito di chi sviluppa il bundle, quindi, decidere in che modo tali configurazioni vadano fuse insieme. Si potrebbe, per esempio, voler fare in modo che i valori successivi sovrascrivano quelli precedenti, oppure fonderli in qualche modo.

Successivamente, nella sezione classe Configuration, si imparerà un modo robusto per gestirli. Per ora, ci si può accontentare di fonderli a mano:

1
2
3
4
5
6
7
8
9

public function load(array $configs, ContainerBuilder $container)
{
    $config = array();
    foreach ($configs as $subConfig) {
        $config = array_merge($config, $subConfig);
    }

    // usare ora l'array $config
}

Usare il metodo load()¶

Con load(), la variabile $container si riferisce a un contenitore che conosce solo la configurazione del proprio spazio dei nomi (cioè non contiene informazioni su servizi caricati da altri bundle). Lo scopo del metodo load() è quello di manipolare il contenitore, aggiungere e configurare ogni metodo o servizio necessario per il proprio bundle.

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

use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
use Symfony\Component\Config\FileLocator;

public function load(array $configs, ContainerBuilder $container)
{
    // ... prepara la propria variabile $config

    $loader = new XmlFileLoader(
        $container,
        new FileLocator(__DIR__.'/../Resources/config')
    );
    $loader->load('services.xml');
}

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

public function load(array $configs, ContainerBuilder $container)
{
    // ... prepara la propria variabile $config

    $loader = new XmlFileLoader(
        $container,
        new FileLocator(__DIR__.'/../Resources/config')
    );

    if (isset($config['enabled']) && $config['enabled']) {
        $loader->load('services.xml');
    }
}

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

<!-- src/Acme/HelloBundle/Resources/config/services.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <parameters>
        <parameter key="acme_hello.my_service_type" />
    </parameters>

    <services>
        <service id="acme_hello.my_service" class="Acme\HelloBundle\MyService">
            <argument>%acme_hello.my_service_type%</argument>
        </service>
    </services>
</container>

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

public function load(array $configs, ContainerBuilder $container)
{
    // ... prepara la propria variabile $config

    $loader = new XmlFileLoader(
        $container,
        new FileLocator(__DIR__.'/../Resources/config')
    );
    $loader->load('services.xml');

    if (!isset($config['mio_tipo'])) {
        throw new \InvalidArgumentException(
            'The "mio_tipo" option must be set'
        );
    }

    $container->setParameter(
        'acme_hello.my_service_type',
        $config['mio_tipo']
    );
}

Validazione e fusione con una classe Configuration¶

Finora, la fusione degli array di configurazione è stata fatta a mano, verificando la presenza di valori di configurazione con la funzione isset() di PHP. Un sistema opzionale Configuration è disponibile, per aiutare nella fusione, nella validazione, con i valori predefiniti e per la normalizzazione dei formati.

Per sfruttare questo sistema, si creerà una classe Configuration e si costruirà un albero, che definisce la propria configurazione in tale classe:

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

// src/Acme/HelloBundle/DependencyInjection/Configuration.php
namespace Acme\HelloBundle\DependencyInjection;

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

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

        $rootNode
            ->children()
            ->scalarNode('mio_tipo')->defaultValue('pluto')->end()
            ->end();

        return $treeBuilder;
    }
}

Questo è un esempio molto semplice, ma si può ora usare questa classe nel proprio metodo load(), per fondere la propria configurazione e forzare la validazione. Se viene passata un'opzione che non sia mio_tipo, l'utente sarà avvisato con un'eccezione del passaggio di un'opzione non supportata:

1
2
3
4
5
6
7
8

public function load(array $configs, ContainerBuilder $container)
{
    $configuration = new Configuration();

    $config = $this->processConfiguration($configuration, $configs);

    // ...
}

Il metodo processConfiguration() usa l'albero di configurazione definito nella classe Configuration per validare, normalizzare e fondere tutti gli array di configurazione insieme.

La classe Configuration può essere molto più complicata di quanto mostrato qui, poiché supporta nodi array, nodi "prototipo", validazione avanzata, normalizzazione specifica di XML e fusione avanzata. Il modo migliore per vederla in azione è guardare alcune classi Configuration del nucleo, come quella FrameworkBundle o di TwigBundle.

 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

// src/Acme/HelloBundle/DependencyExtension/Configuration.php
namespace Acme\HelloBundle\DependencyInjection;

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

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

        $rootNode
            ->children()
                ->scalarNode('mio_tipo')
                    ->defaultValue('pluto')
                    ->setInfo('cosa configura mio_tipo')
                    ->setExample('impostazione di esempio')
                ->end()
            ->end()
        ;

        return $treeBuilder;
    }
}

Convenzioni per l'estensione¶

Quando si crea un'estensione, seguire queste semplici convenzioni:

• L'estensione deve trovarsi nel sotto-spazio dei nomi DependencyInjection;
• l'estensione deve avere lo stesso nome del bundle, ma con Extension (AcmeHelloExtension per AcmeHelloBundle);
• L'estensione deve fornire uno schema XSD.

Se si seguono queste semplici convenzioni, la propria estensione sarà registrata automaticamente da Symfony2. In caso contrario, sovrascrivere il metodo build() nel proprio bundle:

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

// ...
use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass;

class AcmeHelloBundle extends Bundle
{
    public function build(ContainerBuilder $container)
    {
        parent::build($container);

        // registrare a mano estensioni che non seguono le convenzioni
        $container->registerExtension(new UnconventionalExtensionClass());
    }
}

In questo caso, la classe Extension deve implementare anche un metodo getAlias() e restituire un alias univoco, con nome che dipende dal bundle (p.e. acme_hello). Questo perché il nome della classe non segue le convenzioni e non finisce per Extension.

Inoltre, il metodo load() dell'estensione sarà richiamato solo se l'utente specifica l'alias acme_hello in almeno un file di configurazione. Ancora, questo perché la classe Extension non segue le convenzioni viste sopra, quindi non succede nulla in modo automatico.