Development

Documentation/it_IT/book/1.0/05-Configuring-Symfony

You must first sign up to be able to contribute.

Version 6 (modified by giosan, 10 years ago)
--

Capitolo 5 - Configurare symfony

Per essere semplice da usare, symfony definisce alcune convenzioni, che devono soddisfare i requisiti più comuni nello sviluppo web senza bisogno di modifiche. Comunque, utilizzando un insieme di semplici e potenti file di configurazione, è possibile personalizzare il modo in cui il framework e la tua applicazione interagiscono fra loro. Con questi file di configurazione, potrai anche aggiungere parametri speciali alla tua applicazione.

Questo capitolo spiega come funziona la configurazione del sistema:

  • La configurazione di symfony è memorizzaata in file scritti in YAML, anche se è sempre possibile scegliere un altro formato.
  • Nella struttura di cartelle del progetto, i file di configurazione si trovano ai livelli progetto, applicazione e modulo.
  • Puoi definire diversi insiemi di settaggi; in symfony, un insieme di configurazioni è chiamato ambiente.
  • I valori definiti nei file di configurazione sono disponibili al codice PHP della tua applicazione.
  • Inoltre, symfony permette l'utilizzo di PHP all'interno dei file di configurazioni, per renderli ancora piu' flessibili.

Il sistema di configurazione

A parte lo scopo, la maggior parte delle applicazioni web condivide un insieme di caratteristiche comuni. Ad esempio, qualche sezione puo' avere accesso ristretto ad un certo insieme di utenti, oppure le pagine possono essere decorate da un layout, o ancora la possibilita' di avere le form gia' riempite dopo una validazione fallita. Un framework definisce una struttura per simulare queste caratteristiche, e gli sviluppatori possono ulteriormente modificarle cambiando i file di configurazione. Questa strategia fa risparmiare molto tempo durante lo sviluppo, dato che molti cambiamenti non necessitano di alcuna linea di codice, anche se ce n'e' molto dietro. Questo sistema e' anche molto efficiente, perche' assicura che queste informazioni siano reperibili sempre in un punto unico e facile da trovare.

Questo approccio ha però due seri svantaggi:

  • Gli sviluppatori di solito finiscono per scrivere complessi file XML senza fine.
  • In un'architettura PHP, ogni richiesta necessita di più tempo per essere eseguita.

Tenendo conto di questi svantaggi, symfony utilizza file di configurazione solo dove sono veramente necessari. L'ambizione del sistema di configurazione di symfony è di essere:

  • Potente: ogni aspetto che possa essere gestito tramite file di configurazione lo e' veramente.
  • Semplice: diversi parametri di configurazione non sono mostrati in applicazioni normali, in quanto raramente necessitano di essere modificati.
  • Facile: gli sviluppatori troveranno facile leggere, creare e modificare file di configurazione.
  • Personalizzabile: il linguaggio di configurazione di default e' YAML, ma puo' essere INI, XML, o qualsiasi altro formato lo sviluppatore preferisca.
  • Veloce: i file di configurazione non vengono processati dall'applicazione ma dal sistema di configurazione, che li compila velocemente in parti di codice PHP sul server.

Sintassi YAML e convenzioni di symfony

Per la propria configurazione, symfony utilizza il formato YAML, invece dei piu' tradizionali INI e XML. YAML mostra la struttura tramite indentazione ed e' veloce da scrivere. I vantaggi e le regole di base sono state mostrate nel Capitolo 1. Comunque, devi tenere a mente qualche convenzione quando vuoi scrivere file di YAML. Questa sezione mostra diverse convenzioni tra le piu' importanti. Per approfondimenti visita il sito web di YAML (http://www.yaml.org/).

Prima di tutto non sono ammessi caratteri di tabulazione in YAML; occorre usare spazi bianchi. I parser YAML non capiscono le tabulazioni, per cui utilizza spazi bianchi per l'indentazione (la convenzione in symfony e' di due spazi bianchi), come mostrato nel Listato 5-1.

Listato 5-1 - YAML vieta l'utilizzo delle tabulazioni

# Never use tabs
all:
-> mail:
-> -> webmaster:  webmaster@example.com

# Use blanks instead
all:
  mail:
    webmaster: webmaster@example.com

Se i tuoi parametri sono stringhe che cominciano o finiscono con spazi vuoti, incapsula il valore tra singoli apici. Se una stringa contiene caratteri particolari, incapsula anche quella tra singoli apici, come mostrato nel Listato 5-2.

Listato 5-2 - Stringhe non standard dovrebbero essere incapsulate tra singoli apici

error1: This field is compulsory
error2: '  This field is compulsory  '
error3: 'Don''t leave this field blank'   # Single quotes must be doubled

Puoi definire stringhe lunghe in più righe, ed anche stringhe con più di una linea, con gli header speciali di stringa (> e |) più una indentazione addizionale. Il Listato 5-3 illustra questa convenzione.

Listato 5-3 - Definizione di stringhe lunghe e su più righe

# Folded style, introduced by >
# Each line break is folded to a space
# Makes YAML more readable
accomplishment: >
  Mark set a major league
  home run record in 1998.

# Literal style, introduced by |
# All line breaks count
# Indentation doesn't appear in the resulting string
stats: |
  65 Home Runs
  0.278 Batting Average

Per definire un valore come array, racchiudi gli elementi tra parentesi quadre, oppure usa la sintassi estesa con i trattini, come mostrato nel Listato 5-4.

