Configurazione di FrameworkBundle (“framework”)

Questo riferimento è ancora provvisorio. Dovrebbe essere accurato, ma non sono pienamente coperte tutte le opzioni.

FrameworkBundle contiene la maggior parte delle funzionalità di base del framework e può essere configurato sotto la chiave framework nella configurazione di un’applicazione. Include impostazioni relative a sessioni, traduzione, form, validazione, rotte e altro.

Configurazione

secret

tipo: stringa obbligatorio

Una stringa che dovrebbe essere univoca nella propria applicazione. In pratica, è usata per generare il token anti-CSRF, ma potrebbe essere usata in ogni altro contesto in cui è utile avere una stringa univoca. Diventa il parametro del contenitore di servizi di nome kernel.secret.

http_method_override

Nuovo nella versione 2.3: L’opzione http_method_override è nuova in Symfony 2.3.

type: booleano predefinito: true

Determina se il parametro _method della richiesta sia usato come metodo HTTP inteso sulle richieste POST. Se abilitato, Request::enableHttpMethodParameterOverride è richiamato automaticamente. Diventa un parametro del contenitore di servizi, con nome kernel.http_method_override. Per maggiori informazioni, vedere Usare i metodi HTTP oltre a GET e POST nelle rotte.

ide

tipo: stringa predefinito: null

Se si usa un IDE, come TextMate o Mac Vim, allora Symfony può cambiare tutti i percorsi del file nei messaggi di eccezione in collegamenti, che apriranno i file nell’IDE specificato.

Se si usa TextMate o Mac Vim, si possono usare semplicemente uno dei seguenti valori:

  • textmate
  • macvim
  • emacs
  • sublime

Nuovo nella versione 2.3.14: Gli editor emacs e sublime sono stati introdotti in Symfony 2.3.14.

Si può anche specificare una stringa con un collegamento personalizzato. Se lo si fa, tutti i simboli percentuale (%) devono essere raddoppiati, per escape. Per esempio, la stringa completa per PhpStormOpener sarebbe come questa:

  • YAML
    # app/config/config.yml
    framework:
        ide: "pstorm://%%f:%%l"
    
  • XML
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config ide="pstorm://%%f:%%l" />
    </container>
    
  • PHP
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'ide' => 'pstorm://%%f:%%l',
    ));
    

Ovviamente, poiché ogni sviluppatore usa un IDE diverso, è meglio impostarlo a livello di sistema. Lo si può fare impostando il valore xdebug.file_link_format di php.ini alla stringa del collegamento. Se questo valore di configurazione è impostato, non occorre specificare l’opzione ide.

test

tipo: booleano

Se questo parametro di configurazione è presente e non è false, saranno caricati i servizi correlati ai test dell’applicazione (p.e. test.client). Questa impostazione dovrebbe essere presente in ambiente test (solitamente tramite app/config/config_test.yml). Per maggiori informazioni, vedere Test.

default_locale

tipo: stringa predefinito: en

Opzione usata se il parametro _locale non è stato impostato nelle rotte. Diventa il parametro del contenitore dei servizi kernel.default_locale ed è anche disponibile con il metodo Request::getDefaultLocale.

trusted_proxies

tipo: array

Configura gli indirizzi IP di cui fidarsi come proxy. Per maggiori dettagli, vedere Proxy fidati.

Nuovo nella versione 2.3: È stato introdotto il supporto per la notazione CIDR, quindi si possono indicare intere sotto-reti (p.e. 10.0.0.0/8, fc00::/7).

  • YAML
    # app/config/config.yml
    framework:
        trusted_proxies:  [192.0.0.1, 10.0.0.0/8]
    
  • XML
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config trusted-proxies="192.0.0.1, 10.0.0.0/8" />
    </container>
    
  • PHP
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'),
    ));
    

form

enabled

tipo: booleano predefinito: false

Se abilitare o meno il supporto per il componente Form.

Se non si usano form, impostare questa opzione a false può aumentare le prestazioni, perché saranno caricati meno servizi nel contenitore.

Se è attivato, anche il sistema di validazione è automaticamente abilitato.

csrf_protection

enabled

tipo: booleano predefinito: true se il supporto per i form è abilitato, false altrimenti

Si può usare questa opzione per disabilitare la protezione CSRF su tutti i form. Ma si può anche disabilitare la protezione CSRF su singoli form.

