The Components Book for Symfony 2.4

Transcript

1 The Components Book for Symfony. generated on November, 0

2 The Components Book (.) This work is licensed under the Attribution-Share Alike.0 Unported license ( licenses/by-sa/.0/). You are free to share (to copy, distribute and transmit the work), and to remix (to adapt the work) under the following conditions: Attribution: You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work). Share Alike: If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license. For any reuse or distribution, you must make clear to others the license terms of this work. The information in this book is distributed on an as is basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor SensioLabs shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work. If you find typos or errors, feel free to report them by creating a ticket on the Symfony ticketing system ( Based on tickets and users feedback, this book is continuously updated.

3 Contents at a Glance Installare e usare i componenti di Symfony... Il componente ClassLoader... Class Loader PSR-0... MapClassLoader...0 Cache di Class Loader... Debug di un Class Loader... Generatore di classi di mappe... Il componente Config... Caricare risorse... Cache basata sulle risorse...0 Definire e processare valori di configurazione... Il componente Console... Uso di Console... Come costruire un'applicazione in un singolo comando... Usare gli eventi... Aiutante Dialog... Aiutante Formatter... Aiutante Progress... Aiutante Table... Il componente CssSelector... Il componente Debug... Debug di ClassLoader... Il componente DependencyInjection... Tipi di iniezione... Introduzione ai parametri... Lavorare con parametri e definizioni del contenitore... Compilazione del contenitore... Usare i tag nei servizi... Come usare un factory per creare servizi... Configurare servizi con un configuratore di servizi Come gestire le dipendenze comuni con servizi genitori... 0 Configurazione avanzata del contenitore... 0 Servizi pigri... 0 Flusso di costruzione del contenitore... Il componente DomCrawler... Il componente EventDispatcher... generated on November, 0 Contents at a Glance iii

4 Il distributore consapevole del contenitore... Oggetto evento generico... L'Event Dispatcher Immutable... Distributore di eventi tracciabile... Il componente ExpressionLanguage... 0 Sintassi di Expression... Estendere ExpressionLanguage... Cache di espressioni analizzate... Il componente Filesystem... Il componente Finder... Il componente Form... Creare un indovino di tipi... Eventi dei form... 0 Il componente HttpFoundation... Gestione della sessione... Configurare sessioni e gestori di salvataggio... 0 Test con le sessioni... 0 Integrazione con sessioni legacy... Proxy fidati... Il componente HttpKernel... Il componente Intl... Il componente OptionsResolver... Il componente Process... Il componente PropertyAccess... 0 Il componente Routing... Corrispondere una rotta in base all'host... Il componente Security... Il Firewall e il contesto di sicurezza... Autenticazione... Autorizzazione... Il componente Serializer... Il componente Stopwatch... Il componente Templating... 0 Aiutante slots... Aiutante per gli asset... Il componente Translation... Uso di Translator... 0 Il componente YAML... 0 Il formato YAML... iv Contents at a Glance Contents at a Glance

5 Chapter Installare e usare i componenti di Symfony Se si inizia un nuovo progetto (o se si ha già un progetto) che userà uno o più componenti, il modo più semplice per integrare tutto è con Composer. Composer è abbastanza intelligente da scaricare i componenti necessari e occuparsi del caricamento automatico, in modo che si può iniziare a usare immediatamente le librerie. Questo articolo approfondirà l'uso di Il componente Finder, tuttavia è applicabile all'uso di qualsiasi componente. Uso del componente Finder. Se si sta creando un nuovo progetto, creare una cartella vuota.. Creare un file chiamato composer.json e incollarvi dentro il codice seguente: Listing - "require": "symfony/finder": "..*" Se si ha già un file composer.json, aggiungere semplicemente la riga. Potrebbe essere necessario modificare la versione (p.e... o..*). Si possono cercare nomi e versioni dei componenti su packagist.org.. Installare composer, se non è già presente sul proprio sistema:. Scaricare le librerie dei venditori e generare il file vendor/autoload.php: Listing - $ php composer.phar install. Scrivere il proprio codice: generated on November, 0 Chapter : Installare e usare i componenti di Symfony

6 Una volta che Composer ha scaricato i componenti, basterà includere il file vendor/autoload.php generato da Composer stesso. Tale file si occupa di autocaricare tutte le librerie, in modo che si possano usare immediatamente: Listing - 0 // File: src/script.php // cambiare il percorso in quello della cartella "vendor/", relativamente a questo file require_once '../vendor/autoload.php'; use Symfony\Component\Finder\Finder; $finder = new Finder(); $finder->in('../data/'); Se si vogliono usare tutti i componenti di Symfony, invece di aggiungerli uno alla volta: Listing - "require": "symfony/finder": "..*", "symfony/dom-crawler": "..*", "symfony/css-selector": "..*" si può usare: Listing - "require": "symfony/symfony": "..*" Questo includerà le librerie dei bundle e dei bridge, che potrebbero non essere necessarie. E ora? Ora che i componenti sono installati e autocaricati, leggere la documentazione specifica dei componenti per saperne di più sul loro uso. Buon divertimento! generated on November, 0 Chapter : Installare e usare i componenti di Symfony

7 Chapter Il componente ClassLoader Il componente ClassLoader carica le classi di un progetto automaticamente, purché seguano alcune convenzioni standard di PHP. Uso Ogni volta che si usa una classe non ancora richiesta o inclusa, PHP utilizza il meccanismo di autocaricamento per delegare il caricamento di un file che definisca la classe. Symfony fornisce due autoloader, capaci di caricare classi: Class Loader PSR-0: carica classi che seguono lo standard dei nomi PSR-0; MapClassLoader: carica classi che usano una mappa statica dal nome della classe al percorso del file. Inoltre, il componente ClassLoader di Symfony dispone di un insieme di classi wrapper, che si possono usare per aggiungere funzionalità agli autoloader esistenti: Cache di Class Loader Debug di un Class Loader Installazione Si può installare il componente in due modi: Usare il repository ufficiale su Git ( ); Installarlo via Composer (symfony/class-loader su Packagist ) generated on November, 0 Chapter : Il componente ClassLoader

8 Chapter Class Loader PSR-0 Se si usano classi e librerie di terze parti che seguono lo standard PSR-0, si può usare la classe ClassLoader per caricare tutte le classi del progetto. Si possono usare sia ApcClassLoader sia XcacheClassLoader per mettere in cache un'istanza di ClassLoader o di DebugClassLoader per il debug. Uso La registrazione dell'autoloader ClassLoader è semplice: Listing - 0 require_once '/path/to/src/symfony/component/classloader/classloader.php'; use Symfony\Component\ClassLoader\ClassLoader; $loader = new ClassLoader(); // per abilitare la ricerca in include_path (per esempio per i pacchetti PEAR) $loader->useincludepath(true); registrare qui spazi di nomi e prefissi, vedere più avanti $loader->register(); In un'applicazione Symfony, l'autoloader è registrato automaticamente (vedere app/ autoload.php) generated on November, 0 Chapter : Class Loader PSR-0

9 Usare i metodi addprefix() o addprefixes() per registrare le classi: Listing - 0 // registra un singolo spazio di nomi $loader->addprefix('symfony', DIR.'/vendor/symfony/symfony/src'); // registra più spazi di nomi $loader->addprefixes(array( 'Symfony' => DIR.'/../vendor/symfony/symfony/src', 'Monolog' => DIR.'/../vendor/monolog/monolog/src', )); // registra un prefisso di una classe che segue le convenzioni di PEAR $loader->addprefix('twig_', DIR.'/vendor/twig/twig/lib'); $loader->addprefixes(array( 'Swift_' => DIR.'/vendor/swiftmailer/swiftmailer/lib/classes', 'Twig_' => DIR.'/vendor/twig/twig/lib', )); Si possono cercare le classi di un sotto-spazio dei nomi o di una sotto-gerarchia di classi PEAR in una lista di posizioni, per facilitare la gestione dei venditori di un sottoinsieme di classi per grandi progetti: Listing - $loader->addprefixes(array( 'Doctrine\\Common' => DIR.'/vendor/doctrine/common/lib', 'Doctrine\\DBAL\\Migrations' => DIR.'/vendor/doctrine/migrations/lib', 'Doctrine\\DBAL' => DIR.'/vendor/doctrine/dbal/lib', 'Doctrine' => DIR.'/vendor/doctrine/orm/lib', )); In questo esempio, se si prova a usare una classe nello spazio dei nomi Doctrine\Common o uno dei suoi figli, l'autoloader cercherà prima la classe sotto la cartella doctrine-common. Se non trovata, ripiegherà alla cartella predefinita Doctrine (l'ultima configurata), prima di arrendersi. L'ordine delle registrazioni dei prefissi, in questo caso, è significativo generated on November, 0 Chapter : Class Loader PSR-0

10 Chapter MapClassLoader La classe MapClassLoader consente di auto-caricare file tramite una mappa statica, dalle classi ai file. È utile se si usano librerire di terze parti, che non seguono lo standard PSR-0 e quindi non possono usare class loader PSR-0. Si può usare MapClassLoader insieme a class loader PSR-0, configurando e richiamando su entrambi il metodo register(). Il comportamento predefinito è di appendere MapClassLoader alla pila di auto-caricamento. Se lo si vuole usare come primo autoloader, passare true al metodo register(). In questo caso, il class loader sarà messo in cima alla pila di auto-caricamento. Uso È facile, basta passare la mappa al costruttore, quando si crea un'istanza della classe MapClassLoader: Listing - 0 require_once '/path/to/src/symfony/component/classloader/mapclassloader'; $mapping = array( 'Pippo' => '/percorso/di/pippo', 'Pluto' => '/percorso/di/pluto', ); $loader = new MapClassLoader($mapping); $loader->register();. generated on November, 0 Chapter : MapClassLoader 0

11 Chapter Cache di Class Loader Introduzione Trovare un file per una classe specifica può essere pesante. Per fortuna, il componente Class Loader dispone di due classi per la cache della mappatura da classe a file. Sia ApcClassLoader che XcacheClassLoader sono wrapper intorno all'oggetto che implementa un metodo findfile(), per trovare il file di una classe. Sia ApcClassLoader che XcacheClassLoader possono essere usati per la cache dell'autoloader di Composer. ApcClassLoader ApcClassLoader è un wrapper di un class loader esistente e mette in cache le chiamate al suo metodo findfile(), usando APC : Listing - require_once '/path/to/src/symfony/component/classloader/apcclassloader.php'; // istanza di una classe che implementa un metodo findfile(), come ClassLoader $loader =...; // mio_prefisso è il prefisso da usare in APC $cachedloader = new ApcClassLoader('mio_prefisso', $loader); // registra il class loader in cache generated on November, 0 Chapter : Cache di Class Loader

12 0 $cachedloader->register(); // disattiva il loader originale, non in cache, se era stato precedentemente registrato $loader->unregister(); XcacheClassLoader XcacheClassLoader usa XCache per mettere in cache un class loader. La registrazione è semplice: Listing - 0 require_once '/path/to/src/symfony/component/classloader/xcacheclassloader.php'; // istanza di una classe che implementa un metodo findfile(), come ClassLoader $loader =...; // mio_prefisso è il prefisso da usare in XCache $cachedloader = new XcacheClassLoader('mio_prefisso', $loader); // registra il class loader in cache $cachedloader->register(); // disattiva il loader originale, non in cache, se era stato precedentemente registrato $loader->unregister();. generated on November, 0 Chapter : Cache di Class Loader

13 Chapter Debug di un Class Loader A partire da Symfony., DebugClassLoader del componente ClassLoader è deprecato. Usare DebugClassLoader fornito dal componente Debug. generated on November, 0 Chapter : Debug di un Class Loader

14 Chapter Generatore di classi di mappe Il caricamento di una classe è solitamente facile, con gli standard PSR-0 e PSR-. Grazie al componente ClassLoader di Symfony o al meccanismo fornito da Composer, non occorre mappare manualmente i nomi di classi ai file PHP. Oggiogiorno, le librerie PHP solitamente dispongono di un supporto per il caricamento tramite Composer. A volte però capita di usare librerie di terze parti che non dispongono di un supporto per il caricamento, che constringono quindi a caricare ogni classe a mano. Per esempio, si immagini una libreria con la seguente struttura di cartelle: Listing - libreria/ pippo/ quiquoqua/ Paperone.php Pippo.php pluto/ paperino/ Pippo.php Paperrino.php Questi file contengono le seguenti classi: File libreria/pluto/paperino/paperone.php libreria/pluto/pippo.php libreria/pippo/pluto/pippo.php libreria/pippo/pluto.php Nome classe Acme\Pluto\Paperino Acme\Pluto Acme\Pippo\Pluto Acme\Pippo Per facilitare le cose, il componente ClassLoader dispone di una classe ClassMapGenerator, che rende possibile creare una mappa di nomi di classi e file generated on November, 0 Chapter : Generatore di classi di mappe

15 Generare una mappa di classi Per generare una mappa di classi, basta passare la cartella radice dei file delle classi al metodo createmap() : Listing - use Symfony\Component\ClassLoader\ClassMapGenerator; print_r(classmapgenerator::createmap( DIR.'/library')); Dati file e classi della tabella precedente, si dovrebbe ottnere un output come questo: Listing - Array ( [Acme\Pippo] => /var/www/library/pippo/pluto.php [Acme\Pippo\Pluto] => /var/www/library/pippo/pluto/pippo.php [Acme\Pluto\Paperino] => /var/www/library/pluto/paperino/paperone.php [Acme\Pluto] => /var/www/library/pluto/pippo.php ) Esportare la mappa di classi La scrittura della mappa di classi sulla console non è sufficiente per il caricamento automatico. Per fortuna, ClassMapGenerator dispone di un metodo dump(), per salvare la mappa di classi generata su filesystem: Listing - use Symfony\Component\ClassLoader\ClassMapGenerator; ClassMapGenerator::dump( DIR.'/library', DIR.'/class_map.php'); Questa chiamata a dump() genera la mappa di classi e la scrive nel file class_map.php nella stessa cartella, con il seguente contenuto: Listing - <?php return array ( 'Acme\\Pippo' => '/var/www/library/pippo/pluto.php', 'Acme\\Pippo\\Pluto' => '/var/www/library/pippo/pluto/pippo.php', 'Acme\\Pluto\\Baz' => '/var/www/library/pluto/paperino/paperone.php', 'Acme\\Pluto' => '/var/www/library/pluto/pippo.php', ); Invece di caricare ogni file a mano, basta generare la mappa di classi generata, per esempio usando MapClassLoader : Listing - use Symfony\Component\ClassLoader\MapClassLoader; $mapping = include DIR.'/class_map.php'; $loader = new MapClassLoader($mapping); $loader->register(); // ora si possono usare le classi: generated on November, 0 Chapter : Generatore di classi di mappe

16 0 use Acme\Pippo; $pippo = new Pippo(); L'esempio ipotizza che si abbia già un autoloader funzionante (p.e. tramite Composer o uno dei caricatori di classi del componente ClassLoader. Oltre a esportare la mappa di classi per una cartella, si può anche passare un array di cartelle per cui generare la mappa di classi (il risultato è lo stesso dell'esempio precedente): Listing - use Symfony\Component\ClassLoader\ClassMapGenerator; ClassMapGenerator::dump(array( DIR.'/library/pluto', DIR.'/library/pippo'), DIR.'/class_map.php');. generated on November, 0 Chapter : Generatore di classi di mappe