Listato 5-4 - Sintassi di array in YAML

# Shorthand syntax for arrays
players: [ Mark McGwire, Sammy Sosa, Ken Griffey ]

# Expanded syntax for arrays
players:
  - Mark McGwire
  - Sammy Sosa
  - Ken Griffey

Per definire un valore come array associativo, o hash, racchiudi gli elementi tra parentesi graffe e inserisci sempre tra la chiave ed il valore. Puoi anche utilizzare la sintassi estesa, aggiungendo indentazione e ritorno a capo per ogni chiave, come mostrato nel Listato 5-5.

Listato 5-5 - Array associativi in YAML

# Incorrect syntax, blanks are missing after the colon
mail: {webmaster:webmaster@example.com,contact:contact@example.com}

# Correct shorthand syntax for associative arrays
mail: { webmaster: webmaster@example.com, contact: contact@example.com }

# Expanded syntax for associative arrays
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com

Per assegnare un booleano, utilizza 1 o true per un valore positivo, 0 o false per uno negativo. Il Listato 5-6 mostra i possibili valori booleani.

Listato 5-6 - Sintassi YAML per valori booleani

true_values:   [ on, 1, true ]
false_values:  [ off, 0, false ]

Non esitare ad aggiungere commenti (che devono cominciare con il cancelletto #) e spazi aggiuntivi, per rendere ancora più leggibili tuoi file YAML, come mostrato nel Listato 5-7.

Listato 5-7 - Sintassi dei commenti in YAML

# This is a comment line
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com
  admin:     admin@example.com   # extra spaces allow nice alignment of values

In qualche file di configurazione di symfony, ti capiterà di trovare delle linee che cominciano con un cancelletto (per cui ignorate dal parser YAML) e che assomigliano a normali linee di settaggi. Questa è una convenzione di symfony: la configurazione di default, ereditata da altri file YAML che si trovano nel core, è ripetuta in linee commentate nella tua applicazione per pura informazione. Se vuoi cambiare uno di tali parametri, devi innanzitutto decommentare la linea, come mostrato nel Listato 5-8.

Listato 5-8 - La configurazione di default è mostrata commentata

# The cache is off by default
settings:
# cache: off

# If you want to change this setting, uncomment the line first
settings:
  cache: on

Qualche volta symfony raggruppa le definizioni dei parametri in categorie. Tutti i settaggi relativi ad una data categoria appaiono indentati sotto il suo header. Strutturare lunghe liste di coppie chiave: valore raggruppandole in categorie aumenta la leggibilità della configurazione. Gli header di categoria cominciano con un punto (.). Il Listato 5-9 mostra un esempio di categorie.

Listato 5-9 - Gli header di categoria sembrano chiavi, ma cominciano un un punto

all:
  .general:
    tax:        19.6

  mail:
    webmaster:  webmaster@example.com

In questo esempio, mail è una chiave e general è solo un header di categoria. Tutto funziona come se l'header non esistesse, come mostrato nel Listato 5-10. Il parametro tax è effettivamente un figlio di della chiave all.

Listato 5-10 - Gli header di categoria esistono solo per una questione di leggibilità, e sono in effetti ignorati

all:
  tax:          19.6

  mail:
    webmaster:  webmaster@example.com

SIDEBAR E se non ti piace YAML

YAML è solo un'interfaccia per definire settaggi utilizzati da PHP, per cui le configurazioni YAML finiscono per essere trasformate in PHP. Dopo aver navigato la tua applicazione, controllane la configurazione in cache (ad esempio in cache/myapp/dev/config/). Vedrai file PHP corrispondenti alle configurazioni YAML. Imparerai di più sulla cache di configurazione più avanti in questo capitolo.

La buona notizia è che se non vuoi usare YAML, puoi fare la stessa cosa a mano in PHP o con altri formati (come XML o INI). Nel corso di questo libro, incontrerai modi alternativi per definire configurazioni senza YAML, ed imparerai anche come sostituire il gestore di configurazioni di symfony (nel Capitolo 19). Se le usi largamente, questi trucchi ti permetteranno di bypassare i file di configurazione o definire il tuo personale formato di configurazione.

Aiuto, un file YAML ha ucciso la mia applicazione!

I file YAML sono parsati in array o hash PHP, quindi i valori sono usati in varie parti dell'applicazione per modificare il comportamento delle viste, del controller o del modello. Molte volte, quando c'è un errore in un file YAML, esso non viene riconosciuto fino a che il valore non è effettivamente necessario. Ancora più spesso, l'eccezione che ne viene generata non si riferisce chiaramente al file YAML.

Se la tua applicazione smette improvvisamente di funzionare dopo un cambio di configurazione, devi controllare di non aver fatto qualcuno dei più comuni errori di disattenzione con YAML:

  • Ti manca uno spazio tra una chiave ed il suo valore:

    key1:value1      # Manca uno spazio bianco dopo :
    
  • Le chiavi in una sequenza non sono indentate nella stessa maniera:

    all:
      key1:  value1
       key2: value2  # Indentazione sbagliata
      key3:  value3
    
  • C'è un carattere riservato in una chiave o un valore, senza delimitatori di stringa:

    message: tell him: go way    # :, [, ], { e } sono riservati in YAML
    message: 'tell him: go way'  # Sintassi corretta
    
  • Stai modificando una linea commentata:

    # key: value     # Questa linea è ignorata perchè comincia con #
    
  • Imposti dei valori con la stessa chiave allo stesso livello:

    key1: value1
    key2: value2
    key1: value3     # key1 è definita due volte, il valore è l'ultimo inserito
    
  • Pensi che un valore sia un tipo speciale, mentre resta una stringa fino a che non sarà convertita:

    income: 12,345   # Ancora una stringa, fino a che non sarà convertita
    

Riepilogo dei file di configurazione

La configurazione è suddivisa in file, per oggetto. Questi file contengono definizioni di parametri, o settaggi. Alcuni di tali parametri possono essere overridati a diversi livelli (progetto, applicazione e modulo); altri specificatamente a certi livelli. I prossimi paragrafi prenderanno in esame le configurazioni relativamente alle loro finalità principali, mentre il Capitolo 19 esaminerà configurazioni avanzate.

Configurazione di progetto

Ci sono per default pochi file di configurazione per progetto. Di seguito quelli che si trovano nella cartella myproject/config/:

  • config.php: Questo è assolutamente il primo file eseguito per ogni richiesta o comando. Contiene i percorsi ai file del framework, e può essere cambiato per usare un'installazione diversa. Se aggiungi qualche define al fine di questo file, le costanti saranno accessibili da qualsiasi applicazione del progetto. Vedi il Capitolo 19 per usi avanzati di questo file.
  • databases.yml: Qui è dove definisci l'accesso e la connessione al database (host, login, password, nome del database, e così via). Imparerai di più su questo nel Capitolo 8. Può essere overridato a livello applicazione.
  • properties.ini: Questo file gestisce parametri utilizzati a linea di comando, inclusi il nome del progetto ed i settaggi di connessione a server distanti. Vedi il Capitolo 16 per un sommario delle caratteristiche di utilizzo di questo file.
  • rsync_exclude.txt: Questo file specifica quali cartelle devono essere escluse dalla sincronizzazione tra server. E' discusso nel Capitolo 16.
  • schema.yml e propel.ini: Si tratta di file di configurazione per l'accesso ai dati usati da Propel (il livello ORM di symfony). Sono utilizzati per far funzionare le librerie Propel con le classi di symfony ed i dati del tuo progetto. schema.yml contiene una rappresentazione del modello relazionale del progetto. propel.ini è generato automaticamente, per cui probabilmente non avrai bisogno di modificarlo. Se non usi Propel, questi file non sono necessari. Il Capitolo 8 approfondirà il loro utilizzo.

Questi file sono usati per lo più da componenti esterni o dalla linea di comando, o devono essere processati prima che il framework carichi il programma di parsing YAML. Ecco perché alcuni di essi non usano il formato YAML.

Configurazione dell'applicazione

La maggior parte della configurazione è occupata dall'applicazione. E' definita nel front controller (nella cartella web/) per costanti principali, in file YAML nella cartella config/ dell'applicazione, in i18n/ per l'internazionalizzazione, ed infine nei file del framework per una invisibile (ma sempre utile) configurazione addizionale dell'applicazione.

Configurazione del front controller

La prima configurazione dell'applicazione in assoluto si trova nel front controller; si tratta del primo script eseguito da una richiesta. Dai un'occhiata al codice di web/index.php mostrato nel Listato 5-11.

Listato 5-11 - Il front controller di default

[php]
<?php

define('SF_ROOT_DIR',    dirname(__FILE__).'/..');
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       true);

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