Se si usano form, ma non si vuole far partire la sessione (p.e. si usano form in un sito di sole API), csrf_protection va impostato a false.

field_name

tipo: stringa predefinito: "_token"

Il nome del campo nascosto usato per rendere i token CSRF.

session

name

tipo: stringa predefinito: null

Specifica in nome del cookie di sessione. Per impostazione predefinita, sarà utilizzato il nome definito nel php.ini con la direttiva session.name.

gc_probability

tipo: intero predefinito: 1

Definisce la probabilità che il processo del garbage collector parta a ogni inizializzazione della sessione. La probabilità è calcolata usando gc_probability / gc_divisor, p.e. 1/100 vuol dire che c’è una probabilità dell‘1% che il processo parta, in ogni richiesta.

gc_divisor

tipo: intero predefinito: 100

Vedere gc_probability.

gc_maxlifetime

tipo: intero predefinito: 14400

Determina il numero di secondi dopo i quali i dati saranno visti come “garbage” e quindi potenzialmente cancellati. Il garbage collector può intervenire a inizio sessione e dipende da gc_divisor e gc_probability.

save_path

tipo: stringa predefinito: %kernel.cache.dir%/sessions

Determina il parametro da passare al gestore di salvataggio. Se si sceglie il gestore file (quello predefinito), è il percorso in cui saranno creati i file. Per maggiori informazioni, vedere Configurare la cartella in cui salvare le sessioni.

Si può anche impostare questo valore a quello di save_path di php.ini, impostandolo a null:

  • YAML
    # app/config/config.yml
    framework:
        session:
            save_path: null
    
  • XML
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:session save-path="null" />
        </framework:config>
    </container>
    
  • PHP
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'session' => array(
            'save_path' => null,
        ),
    ));
    

serializer

enabled

tipo: booleano predefinito: false

Se abilitare o meno il servizio serializer nel contenitore.

Per maggiori dettagli, vedere Come usare il Serializer.

templating

assets_base_urls

predefinito: { http: [], ssl: [] }

Questa opzione consente di definire URL di base da usare per i riferimenti alle risorse nelle pagine http e https. Si può fornire un valore stringa al posto di un array a elementi singoli. Se si forniscono più URL base, Symfony ne sceglierà una dall’elenco ogni volta che genera il percorso di una risorsa.

Per praticità, assets_base_urls può essere impostata direttamente con una stringa o array di stringhe, che saranno automaticamente organizzate in liste di URL base per le richieste http e https. Se un URL inizia con https:// o è protocol-relative (cioè inizia con //), sarà aggiunto a entrambe le liste. Gli URL che iniziano con http:// saranno aggiunti solo alla lista http.

assets_version

tipo: stringa

Questa opzione è usata per evitare che le risorse vadano in cache, aggiungendo globalmente un parametro di query a tutti i percorsi delle risorse (p.e. /images/logo.png?v2). Si applica solo alle risorse rese tramite la funzione asset di Twig (o al suo equivalente PHP), come pure alle risorse rese con Assetic.

Per esempio, si supponga di avere il seguente:

  • Twig
    <img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
    
  • PHP
    <img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
    

Per impostazione predefinita, renderà un percorso alla propria immagine, come /images/logo.png. Ora, attivare l’opzione assets_version:

  • YAML
    # app/config/config.yml
    framework:
        # ...
        templating: { engines: ['twig'], assets_version: v2 }
    
  • XML
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:templating assets-version="v2">
            <!-- ... -->
            <framework:engine>twig</framework:engine>
        </framework:templating>
    </container>
    
  • PHP
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        // ...
        'templating'      => array(
            'engines'        => array('twig'),
            'assets_version' => 'v2',
        ),
    ));
    

Ora, la stessa risora sarà resa come /images/logo.png?v2. Se si usa questa caratteristica, si deve incrementare a mano il valore di assets_version, prima di ogni deploy, in modo che il parametro della query cambi.

È anche possibile impostare il valore della versione per singola risorsa (invece di usare una versione globale, come fatto qui con v2)). Vedere versioni per risorsa per i dettagli.

Si può anche contollare il funzionamento della stringa della query, tramite l’opzione assets_version_format.

assets_version_format

tipo: stringa predefinito: %%s?%%s

Specifica uno schema per sprintf, usato con l’opzione assets_version per costruire il percorso della risorsa. Per impostazione predefinita, lo schema aggiunge la versione della risorsa alla stringa della query. Per esempio, se assets_version_format è impostato a %%s?version=%%s e assets_version è impostato a 5, il percorso della risorsa sarà /images/logo.png?version=5.