17 Chapter Il componente Config Il componente Config fornisce diverse classi che aiutano a trovare, caricare, combinare, riempire e validare valori di configurazione di ogni tipo, indipendentemente dal tipo di sorgente (file YAML, XML o INI, oppure ad esempio una base dati). IniFileLoader analizza i contenuti dei file usando la funzione parse_ini_file, quindi si possono impostare solamente parametri stringa. Per impostare tipi di versi di parametri (p.e. booleani, interi, ecc), si raccomanda l'uso di altri caricatori. Installazione Si può installare il componente in molti modi diversi: Installarlo tramite Composer (symfony/config su Packagist ); Usare il repository ufficiale su Git ( ). Sezioni Caricare risorse Cache basata sulle risorse Definire e processare valori di configurazione generated on November, 0 Chapter : Il componente Config

18 Chapter Caricare risorse Trovare le risorse Il caricamento della configurazione solitamente inizia con la ricerca delle risorse, nella maggior parte dei casi dei file. Lo si può fare con FileLocator : Listing - use Symfony\Component\Config\FileLocator; $configdirectories = array( DIR.'/app/config'); $locator = new FileLocator($configDirectories); $yamluserfiles = $locator->locate('utenti.yml', null, false); Il cercatore di risorse riceve un insieme di posizioni in cui cercare file. Il primo parametro di locate() è il nome del file da cercare. Il secondo parametro può essere il percorso e, se fornito, il cercatore cercherà prima in tale cartella. Il terzo parametro indica se il cercatore debba restituire il primo file trovato oppure un array con tutte le corrispondenze. Caricatori di risorse Per ciascun tipo di risorsa (Yaml, XML, annotazioni, ecc.) va definito un caricatore. Ogni caricatore deve implementare LoaderInterface o estendere la classe astratta FileLoader, che consente di importare ricorsivamente altre risorse: Listing - use Symfony\Component\Config\Loader\FileLoader; use Symfony\Component\Yaml\Yaml; generated on November, 0 Chapter : Caricare risorse