sfContext::getInstance()->getController()->dispatch();

Dopo aver definito il nome dell'applicazione (myapp) e l'ambiente (prod), la configurazione generale e' chiamata prima del dispatching. Per cui qualche costante utile viene definita qui:

  • SF_ROOT_DIR: La cartella di root del progetto (di norma dovrebbe rimanere come e' di default, a meno che tu non voglia cambiare la struttura delle cartelle).
  • SF_APP: Nome dell'applicazione nel progetto. Necessario per computare i percorsi dei file.
  • SF_ENVIRONMENT: Nome dell'ambiente ({{{prod}}}, {{{dev}}}, o qualsiasi altro ambiente specifico che tu creerai ad hoc per il tuo progetto). Determinerà quali sono i settaggi di configurazione da utilizzare. Gli ambienti sono spiegati più avanti in questo capitolo.
  • SF_DEBUG: Attivazione della modalità di debug (vedere il Capitolo 16 per i dettagli).

Se vuoi cambiare uno di questi valori, probabilmente avrai bisogno di un front controller addizionale. Il prossimo capitolo spiegherà più nel dettaglio i front controller e come crearne di nuovi.

SIDEBAR La directory di root può essere ovunque

Esclusivamente i file e directory che stanno sotto la web root (in symfony la cartella web/) sono visibili dall'esterno. Gli script del front controller, le immagini, i fogli di stile e i JavaScript sono pubblici. Tutti i restanti file devono essere al di fuori della web root, il che significa che potrebbero essere in qualunque altra posizione.

I file non pubblici sono acceduti da front controller dalla cartella SF_ROOT_DIR. Classicamente, la cartella di root è un livello prima di web/; però puoi scegliere una struttura completamente diversa. Immagina che la tua struttura principale sia composta da due cartelle, una pubblica ed una privata:

symfony/    # Private area
  apps/
  batch/
  cache/
  ...
www/        # Public area
  images/
  css/
  js/
  index.php

In questo caso, la root directory è symfony/. Così il front controller index.php per funzionare ha bisogno semplicemente di definire SF_ROOT_DIR come segue:

define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony');

Il Capitolo 19 fornirà più dettagli su come far funzionare symfony con una struttura di cartelle specifica.

Configurazione dell'applicazione principale

La configurazione dell'applicazione principale è memorizzata in file che si trovano nella cartella myproject/apps/myapp/config/:

  • app.yml: Questo file dovrebbe contenere configurazioni specifiche all'applicazione; ad esempio variabili globali che definiscono business logic o applicativa specifiche, che non hanno bisogno di essere memorizzate nel db. Tasse, costi di spedizione, indirizzi e-mail sono memorizzati spesso in questo file, che di default è vuoto.
  • config.php: si occupa del bootstrap dell'applicazione, quindi fa tutte le inizializzazioni di base necessarie all'applicazione per partire. Qui è dove puoi definire una struttura di cartelle particolare, oppure delle costanti specifiche (il Capitolo 19 ne fornirà maggiori dettagli). Comincia includendo il config.php di progetto.
  • factories.yml: symfony definisce le proprie classi per gestire le viste, la richiesta, la risposta, le sessioni e così via. Se invece vuoi utilizzare le tue classi personali, questo file è i posto in cui definirle (maggiori informazioni nel Capitolo 19).
  • filters.yml: I filtri sono porzioni di codice eseguiti per ogni richiesta. Qui è dove definisci quali filtri devono essere processati, e può essere overridato in ogni modulo. Il Capitolo 6 fornisce maggiori dettagli sui filtri.
  • logging.yml: Questo file definisce quale livello di dettaglio deve essere utilizzato nei log, per aiutarti a gestire e debuggare la tua applicazione. L'utilizzo di questo file è approfondito nel Capitolo 16.
  • routing.yml: Le regole di routing, che permettono di trasformare una URL illeggibile in una più "intelligente", sono definite in questo file. Per nuove applicazioni, esistono poche regole di default. Il Capitolo 9 è dedicato ai link e al routing.
  • settings.yml: I settaggi principali di un'applicazione symfony sono definiti in questo file. Qui è dove specifichi se la tua applicazione è internazionalizzata, qual'è la lingua di default, il timeout per le richieste e se la cache è attiva o meno. Cambiando una linea di questo file puoi "spegnere" la tua applicazione, per poterla aggiornare o manutenere. I settaggi più comuni ed il loro utilizzo sono approfonditi nel Capitolo 19.
  • view.yml: La struttura della vista di default (nome del layout, titolo, meta dati; fogli di stile e JavaScript da includere; content-type di default e così via) è definita in questo file. Il Capitolo 7 approfondirà questo file. Questi settaggi possono essere overridati in ogni modulo.

Configurazione dell'internazionalizzazione

Applicazioni internazionalizzate possono mostrare le pagine in diverse lingue. Questo richiede una configurazione specifica. Ci sono due file da configurare per l'internazionalizzazione:

  • i18n.yml della cartella config/ dell'applicazione: Questo file definisce settaggi generali di traduzione, come ad esempio la cultura di default per la traduzione, se le traduzioni sono in un file o nel database ed il loro formato.
  • File di traduzione nella cartella i18n/ dell'applicazione: Questi sono fondamentalmente dei dizionari, che forniscono la traduzione delle parole utilizzate nelle template dell'applicazione in modo che le pagine mostrino testo tradotto quando un utente cambia la lingua.

Nota che l'attivazione delle feature i18n è impostata nel file settings.yml. Approfondimenti a tale proposito nel Capitolo 13.

Configurazioni addizionali dell'applicazione

Un secondo insieme di file di configurazione è posizionato nella cartella di installazione di symfony (in $sf_symfony_data_dir/config/) e non figura nella cartella di configurazione delle tue applicazioni. Tali settaggi sono default che raramente hanno bisogno di essere modificati, oppure che sono globali a tutti i progetti. Comunque, se tu avessi bisogno di modificarli, crea un file vuoto nella cartella myproject/apps/myapp/config/ e fai un override dei parametri che vuoi cambiare. I settaggi definiti nell'applicazione hanno sempre la precedenza rispetto a quelli definiti nel framework. Di seguito i file di configurazione nella cartella config/ dell'installazione di symfony:

  • autoload.yml: Questo file contiene i settaggi della funzione di autoloading. Tale funzione ti esonera dall'includere classi personalizzate se esse si trovano in una cartella specifica. Questa funzione e' descritta nel Capitolo 19.
  • constants.php: Questo file contiene la struttura di default dei file. Per poter fare l'override dei settaggi di questo file, utilizza config.php dell'applicazione, come spiegato nel Capitolo 19.
  • core_compile.yml and bootstrap_compile.yml: Queste sono liste di classi da includere per far partire un'applicazione (bootstrap_compile.yml) e per processare una richiesta (core_compile.yml). Questi file sono effettivamente concatenati in un file PHP ottimizzato senza commenti, che velocizzera' l'esecuzione minimizzando le operazioni di accesso (e' caricato un solo file invece di quaranta per ogni richiesta). Questo risulta specialmente utile se non utilizzi un acceleratore PHP. Le tecniche di ottimizzazione sono descritte nel Capitolo 18.
  • config_handlers.yml: Qui e' dove puoi aggiungere o modificare i gestori usati per processare ogni file di configurazione. Il Capitolo 19 fornisce maggiori dettagli in merito.
  • php.yml: Questo file controlla che le variabili in php.ini siano definite nel modo giusto e ti permette di farne l'override, se ne avessi bisogno. Controlla il Capitolo 19 per maggiori dettagli.