Nota

Tutti i simboli percentuale (%) nel formato devono essere raddoppiati per escape. Senza escape, i valori sarebbero inavvertitamente interpretati come I parametri del servizio.

Suggerimento

Alcuni CDN non sopportano la spaccatura della cache tramie stringa della query, quindi si rende necessario l’inserimento della versione nel vero percorso della risorsa. Fortunatamente, assets_version_format non è limitato alla produzione di stringhe di query con versioni.

Lo schema riceve il percorso originale della risorsa e la versione come primo e secondo parametro, rispettivamente. Poiché il percorso della risorsa è un parametro, non possiamo modificarlo al volo (p.e. /images/logo-v5.png). Tuttavia, possiamo aggiungere un prefisso al percorso della risorsa, usando uno schema version-%%2$s/%%1$s, che risulta nel percorso version-5/images/logo.png.

Si possono quindi usare le riscritture degli URL, per togliere il prefissod con la versione prima di servire la risorsa. In alternativa, si possono copiare le risorse nel percorso appropriato con la versione, come parte del processo di deploy, e non usare la riscrittura degli URL. L’ultima opzione è utile se si vuole che le vecchie versioni delle risorse restino disponibili nei loro URL originari.

profiler

enabled

Nuovo nella versione 2.2: L’opzione enabled è stata aggiunta in Symfony 2.2. Precedentemente il profilatore poteva essere disabilitato solamente omettendo interamente la configurazione framework.profiler.

tipo: booleano predefinito: false

Il profilatore può essere abilitato impostando questa chiave a true. Se si usa Symfony Standard Edition, il profilatore è abilitato in ambiente dev e test.

collect

Nuovo nella versione 2.3: L’opzione collect è nuova in Symfony 2.3. Precedentemente, quando profiler.enabled era false, il profilatore era effettivamente attivo, ma i raccoglitori disabilitati. Ora profilatore e raccoglitori sono controllabili separatamente.

predefinito: true

Questa opzione configura il modo in cui il profilatore si comporta quando abilitato. Se true, il profilatore raccoglie dati per ogni richiesta. Se si vogliono raccogliere informazioni solo in casi specifici, impostare collect a false e attivare i raccoglitori di dati manualmente:

$profiler->enable();

translator

enabled

tipo: booleano predefinito: false

Se abilitare o meno il servizio translator nel contenitore.

fallbacks

tipo: stringa|array predefinito: array('en')

Nuovo nella versione 2.3.25: L’opzione fallbacks è stata introdotta in Symfony 2.3.25. Prima di Symfony 2.3.25, si chiamava fallback e consentiva un solo linguaggio, definito come stringa. Notare che è ancora possibile usare la vecchia opzione fallback, se si vuole definire un solo linguaggio.

Opzione usata quando non viene trovata la chiave di traduzione del locale corrente.

Per maggiori dettagli, vedere Traduzioni.

logging

Nuovo nella versione 2.6: L’opzione logging è stata introdotta in Symfony 2.6.

predefinito: true in modalità di debug, false altrimenti.

Se true, ogni volta che il traduttore non trova una traduzione per una chiave, la salverà nel log. I log sono scritti sul canale translation e su debug per livelli per chiavi in cui ci sia una traduzione nel locale predefinito e a livello warning se non c’è alcuna traduzione utilizzabile.

property_accessor

magic_call

tipo: booleano predefinito: false

Se abilitato, il servizio property_accessor usa il metodo magico __call() di PHP quando viene richiamato il metodo getValue().

throw_exception_on_invalid_index

tipo: booleano predefinito: false

Se abilitato, il servizio property_accessor lancerà un’eccezione se si prova ad accedere a un indice non valido di un array.

validation

enabled

tipo: booleano predefinito: true se il supporto ai form è abilitato, false altrimenti

Se abilitare o meno il supporto alla validazione.

cache

tipo: stringa

Questo valore è usato per deterimnare il servizio utilizzato per persistere i metadati di classe in una cache. Il servizio deve implementare Symfony\Component\Validator\Mapping\Cache\CacheInterface.

enable_annotations

tipo: Booleano predefinito: false

Se questa opzione è abilitata, si possono definire vincoli di validazione tramite annotazioni.

translation_domain

tipo: stringa predefinito: validators