19 0 0 class YamlUserLoader extends FileLoader public function load($resource, $type = null) $configvalues = Yaml::parse($resource); gestione dei valori di configurazione // possibile importazione di altri risorse: // $this->import('altri_utenti.yml'); public function supports($resource, $type = null) return is_string($resource) && 'yml' === pathinfo( $resource, PATHINFO_EXTENSION ); Trovare il giusto caricatore La classe LoaderResolver riceve un insieme di caricatori come primo parametro del suo costruttore. Quando una risorsa (per esempio un file XML) va caricata, cerca in questo insieme di caricatori e restituisce il caricatore che supporta questo particolare tipo di risorsa. La classe DelegatingLoader fa uso di LoaderResolver. Quando gli viene richiesto di caricare una risorsa, delega la questione a LoaderResolver. Se quest'ultimo trova un caricatore adatto, a tale caricatore sarà chiesto di caricare la risorsa: Listing - 0 use Symfony\Component\Config\Loader\LoaderResolver; use Symfony\Component\Config\Loader\DelegatingLoader; $loaderresolver = new LoaderResolver(array(new YamlUserLoader($locator))); $delegatingloader = new DelegatingLoader($loaderResolver); $delegatingloader->load( DIR.'/utenti.yml'); /* Sarà usato YamlUserLoader per caricare questa risorsa, poiché supporta file con estensione "yml" */ generated on November, 0 Chapter : Caricare risorse