Configurazione del modulo

Per default un modulo non ha una configurazione specifica. Ma, qualora necessario, puoi fare l'override di qualche settaggio del livello applicazione per un dato modulo. Ad esempio, potresti farlo per cambiare la descrizione HTML di tutte le azioni di un modulo, o per includere un file JavaScript specifico. Puoi anche scegliere di aggiungere nuovi parametri esclusivamente per un dato modulo al fine di preservare l'incapsulazione.

Come puoi immaginare, i settaggi di un modulo devono essere nella cartella myproject/apps/myapp/modules/mymodule/config/. I file interessati sono i seguenti:

  • generator.yml: Per i moduli generati secondo una tabella di database (scaffolding e amministrazione), questo file descrive il modo in cui le righe e campi devono essere visualizzati, e quali tipi di interazioni sono proposti all'utente (filtri, ordinamenti, pulsanti e cosi' via). Il Capitolo 14 approfondira' l'argomento.
  • module.yml: Questo file contiene parametri specifici ad un modulo (equivalente a app.yml, ma a livello modulo) e la configurazione dell'azione. Il Capitolo 6 fornisce maggiori dettagli in merito.
  • security.yml: Questo file permette di impostare restrizioni per le azioni. Qui e' dove puoi impostare il fatto che una certa pagina sia visibile solo agli utenti registrati, oppure ad un sottoinsieme di utenti con permessi speciali. Il Capitolo 6 fornisce maggiori dettagli in merito.
  • view.yml: Questo file contiene le configurazioni delle viste di una o tutte le azioni di un modulo. Permette l'override di view.yml del livello applicazione, ed e' descritto nel Capitolo 7.
  • File per la validazione: Sebbene situati all'interno della cartella validate/ invece di config/, i file YAML per la validazione, utilizzati per controllare i dati inseriti nelle form, sono anche file di configurazione per i moduli. Imparerai ad usarli nel Capitolo 10.