Il dominio di traduzione usato quando si traducono i messaggi di errore dei vincoli di validazione.

strict_email

Nuovo nella versione 2.5: L’opzione strict_email è stata introdotta in Symfony 2.5.

tipo: Booleano predefinito: false

Se questa opzione è abilitati, sarà usata la libreria egulias/email-validator dal vincolo di validazione Email. Altrimenti, il validare usa una semplice espressione regolare per validare indirizzi email.

api

Nuovo nella versione 2.5: L’opzione api è stata introdotta in Symfony 2.5.

tipo: stringa

A partire da Symfony 2.5, il componente Validator ha introdotto una nuova API di validazione. L’opzione api si usa per cambiare implementazione:

2.4
Usa l’API di validazione compatibile con le vecchie versioni di Symfony.
2.5
Usa l’API di validazione introdotta in Symfony 2.5.
2.5-bc or auto
Se si omette un valore o si imposta api a 2.5-bc o auto, Symfony userà un’API compatibile sia con la vecchia implementazione che con quella 2.5. Occorre usare PHP 5.3.9 o successivi per poter usare questa implementazione.

Per salvare i log in ambiente prod, configurare un gestore di canale in config_prod.yml per il canale translation e impostare level a debug.

Configurazione predefinita completa

  • YAML
    framework:
        secret:               ~
        http_method_override: true
        trusted_proxies:      []
        ide:                  ~
        test:                 ~
        default_locale:       en
    
        csrf_protection:
            enabled:              false
            field_name:           _token # Deprecato da 2.4, da rimuovere in 3.0. Usare invece form.csrf_protection.field_name
    
        # configurazione dei form
        form:
            enabled:              false
            csrf_protection:
                enabled:          true
                field_name:       ~
    
        # configurazione di esi
        esi:
            enabled:              false
    
        # configurazione dei frammenti
        fragments:
            enabled:              false
            path:                 /_fragment
    
        # configurazione del profilatore
        profiler:
            enabled:              false
            collect:              true
            only_exceptions:      false
            only_master_requests: false
            dsn:                  "file:%kernel.cache_dir%/profiler"
            username:
            password:
            lifetime:             86400
            matcher:
                ip:                   ~
    
                # usare il formato urldecoded
                path:                 ~ # Esempio: ^/percorso della risorsa/
                service:              ~
    
        # configurazione delle rotte
        router:
            resource:             ~ # Obbligatorio
            type:                 ~
            http_port:            80
            https_port:           443
    
            # impostare a true per lanciare un'eccezione se un parametro non corrisponde ai requisiti
            # impostare a false per disabilitare le eccezioni se un parametro non corrisponde ai requisiti (e restituire null)
            # impostare a null per disabilitare la verifica dei requisiti dei parametri
            # true è preferibile durante lo sviluppo, mentre false o null sono preferibili in produzione
            strict_requirements:  true
    
        # configurazione della sessione
        session:
            storage_id:           session.storage.native
            handler_id:           session.handler.native_file
            name:                 ~
            cookie_lifetime:      ~
            cookie_path:          ~
            cookie_domain:        ~
            cookie_secure:        ~
            cookie_httponly:      ~
            gc_divisor:           ~
            gc_probability:       ~
            gc_maxlifetime:       ~
            save_path:            "%kernel.cache_dir%/sessions"
    
        # configurazione dei serializer
        serializer:
           enabled: false
    
        # configurazione dei template
        templating:
            assets_version:       ~
            assets_version_format:  "%%s?%%s"
            hinclude_default_template:  ~
            form:
                resources:
    
                    # Predefinito:
                    - FrameworkBundle:Form
            assets_base_urls:
                http:                 []
                ssl:                  []
            cache:                ~
            engines:              # Obbligatorio
    
                # Esempio:
                - twig
            loaders:              []
            packages:
    
                # Prototipo
                nome:
                    version:              ~
                    version_format:       "%%s?%%s"
                    base_urls:
                        http:                 []
                        ssl:                  []
    
        # configurazione della traduzione
        translator:
            enabled:              false
            fallback:             en
            logging:              "%kernel.debug%"
    
        # configurazione della validazione
        validation:
            enabled:              false
            cache:                ~
            enable_annotations:   false
            translation_domain:   validators
    
        # configurazione delle annotazioni
        annotations:
            cache:                file
            file_cache_dir:       "%kernel.cache_dir%/annotations"
            debug:                "%kernel.debug%"