20 Chapter 0 Cache basata sulle risorse Quando tutte le risorse di configurazione sono state caricate, si potrebbero voler processare i valori di configurazione e combinarli un unico file. Questo file agisce da cache. I suoi contenuti non devono essere rigenerati ogni volta che gira l'applicazione, ma solo quando le risorse di configurazione vengono modificate. Per esempio, il componente Routing di Symfony consente di caricare tutte le rotte e poi di esportare un matcher di UL o un generatore di URL, basati su tali rotte. In questo caso, quando una delle risorse viene modificata (e si sta lavorando in un ambiente di sviluppo), il file generato va invalidato e rigenerato. Si può ottenere questo risultato usando la classe ConfigCache. L'esempio successivo mostra come raccogliere le risorse e generare un codice, basato sulle risorse caricate, e scrivere tale codice in cache. La cache riceve anche l'insieme di risorse usate per generare il codice. Cercando il timestamp "last modified" di tali risorse, la cache può dirci se è ancora fresca o se i suoi contenuti vanno rigenerati: Listing 0-0 use Symfony\Component\Config\ConfigCache; use Symfony\Component\Config\Resource\FileResource; $cachepath = DIR.'/cache/appUserMatcher.php'; // il secondo parametro indica se si è in debug o meno $usermatchercache = new ConfigCache($cachePath, true); if (!$usermatchercache->isfresh()) // inserire un array di percorsi per il file 'utenti.yml' $yamluserfiles =...; $resources = array(); foreach ($yamluserfiles as $yamluserfile) // vedere la voce precedente "Caricare risorse" per // capire da dove viene $delegatingloader $delegatingloader->load($yamluserfile); $resources[] = new FileResource($yamlUserFile);. generated on November, 0 Chapter 0: Cache basata sulle risorse 0

21 0 // il codice per UserMatcher è generato altrove $code =...; $usermatchercache->write($code, $resources); // si potrebbe voler richiedere il codice in cache: require $cachepath; In debug, sarà creato un file.meta nella stessa cartella del file di cache stesso. Tale file.meta contiene le risorse serializzate, i cui timestamp sono usati per determinare se la cache è ancora fresca. Se non si è in debug, la cache è considerata fresca fintanto che esiste, per cui non viene generato alcun file.meta. generated on November, 0 Chapter 0: Cache basata sulle risorse

22 Chapter Definire e processare valori di configurazione Validare i valori di configurazione Dopo aver caricato i valori di configurazione da ogni tipo di risorsa, i valori e le loro strutture possono essere validati, usando la parte "Definition" del componente Config. Solitamente ci si aspetta che i valori di configurazione mostrino un qualche tipo di gerarchia. Inoltre, i valori dovrebbero essere di un certo tipo, ristretti in numero o all'interno di un determinato insieme di valori. Per esempio, la configurazione seguente (in Yaml) mostra una chiara gerarchia e alcune regole di validazione che vi andrebbero applicate (come: "il valore per auto_connect deve essere booleano"): Listing - 0 auto_connect: true default_connection: mysql connections: mysql: host: localhost driver: mysql username: utente password: pass sqlite: host: localhost driver: sqlite memory: true username: utente password: pass Quando si caricano diversi file di configurazione, dovrebbe essere possibile fondere e sovrascrivere alcuni valori. Gli altri valori non vanno fusi e devono rimanere come prima. Inoltre, alcune chiavi sono disponibili solo quando un altra chiave ha uno specifico valore (nell'esempio precedente: la chiave memory ha senso solo quando driver è sqlite). generated on November, 0 Chapter : Definire e processare valori di configurazione