La maggior parte dei file di configurazione dei moduli offrono la possibilita' di definire parametri per tutte le viste o tutte le azioni di un modulo, oppure per un loro sottoinsieme.

SIDEBAR Troppi file?

Ti potresti sentire travolto dal numero di file di configurazione presenti nell'applicazione. Ma ricorda:

La maggior parte delle volte non avrai bisogno di cambiare la configurazione, perche' le convenzioni stabilite per default soddisfano i requisiti piu' comuni. Ogni file di configurazione corrisponde ad una particolare funzione, ed il prossimo capitolo le affrontera' dettagliatamente il loro utilizzo una alla volta. Quando ti focalizzi su di un singlo file, puoi capire chiaramente cosa fa e come e' organizzato. Per lo sviluppo web professionale, la configurazione di default e' spesso non completamente adatta. I file di configurazione permettono di modificare facilmente i meccanismi di symfony senza scrivere codice. Immagina l'ammontare di codice PHP necessario per raggiungere lo stesso livello di controllo. Se tutti parametri fossero all'interno di un unico file, non solo esso sarebbe illeggibile, ma non ci potrebbe nemmeno essere la possibilita' di fare override di parametri a divresi livelli (v. la sezione "Configurazione a cascata" piu' avanti in questo capitolo).

Il sistema di configurazione e' uno dei punti di forza di symfony, peche' lo rende utilizzabile per qualsiasi tipo di applicazione web, e non solamente per quelle per le quali era stato pensato inizialmente.

Environments

Durante lo sviluppo di un'applicazione, avrai probabilmente bisogno di mantenere in parallelo diversi insiemi di configurazioni. Ad esempio avrai bisogno di avere disponibili i settaggi di connessione al tuo database di test per lo sviluppo, e di avere allo stesso tempo quelli reali per la produzione. Per soddisfare tale fabbisogno, symfony offre diversi ambienti.

Cosa è un Environment?

Una applicazione puo' girare in diversi ambienti. Tali ambienti condividono lo stesso codice PHP (a parte il front controller) ma possono avere configurazioni completamente differenti. Per ogni applicazione, symfony fornisce tre ambienti: produzione (prod), test (test) e sviluppo (dev). Sei inoltre libero di aggiungerne quanti ne vuoi.

Quindi, fondamentalmente, ambienti e configurazioni sono sinonimi. Ad esempio, un ambiente di test mettera' nei log sia alert che errori, mentre un prod scrivera' solo gli errori. La cache e' spesso disattivata in ambienti dev, ma attivata in test e prod. Gli ambienti dev e test avranno bisogno di dati di test, memorizzati in un database diverso da quello di produzione. Tutti gli ambienti possono convivere sulla stessa macchina, sebbene di solito un server di produzione ospiti esclusivamente un ambiente prod.

In dev, i settaggi di logging e debugging sono tutti abilitati, dato che la manutenzione in tale ambiente e' piu' importante delle performance. Al contrario, l'ambiente di sviluppo e' ottimizzato per le performance per default. Una buona regola e' quella di navigare sul sito di sviluppo fino a che sei soddisfatto delle funzioni su cui stai lavorando, quindi passare a quello in produzione per verificarne le performance.

L'ambiente test differisce dagli altri due in modi diversi. Interagirai con questo ambiente esclusivamente tramite la linea di comando per finalita' di test funzionali o scripting batch. Conseguentemente, l'ambiente test e' simile a quello di produzione ma non vi si accede navigando. Simula l'utilizzo di cookie ed altri componenti specifici di HTTP.

Per cambiare ambiente nel quale stai navigando l'applicazione, devi semplicemente cambiare il front controller. Sino ad ora hai visto solo l'ambiente di sviluppo, dato che le URL utilizzate negli esempi chiamavano sempre il front controller di sviluppo:

http://localhost/myapp_dev.php/mymodule/index

Se vuoi vedere come l'applicazione reagisce in produzione, puoi invece chiamare il front controller per tale ambiente:

http://localhost/index.php/mymodule/index

Se il tuo web server ha il mod_rewrite abilitato, puoi anche utilizzare le regole di symfony per il rewriting, definite in web/.htaccess. Esse definiscono il front controller di produzione come esecuzione di default e permettono di chiamare URL come:

http://localhost/mymodule/index

SIDEBAR Environments e servers

Non confondere le nozioni di ambiente e server. In symfony, diversi ambienti sono diverse configurazioni, e corrispondono a diversi front controller (gli script che gestiscono le richieste). Server diversi corrispondono a diversi nomi a dominio nelle URL.

http://localhost/myapp_dev.php/mymodule/index
       _________ _____________
        server    environment

Normalmente, gli sviluppatori lavorano alle applicazioni su server di sviluppo, scollegati da Internet e dove le configurazioni possono essere cambiate a piacimento. Quando un'applicazione deve essere pubblicata, i suoi file vengono spostati sul server di sviluppo e resi cosi' pubblici.

Questo significa che diversi ambienti sono disponibili su ogni server. Ad esempio, potresti avere sulla stessa macchina ambiente di produzione e di sviluppo. Comunque, la maggior parte delle volte, sul server di produzione ci dovrebbe essere esclusivamente l'ambiente di produzione, per ovvi motivi.

Per aggiungere un ambiente, non hai bisogno di create una direcotry o usare la symfony CLI. Crea semplicemente un nuovo front controller e cambia il nome dell'ambiente. Questo ambiente erediterà tutte le configurazioni di default più i parametri comuni a tutti gli ambienti. Il prossimo capitolo ti insegnerà come fare questo.

Configurazione a cascata

Gli stessi settaggi possono essere definiti più di una volta, in posti diversi. Ad esempio, potresti volere settare il mime-type delle tue pagine come text/html per tutte le applicazioni tranne per le pagine di un modulo rss, che dovrebbe invece avere un mime-type text/xml. Symfony ti da la possibilità di scrivere il primo settaggio in myapp/config/view.yml ed il secondo in myapp/modules/rss/config/view.yml. Il sistema di configurazione sa che un settaggio definito a livello modulo ha la precedenza rispetto allo stesso definito a livello applicazione.

Infatti, ci sono diversi livelli di configurazione in symfony:

  • Livelli di granularità:
    • Configurazione di default situata nel framework
    • Configurazione globale per l'intero progetto (in myproject/config/)
    • Configurazione locale per un'applicazione del progetto (in myproject/apps/myapp/config/)
    • Configurazione ristretta ad un modulo (in myproject/apps/myapp/modules/mymodule/config/)
  • Livelli ambiente:
    • Specifico ad un ambiente
    • Per tutti gli ambienti

Di tutte le proprietà che possono essere personalizzate, diverse sono dipendenti dall'ambiente. Conseguentemente, diversi file di configurazione YAML sono divisi per ambiente, più una sezione di coda per tutti gli ambienti. Il risultato di una tipica configurazione symfony è mostrato nel Listato 5-12.

Listato 5-12 - Struttura dei file di configurazione di symfony

# Production environment settings
prod:
  ...

# Development environment settings
dev:
  ...

# Test environment settings
test:
  ...

# Custom environment settings
myenv:
  ...

# Settings for all environments
all:
  ...

In più, il framework stesso definisce dei valori di default in file che non sono situati nel tree del progetto, bensì nella cartella $sf_symfony_data_dir/config/ dell'installazione di symfony. Questa configurazione è mostrata nel Listato 5-13, e tali settaggi sono ereditati da tutte le applicazioni.

Listato 5-13 - Configurazione di default, in $sf_symfony_data_dir/config/settings.yml

 # Default settings:
 default:
   default_module:         default
   default_action:         index
   ...

Queste configurazione di default sono ripetute nei files di configurazione di progetti, applicazione e moduli come commenti, come mostrato nel Listato 5-14, così che tu possa conoscere quali sono i parametri di defualt e modificarli.

Listato 5-14 - Configurazione di default, ripetuta per informazione, in myapp/config/settings.yml

#all:
 #  default_module:         default
 #  default_action:         index
 ...

Ciò significa che una proprietà può essere definita diverse volte, e l'effettivo valore è il risultato di una cascata di definizioni. Il valore di un parametro definito in un ambiente specifico ha la precedenza sullo stesso valore definito per tutti gli ambienti, che a sua volta ha la precedenza su quello definito per default. Un parametro definito a livello modulo ha la precedenza sullo stesso definito a livello applicazione, che a sua volta ha la precedenza su quello definito a livello progetto. Tutto ciò è mostrato nella seguente lista di priorità:

  1. Modulo
  2. Applicazione
  3. Progetto
  4. Ambiente specifico
  5. Tutti gli ambienti
  6. Default

La configurazione della cache

Fare il parsing di file YAML e avere a che fare con la cascata di configurazioni comporta un grande carico di lavoro per ogni richiesta. Symfony possiede un meccanismo di cache integrato pensato per accelerare le richieste.

I file di configurazione, in qualsiasi formato, vengono processati da classi speciali, chiamate gestori, che li trasformano in codice PHP processati velocemente. Nell'ambiente di sviluppo, i gestori controllano se ci sono stati cambiamenti nella configurazione ad ogni richiesta, per promuovere l'interattività. Essi fanno il parsing dei file modificati di recente in modo che tu possa vedere un cambiamento in un file YAML immediatamente. Ma nell'ambiente di produzione, questo avviene solo alla prima richiesta, dopodichè il codice PHP processato viene memorizzato in cache per le richieste successive. Le performance sono garantite, dato che ogni richiesta non farà altro che eseguire codice PHP ottimizzato.

Ad esempio, se il file app.yml contenesse:

all:                   # Setting for all environments
  mail:
    webmaster:         webmaster@example.com

allora il file config_app.yml.php, situato nella cartella cache/ del tuo progetto, conterrebbe:

[php]
<?php

sfConfig::add(array(
  'app_mail_webmaster' => 'webmaster@example.com',
));

Come conseguenza, il più delle volte, il framework non fa nemmeno il parsing dei file YAML, ma utilizza solo la cache. In ogni caso, in ambiente di sviluppo, symfony controllerà sistematicamente le date dei file YAML e dei file in cache, riprocessando solo il file che sono stati modificati dall'ultima richiesta.

Questo rappresenta un grande vantaggio rispetto a molti framework PHP, che invece fanno il parsing dei file di configurazione ad ogni richiesta, anche in produzione. Diversamente da Java, PHP non condivide un contesto di esecuzione fra le richieste. Per altri framework PHP, possedere la flessibilità di file XML significa colpire le performance, per poter fare il parsing della configurazione ad ogni richiesta. Questo non è il caso di symfony. Grazie al sistema di cache, il sovraccarico dovuto alla configurazione è molto basso.

C'è un'importante conseguenza di questo meccanismo. Se cambi la configurazione in produzione, devi forzare il sistema a rileggere i file per poter vedere le tue modifiche. Per poter fare questo, basta pulire la cache, rimuovendo tutti i file dalla cartella cache/ oppure richiamando il comando:

> symfony clear-cache

Accedere alla configurazione dal codice

Tutti i file di configurazione sono alla fine trasformati in PHP, e molti dei settaggi che contengono sono utilizzati dal framework senza ulteriori interventi. Comunque, ti potrebbe capitare di dover accedere ad alcuni settaggi direttamente dal tuo codice (in azioni, template, classi e così via). I settaggi definiti in settings.yml, app.yml, module.yml, logging.yml, e i18n.yml sono disponibili attraverso una classe speciale chiamata sfConfig.

la classe sfConfig

Si tratta di un registro dei parametri di configurazione, con un semplice metodo getter utilizzabile da qualunque parte dell'applicazione:

[php]
// Retrieve a setting
parameter = sfConfig::get('param_name', $default_value);

Inoltre è anche possibile definire, o fare un ovveride, di un parametro:

[php]
// Define a setting
sfConfig::set('param_name', $value);

Il nome del parametro è una concatenazione di diversi elementi, separati da underscore, nel seguente ordine:

  • Un prefisso relativo al nome del file di configurazione (sf_ per settings.yml, app_ per app.yml, mod_ per module.yml, sf_i18n_ per i18n.yml, e sf_logging_ per logging.yml)
  • La chiave del genitore, se definita, in minuscolo
  • Il nome della chiave, in minuscolo

L'ambiente non è incluso, dato che il tuo codice PHP avrà accesso unicamente ai valori definiti per l'ambiente in cui è eseguito.

Ad esempio, se tu avessi bisogno di accedere ai parametri definiti in app.yml mostrato nel Listato 5-15, avrai bisogno del codice mostrato nel Listato 5-16.

Listato 5-15 - Un esempio di configurazione di app.yml

all:
  version:        1.5
  .general:
    tax:          19.6
  default_user:
    name:         John Doe
  mail:
    webmaster:    webmaster@example.com
    contact:      contact@example.com
dev:
  mail:
    webmaster:    dummy@example.com
    contact:      dummy@example.com

Listato 5-16 - Recupero di parametri dall'ambiente dev

[php]
echo sfConfig::get('app_version');
 => '1.5'
echo sfConfig::get('app_tax');   // Remember that category headers are ignored
 => '19.6'
echo sfConfig::get('app_default_user_name');
 => 'John Doe'
echo sfConfig::get('app_mail_webmaster');
 => 'dummy@example.com'
echo sfConfig::get('app_mail_contact');
 => 'dummy@example.com'

In tal maniera, i settaggi di configurazione di symfony hanno tutti i vantaggi delle costanti di PHP, ma non gli svantaggi, in quanto i loro valori possono essere modificati.

Tenendo a mente questo concetto, il file settings.yml, nel quale puoi settare i parametri del framework per l'applicazione, è equivalente ad una lista di chiamate sfConfig::set(). Il Listato 5-17 è interpretato come nel Listato 5-18.

Listato 5-17 - Una parte di settings.yml

all:
  .settings:
    available:              on
    path_info_array:        SERVER
    path_info_key:          PATH_INFO
    url_format:             PATH

Listato 5-18 - Ciò che symfony produce quando ne fa il parsing di settings.yml

[php]
sfConfig::add(array(
  'sf_available' => true,
  'sf_path_info_array' => 'SERVER',
  'sf_path_info_key' => 'PATH_INFO',
  'sf_url_format' => 'PATH',
));

Il significato dei parametri del file settings.yml è spiegato nel Capitolo 19.

Settaggi dell'applicazione personalizzati e app.yml

La maggior parte dei settaggi delle funzioni di un'applicazione dovrebbero essere definiti in app.yml, dentro la cartella myproject/apps/myapp/config/. Questo file dipende dall'ambiente e di default vuoto. Imposta in questo file tutti i parametri che vuoi cambiare facilmente, ed usa la classe sfConfig per accedere a tali parametri dal tuo codice. Il Listato 5-19 mostra un esempio.

Listato 5-19 - Un esempio di app.yml per definire operazioni su carta di credito

all:
  creditcards:
    fake:             off
    visa:             on
    americanexpress:  on

dev:
  creditcards:
    fake:             on

Per sapere se una carta di credito è accettata nell'ambiente corrente, controlla il valore di:

[php]
sfConfig::get('app_creditcards_fake');

TIP Ogni qualvolta sei tentato di definire una costante od un parametro nei tuoi script, pensa se non possa essere meglio metterlo nel file app.yml. E' un posto molto conveniente per memorizzare i parametri dell'applicazione.

Quando hai bisogno di parametri personalizzati e diventa difficile utilizzare la sintassi di app.yml, puoi definire una tua sintassi personalizzata. In questo caso, puoi memorizzare la configurazione in un nuovo file, interpretato da un nuovo gestore. Il Capitolo 19 fornisce maggiori informazioni sui gestori di configurazione.

Suggerimenti per ottenere di più dai file di configurazione

C'è qualche trucco ancora da imparare prima di scrivere i tuoi file YAML. Ti servirà per evitare duplicazione della configurazione e per gestire i tuoi file YAML.

Utilizzare costanti nei file YAML

Certi parametri di configurazione si basano sul valore di altri. Per evitare di duplicare i valori, symfony supporta le costanti in YAML. Quando il gestore della configurazione incontra un parametro (accessibile tramite tramite sfConfig::get()) in maiuscolo e racchiuso tra %, esso lo sostituisce con il suo valore effettivo. Il Listato 5-20 ne mostra un esempio.

Listato 5-20 - Utilizzo delle costanti in YAML, esempio da autoload.yml

autoload:
  symfony:
    name:           symfony
    path:           %SF_SYMFONY_LIB_DIR%
    recursive:      on
    exclude:        [vendor]

Il parametro path verrà sostituito con il valore di sfConfig::get('sf_symfony_lib_dir'). Se vuoi che un file di configurazione si basi su di un altro, devi essere certo che quello su cui si basa venga parsato per primo (controlla i sorgenti di symfony per verificare l'ordine in cui i file di configurazione vengono parsati). app.yml è uno degli ultimi file di cui viene fatto il parsing, per cui si può basare su altri.

Utilizzare codice nella configurazione

Potrebbe succedere che la tua configurazione si debba basare su parametri esterni (database od un altro file di configurazione). Per gestire questi casi particolari, viene fatto il parsing dei file di configurazione di symfony da PHP prima che essi vengano passi al parser YAML. Questo significa che i file YAML possono contenere codice PHP, come mostrato nel Listato 5-21.

Listato 5-21 - I file YAML possono contenere codice PHP

all:
  translation:
    format:  <?php echo sfConfig::get('sf_i18n') == true ? 'xliff' : 'none' ?>

Ma fai attenzione al fatto che il parsing di questi file viene eseguito molto presto durante il ciclo di vita di una richiesta, per cui non avrai a tua disposizione i metodi o funzioni di symfony.

CAUTION Nell'ambiente di produzione la configurazione è in cache, per cui il parsing (e l'esecuzione) dei file di configurazione avviene esclusivamente dopo che la cache è stata pulita.

Navigare i tuoi file YAML personali

Ogni qualvolta tu voglia leggere un file YAML direttamente, puoi usare la classe sfYaml. Si tratta di un parser YAML che ne trasforma i file in array associativi di PHP. Il Listato 5-22 presenta un file YAML di esempio, mentre il Listato 5-23 mostra come farne il parsing.

Listato 5-22 - File di esempio test.yml

house:
  family:
    name:     Doe
    parents:  [John, Jane]
    children: [Paul, Mark, Simone]
  address:
    number:   34
    street:   Main Street
    city:     Nowheretown
    zipcode:  12345

Listato 5-23 - Utilizzo della classe sfYaml per trasformare il file precedente in array associativo

[php]
$test = sfYaml::load('/path/to/test.yml');
print_r($test);

Array(
  [house] => Array(
    [family] => Array(
      [name] => Doe
      [parents] => Array(
        [0] => John
        [1] => Jane
      )
      [children] => Array(
        [0] => Paul
        [1] => Mark
        [2] => Simone
      )
    )
    [address] => Array(
      [number] => 34
      [street] => Main Street
      [city] => Nowheretown
      [zipcode] => 12345
    )
  )
)

Riepilogo

Il sistema di configurazione di symfony utilizza il linguaggio YAML per poter essere semplice e leggibile. La capacità di gestire ambienti multipli e di definire insiemi di parametri tramite cascata offre grande versatilità allo sviluppatore. Alcuni dei parametri sono accessibili via codice tramite l'oggetto sfConfig, specialmente quelli specifici dell'applicazione memorizzati nel file app.yml.

E' vero, symfony ha molti file di configurazione, ma questo approccio lo rende molto adattabile. Ricorda che non hai bisogno di annoiarti con essi se non hai bisogno di un alto livello di personalizzazione.