23 Definire una gerarchia di valori di configurazione con TreeBuilder Tutte le regole relative ai valori di configurazione possono essere definite tramite TreeBuilder. Un'istanza di TreeBuilder va restituita da una classe personalizzata Configuration, che implementa ConfigurationInterface : Listing - 0 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'); aggiungere definizioni di nodi alla radice dell'albero return $treebuilder; Aggiungere definizioni di nodi all'albero Nodi variabili Un albero contiene definizioni di nodi, che possono essere stratificati in modo semantico. Questo vuol dire che, usando l'indentazione e la notazione fluida, è possibile riflettere la reale struttura dei valori di configurazione: Listing - 0 $rootnode ->children() ->booleannode('auto_connessione') ->defaulttrue() ->end() ->scalarnode('connessione_predefinita') ->defaultvalue('predefinito') ->end() ->end() ; Lo stesso nodo radice è un nodo array e ha dei figli, come il nodo booleano auto_connect e il nodo scalare default_connection. In generale: dopo aver definito un nodo, una chiamata end() porta un gradino in alto nella gerarchia generated on November, 0 Chapter : Definire e processare valori di configurazione

24 Tipo di nodo Si può validare il tipo di un valore fornito, usando l'appropriata definizione di nodo. I tipi di nodo disponibili sono: scalare booleano intero (nuovo in.) virgola mobile enum array variabile (nessuna validazione) e sono creati con node($nome, $tipo) o con i relativi metodi scorciatoia xxxxnode($nome). Nodi di vincoli numerici New in version.: I nodi numerici (virgola mobile e intero) sono nuovi in. I nodi numerici (virgola mobile e intero) foniscono due vincoli extra, min() e max(), che consentono di validare il valore: Listing - 0 $rootnode ->children() ->integernode('valore_positivo') ->min(0) ->end() ->floatnode('valore_grosso') ->max(e) ->end() ->integernode('valore_tra_estremi') ->min(-0)->max(0) ->end() ->end() ; Nodi enum I nodi enum forniscono un vincolo che fa corrispondere il dato inserito a una serie divalori: Listing - $rootnode ->children() ->enumnode('genere') ->values(array('maschio', 'femmina')) ->end() ->end() ; Questo restringe l'opzione genere ai valori maschio o femmina generated on November, 0 Chapter : Definire e processare valori di configurazione

25 Nodi array Si può aggiungere un livello ulteriore alla gerarchia, aggiungendo un nodo array. Il nodo array stesso potrebbe avere un insieme predefinito di nodi variabili: Listing - 0 $rootnode ->children() ->arraynode('connection') ->children() ->scalarnode('driver')->end() ->scalarnode('host')->end() ->scalarnode('utente')->end() ->scalarnode('password')->end() ->end() ->end() ->end() ; Oppure si può definire un prototipo per ogni nodo dentro un nodo array: Listing - 0 $rootnode ->children() ->arraynode('connections') ->prototype('array') ->children() ->scalarnode('driver')->end() ->scalarnode('host')->end() ->scalarnode('utente')->end() ->scalarnode('password')->end() ->end() ->end() ->end() ->end() ; Si può usare un prototipo per aggiungere una definizione, che potrebbe essere ripetuta molte volte dentro il nodo corrente. In base alla definizione del prototipo nell'esempio precedente, è possibile avere molte array di connessione (contenenti driver, host, ecc.). Opzioni dei nodi array Prima di definire i figli di un nodo array, si possono fornire opzioni, come: useattributeaskey() Fornisce il nome di un nodo figlio, i cui valori sono usati come chiavi nell'array risultante requiresatleastoneelement() Dovrebbe esserci almeno un elemento nell'array (funziona solo se viene richiamato anche isrequired()). adddefaultsifnotset() Se dei nodi figli hanno valori predefiniti, usarli se non sono stati forniti dati espliciti. Un esempio: Listing - $rootnode ->children() ->arraynode('parameters') generated on November, 0 Chapter : Definire e processare valori di configurazione

26 0 ; ->isrequired() ->requiresatleastoneelement() ->useattributeaskey('nome') ->prototype('array') ->children() ->scalarnode('valore')->isrequired()->end() ->end() ->end() ->end() ->end() In YAML, la configurazione potrebbe essere come questa: Listing - database: parameters: param: valore: paramval In XML, ciascun nodo parameters avrebbe un attributo name (insieme a value), che sarebbe rimosso e usato come chiave per tale elemento nell'array finale. L'opzione useattributeaskey è utile per normalizzare il modo in cui gli array sono specificati tra formati diversi, come XML e YAML. Valori predefiniti e obbligatori Per tutti i tipi di nodo, è possibile definire valori predefiniti e valori di rimpiazzo nel caso in cui un nodo abbia un determinato valore: defaultvalue() Imposta un valore predefinito isrequired() Deve essere definito (ma può essere vuoto) cannotbeempty() Non può contenere un valore vuoto default*() (null, true, false), scorciatoia per defaultvalue() treat*like() (null, true, false), fornisce un valore di rimpiazzo in caso in cui il valore sia *. Listing -0 0 $rootnode ->children() ->arraynode('connection') ->children() ->scalarnode('driver') ->isrequired() ->cannotbeempty() ->end() ->scalarnode('host') ->defaultvalue('localhost') ->end() ->scalarnode('username')->end() generated on November, 0 Chapter : Definire e processare valori di configurazione

27 0 0 ; ->scalarnode('password')->end() ->booleannode('memory') ->defaultfalse() ->end() ->end() ->end() ->arraynode('settings') ->adddefaultsifnotset() ->children() ->scalarnode('nome') ->isrequired() ->cannotbeempty() ->defaultvalue('valore') ->end() ->end() ->end() ->end() Sezioni facoltative New in version.: I metodi canbeenabled e canbedisabled sono stati introdotti in Symfony. Se si hanno intere sezioni facoltative e che possono essere abilitate/disabilitate, si possono sfruttare le scorciatoie canbeenabled() e canbedisabled() : Listing - 0 $arraynode ->canbeenabled() ; // è equivalente a $arraynode ->treatfalselike(array('enabled' => false)) ->treattruelike(array('enabled' => true)) ->treatnulllike(array('enabled' => true)) ->children() ->booleannode('enabled') ->defaultfalse() ; Il metodo canbedisabled è uguale, tranne per il fatto che la sezione viene abilitata in modo predefinito. Opzioni di fusione Si possono fornire opzioni aggiuntive sul processo di fusione. Per gli array:. generated on November, 0 Chapter : Definire e processare valori di configurazione

28 performnodeepmerging() Quando il valore è definito anche in un altro array di configurazione, non provare a fondere un array, ma sovrascrivilo completamente Per tutti i nodi: cannotbeoverwritten() non consentire che altri array di configurazione sovrascrivano il valore di questo nodo Aggiunta di sezioni Se occorre validare una configurazione complessa, l'albero potrebbe diventare troppo grande, si potrebbe quindi volerlo separare in sezioni. Lo si può fare creando una sezione come nodo separato e quindi aggiungendola all'albero principale con append(): Listing 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('utente')->end() ->scalarnode('password')->end() ->booleannode('memory') ->defaultfalse() ->end() ->end() ->append($this->addparametersnode()) ->end() ->end() ; return $treebuilder; public function addparametersnode() $builder = new TreeBuilder(); $node = $builder->root('parameters'); $node ->isrequired() ->requiresatleastoneelement() ->useattributeaskey('nome') ->prototype('array') ->children() ->scalarnode('valore')->isrequired()->end() ->end() generated on November, 0 Chapter : Definire e processare valori di configurazione

29 ; ->end() return $node; Questo è utile per evitare di ripetersi, nel caso in cui si abbiano sezioni della configurazione ripetute in posti diversi. Normalizzazione Prima di essere processati, i file di configurazione vengono normalizzati, quindi fusi e infine si usa l'albero per validare l'array risultante. Il processo di normalizzazione si usa per rimuovere alcune differenze risultati dai vari formati di configurazione, soprattutto tra Yaml e XML. Il separatore usato nelle chiavi è tipicamente _ in Yaml e - in XML. Per esempio, auto_connect in Yaml e auto-connect. La normalizzazione rende entrambi auto_connect. La chiave interessata non sarà alterata se è mista, come pippo-pluto_muu, o se esiste già. Un'altra differenza tra Yaml e XML è il modo in cui sono rappresentati array di dati. In Yaml si può avere: Listing - twig: extensions: ['twig.extension.pippo', 'twig.extension.pluto'] e in XML: Listing - <twig:config> <twig:extension>twig.extension.pippo</twig:extension> <twig:extension>twig.extension.pluto</twig:extension> </twig:config> La normalizzazione rimuove tale differenza, pluralizzando la chiave usata in XML. Si può specificare se si vuole una chiave pluralizzata in tal modo con fixxmlconfig(): Listing - $rootnode ->fixxmlconfig('extension') ->children() ->arraynode('extensions') ->prototype('scalar')->end() ->end() ->end() ; Se la pluralizzazione è irregolare, si può specificare il plurale da usare, come secondo parametro: Listing - $rootnode ->fixxmlconfig('uovo', 'uova') ->children() ->arraynode('uova') generated on November, 0 Chapter : Definire e processare valori di configurazione

30 ; ->end() ->end() Oltre a sistemare queste cose, fixxmlconfig si assicura che i singoli elementi xml siano modificati in array. Quindi si potrebbe avere: Listing - <connessione>predefinito</connessione> <connessione>extra</connessione> e a volte solo: Listing - <connessione>default</connessione> Per impostazione predefinita, connessione sarebbe un array nel primo caso e una stringa nel secondo, rendendo difficile la validazione. Ci si può assicurare che sia sempre un array con fixxmlconfig. Se necessario, si può controllare ulteriormente il processo di normalizzazione. Per esempio, si potrebbe voler consentire che una stringa sia impostata e usata come chiave particolare o che che molte chiavi siano impostate in modo esplicito. Quindi, se tutto tranne id è facoltativo, in questa configurazione: Listing - connessione: name: connessione_mysql host: localhost driver: mysql username: utente password: pass si può consentire anche il seguente: Listing -0 connection: my_mysql_connection Cambiando un valore stringa in un array associativo con name come chiave: Listing - 0 $rootnode ->children() ->arraynode('connessione') ->beforenormalization() ->ifstring() ->then(function($v) return array('name'=> $v); ) ->end() ->children() ->scalarnode('name')->isrequired() ->end() ->end() ->end() ; generated on November, 0 Chapter : Definire e processare valori di configurazione 0

31 Regole di validazione Si possono fornire regole di validazione avanzata, usando ExprBuilder. Questa classe implementa un'interfaccia fluida per una struttura di controllo nota. Si può usare per aggiungere regole di validazione avanzate alle definizioni dei nodi, come: Listing - 0 $rootnode ->children() ->arraynode('connessione') ->children() ->scalarnode('driver') ->isrequired() ->validate() ->ifnotinarray(array('mysql', 'sqlite', 'mssql')) ->theninvalid('valore non valido "%s"') ->end() ->end() ->end() ->end() ->end() ; Una regola di validazione ha sempre una parte "if". Si può specificare tale parte nel modo seguente: iftrue() ifstring() ifnull() ifarray() ifinarray() ifnotinarray() always() Una regola di validazione richiede anche una parte "then": then() thenemptyarray() theninvalid() thenunset() Di solito, "then" è una closure. Il suo valore di ritorno sarà usato come nuovo valore del nodo, al posto del valore originale del nodo. Processare i valori di configurazione La classe Processor usa l'albero, costruito usando TreeBuilder 0, per processare molteplici array di valori di configurazione da fondere. Se un valore non è del tipo atteso, è obbligatorio e non ancora definito oppure non può essere validato in altri modi, sarà lanciata un'eccezione. Altrimenti, il risultato è un array pulito di valori di configurazione: Listing - use Symfony\Component\Yaml\Yaml; use Symfony\Component\Config\Definition\Processor; generated on November, 0 Chapter : Definire e processare valori di configurazione

32 0 use Acme\DatabaseConfiguration; $config = Yaml::parse( DIR.'/src/Matthias/config/config.yml'); $config = Yaml::parse( DIR.'/src/Matthias/config/config_extra.yml'); $configs = array($config, $config); $processor = new Processor(); $configuration = new DatabaseConfiguration(); $processedconfiguration = $processor->processconfiguration( $configuration, $configs ); generated on November, 0 Chapter : Definire e processare valori di configurazione

33 Chapter Il componente Console Il componente Console semplifica la creazione di eleganti e testabili comandi da terminale. Symfony viene distribuito con un componente Console, che permette di creare comandi da terminale. I comandi da terminale possono essere utilizzati per qualsiasi lavoro ripetivo, come i lavori di cron, importazioni o lavori batch. Installazione Il componente può essere installato in due modi: Installandolo tramite Composer (symfony/console su Packagist ); Utilizzando il repository Git ufficiale ( ). Windows non supporta i colori ANSI in modo predefinito, quindi il componente Console individua e disabilita i colori quando Windows non dà supporto. Tuttavia, se Windows non è configurato con un driver ANSI e i propri comandi di console invocano altri scipt che emetttono sequenze di colori ANSI, saranno mostrati come sequenze di caratteri grezzi. Per abilitare il supporto ai colori ANSI su Windows, si può installare ANSICON. Creazione di comandi di base Per creare un comando che porga il saluto dal terminale, creare il file SalutaCommand.php, contenente il seguente codice: Listing generated on November, 0 Chapter : Il componente Console

34 namespace Acme\DemoBundle\Command; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputArgument; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Input\InputOption; use Symfony\Component\Console\Output\OutputInterface; class SalutaCommand extends Command protected function configure() $this ->setname('demo:saluta') ->setdescription('saluta qualcuno') ->addargument( 'nome', InputArgument::OPTIONAL, 'Chi vuoi salutare?' ) ->addoption( 'urla', null, InputOption::VALUE_NONE, 'Se impostato, il saluto verrà urlato con caratteri maiuscoli' ) ; protected function execute(inputinterface $input, OutputInterface $output) $nome = $input->getargument('nome'); if ($nome) $testo = 'Ciao '.$nome; else $testo = 'Ciao'; if ($input->getoption('urla')) $testo = strtoupper($testo); $output->writeln($testo); Occorre anche creare il file da eseguire in linea di comando, che crea una Application e vi aggiunge comandi: Listing - #!/usr/bin/env php <?php // app/console use Acme\DemoBundle\Command\GreetCommand; use Symfony\Component\Console\Application; $application = new Application(); generated on November, 0 Chapter : Il componente Console

35 0 $application->add(new GreetCommand); $application->run(); È possibile provare il programma nel modo seguente Listing - app/console demo:saluta Fabien Il comando scriverà, nel terminale, quello che segue: Listing - Ciao Fabien È anche possibile usare l'opzione --urla per stampare il saluto in lettere maiuscole: Listing - app/console demo:saluta Fabien --urla Il cui risultato sarà: Listing - CIAO FABIEN Colorare l'output È possibile inserire il testo da stampare, all'interno di speciali tag per colorare l'output. Ad esempio: Listing - 0 // testo verde $output->writeln('<info>pippo</info>'); // testo giallo $output->writeln('<comment>pippo</comment>'); // testo nero su sfondo ciano $output->writeln('<question>pippo</question>'); // testo nero su sfondo rosso $output->writeln('<error>pippo</error>'); Si può definire un proprio stile, usando la classe OutputFormatterStyle : Listing - use Symfony\Component\Console\Formatter\OutputFormatterStyle; $style = new OutputFormatterStyle('red', 'yellow', array('bold', 'blink')); $output->getformatter()->setstyle('fire', $style); $output->writeln('<fire>foo</fire>'); I colori di sfondo e di testo disponibili sono: black, red, green, yellow, blue, magenta, cyan e white. Le opzioni disponibili sono: bold, underscore, blink, reverse e conceal. Si possono anche impostare colori e opzioni dentro il tag: Listing - // testo verde $output->writeln('<fg=green>pippo</fg=green>');. generated on November, 0 Chapter : Il componente Console

36 // testo nero su sfondo ciano $output->writeln('<fg=black;bg=cyan>pippo</fg=black;bg=cyan>'); // testo grassetto su sfondo giallo $output->writeln('<bg=yellow;options=bold>pippo</bg=yellow;options=bold>'); Livelli di verbosità New in version.: Le costanti VERBOSITY_VERY_VERBOSE e VERBOSITY_DEBUG sono state introdotte nella versione. La console dispone di tre livelli di verbosità. Tali livelli sono definiti in OutputInterface : Opzione OutputInterface::VERBOSITY_QUIET OutputInterface::VERBOSITY_NORMAL OutputInterface::VERBOSITY_VERBOSE OutputInterface::VERBOSITY_VERY_VERBOSE OutputInterface::VERBOSITY_DEBUG Valore Nessun messaggio in output Livello predefinito di verbosità Verbosità maggiore Messaggi informativi non essenziali Messaggi di debug Si può specificare il livello quieto di verbosità con l'opzione --quiet o -q. L'opzione --verbose o -v si usa quando si vuole un livello di verbosità maggiore. Se si usa il livello VERBOSITY_VERBOSE, viene mostrato lo stacktrace completo delle eccezioni. È anche possibile mostrare un messaggio in un comando solo per uno specifico livello di verbosità. Per esempio: Listing -0 if (OutputInterface::VERBOSITY_VERBOSE <= $output->getverbosity()) $output->writeln(...); New in version.: I metodi isquiet(), isverbose(), isveryverbose() e isdebug() sono stati introdotti in Symfony. Ci sono anche metodi più semantici da usare, per testare ciascun livello di verbosità: Listing generated on November, 0 Chapter : Il componente Console

37 0 if ($output->isquiet()) if ($output->isverbose()) if ($output->isveryverbose()) if ($output->isdebug()) Quando si usa il livello quieto, viene soppresso ogni output, poiché il metodo write() 0 esce senza stampare nulla. MonologBridge fornisce una classe ConsoleHandler, che consente di mostrare messaggi sulla console. Questo è un modo più pulito rispetto a inserire le chiamate di output all'interno di condizioni. Per un esempio di utilizzo nel framework Symfony, vedere Configurare Monolog per mostrare messaggi di console. Utilizzo dei parametri nei comandi La parte più interessante dei comandi è data dalla possibilità di mettere a disposizione parametri e opzioni. I parametri sono delle stringhe, separate da spazi, che seguono il nome stesso del comando. Devono essere inseriti in un ordine preciso e possono essere opzionali o obbligatori. Ad esempio, per aggiungere un parametro opzionale cognome al precedente comando e rendere il parametro nome obbligatorio, si dovrà scrivere: Listing - 0 $this ->addargument( 'nome', InputArgument::REQUIRED, 'Chi vuoi salutare?' ) ->addargument( 'cognome', InputArgument::OPTIONAL, 'Il tuo cognome?' ) A questo punto si può accedere al parametro cognome dal codice: Listing - if ($cognome = $input->getargument('cognome')) $testo.= ' '.$cognome; generated on November, 0 Chapter : Il componente Console

38 Il comando potrà essere utilizzato in uno qualsiasi dei seguenti modi: Listing - $ app/console demo:saluta Fabien $ app/console demo:saluta Fabien Potencier È anche possibile consentire una lista di valori a un parametro (si immagini di voler salutare tutti gli amici). Lo si deve fare alla fine della lista dei parametri: Listing - $this ->addargument( 'nomi', InputArgument::IS_ARRAY, 'Chi vuoi salutare (separare i nomi con uno spazio)?' ); In questo modo, si possono specificare più nomi: Listing - $ app/console demo:saluta Fabien Ryan Bernhard Si può accedere al parametro nmoi come un array: Listing - if ($nomi = $input->getargument('nomi')) $testo.= ' '.implode(', ', $nomi); Ci sono tre varianti di parametro utilizzabili: Modalità InputArgument::REQUIRED InputArgument::OPTIONAL InputArgument::IS_ARRAY Valore Il parametro è obbligatorio Il parametro è facoltativo, può essere omesso Il parametro può contenere un numero indefinito di parametri e deve essere usato alla fine della lista dei parametri Si può combinare IS_ARRAY con REQUIRED e OPTIONAL, per esempio: Listing - $this ->addargument( 'nomi', InputArgument::IS_ARRAY InputArgument::REQUIRED, 'Chi vuoi salutare (separare i nomi con uno spazio)?' ); Utilizzo delle opzioni nei comandi Diversamente dagli argomenti, le opzioni non sono ordinate (cioè possono essere specificate in qualsiasi ordine) e sono identificate dal doppio trattino (come in --urla; è anche possibile dichiarare una scorciatoia a singola lettera preceduta da un solo trattino come in -u). Le opzioni sono sempre opzionali e possono accettare valori (come in dir=src) o essere semplici indicatori booleani senza alcuna assegnazione (come in urla). generated on November, 0 Chapter : Il componente Console

39 È anche possibile fare in modo che un'opzione possa opzionalmente accettare un valore (ad esempio si potrebbe avere --urla o --urla=forte). Le opzioni possono anche essere configurate per accettare array di valori. Ad esempio, per specificare il numero di volte in cui il messaggio di saluto sarà stampato, si può aggiungere la seguente opzione: Listing - $this ->addoption( 'ripetizioni', null, InputOption::VALUE_REQUIRED, 'Quante volte dovrà essere stampato il messaggio?', ); Ora è possibile usare l'opzione per stampare più volte il messaggio: Listing -0 for ($i = 0; $i < $input->getoption('ripetizioni'); $i++) $output->writeln($testo); In questo modo, quando si esegue il comando, sarà possibile specificare, opzionalmente, l'impostazione --ripetizioni: Listing - $ app/console demo:saluta Fabien $ app/console demo:saluta Fabien --ripetizioni= Nel primo esempio, il saluto verrà stampata una sola volta, visto che ripetizioni è vuoto e il suo valore predefinito è (l'ultimo argomento di addoption). Nel secondo esempio, il saluto verrà stampato volte. Ricordiamo che le opzioni non devono essere specificate in un ordina predefinito. Perciò, entrambi i seguenti esempi funzioneranno correttamente: Listing - $ app/console demo:saluta Fabien --ripetizioni= --urla $ app/console demo:saluta Fabien --urla --ripetizioni= Ci sono possibili varianti per le opzioni: Opzione Valore InputOption::VALUE_IS_ARRAY Questa opzione accetta valori multipli (p.e. --dir=/pippo -- dir=/pluto) InputOption::VALUE_NONE Non accettare alcun valore per questa opzione (come in -- urla) InputOption::VALUE_REQUIRED InputOption::VALUE_OPTIONAL Il valore è obbligatorio (come in ripetizioni=), l'opzione stessa è comunque facoltativa L'opzione può avere un valore o meno (p.e. urla o urla=forte) È possibile combinare VALUE_IS_ARRAY con VALUE_REQUIRED o con VALUE_OPTIONAL nel seguente modo: generated on November, 0 Chapter : Il componente Console