The Best Practices Book Version: 2.6

Transcript

1 The Best Practices Book Version:. generated on September, 0

2 The Best Practices 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 Best Practice Symfony Framework... Creare il progetto... Configurazione...0 Organizzare la logica di business... Controllori...0 Template... Form... Internationalizzazione... Sicurezza... Risorse pubbliche... Test... generated on September, 0 Contents at a Glance iii

4 Chapter Best Practice Symfony Framework Symfony è conosciuto per essere un framework molto flessibile ed è infatti utilizzato in diversi ambiti come ad esempio piccoli siti web, applicazioni enterprise con miliardi di richieste e anche come base per altri framework. Da quando è stato pubblicato nel luglio 0, la comunità ha imparato molto su ciò che Symfony è in grado di fare e su quale sia il modo migliore per farlo. Le diverse risorse create dalla comunità, da articoli di blog a presentazioni a conferenze, hanno creato una serie di raccomandazioni e pratiche ufficiose per lo sviluppo di applicazioni Symfony. Purtroppo molte di queste raccomandazioni sono sbagliate e oltre a complicare lo sviluppo delle stesse applicazioni non sono allineate con la filosofia originale e pragmatica dei creatori di Symfony. Di che parla questa guida? Lo scopo di questa guida è quello di risolvere il problema sopra menzionato stabilendo una serie di buone pratiche ufficiali per lo sviluppo di applicazioni web con il framework Symfony. Queste pratiche sono quelle che meglio si adattano alla filosofia immaginata dal creatore originale del framework Fabien Potencier. Best practice è un termine che vuol dire "una procedura ben definita, nota per produrre risultati quasi ottimali". Ciò è esattamente quello che questa guida di propone di fornire. Anche se non tutti saranno d'accordo con ogni raccomandazione, c'è una ferma convinzione che saranno tutte d'aiuto per costruire grandi applicazioni con minore complessità. Questa guida è particolarmente indicata per: Siti web e applicazioni web sviluppato con il framework Symfony. Per altre situazioni, questa guida potrebbe essere un buon punto di partenza, che si potre estendere per soddisfare le proprie esigenze specifiche: Bundle condivisi pubblicamente con la comunità di Symfony; Sviluppatori esperti o squadre che hanno creato i propri standard;. generated on September, 0 Chapter : Best Practice Symfony Framework

5 Alcune applicazioni complesse, con requisiti altamente personalizzati; Bundle che potrebbero essere condivisi internamente in un'azienda. Si sa che le vecchie abitudini sono dure a morire e qualcuno potrebbe meravigliarsi o non essere d'accordo con alcune di queste regole. Nonostante ciò, crediamo che seguendo questi consigli potrete sviluppare le applicazioni più velocemente, con una minore complessità e con la stessa o perfino una migliore qualità. Inoltre le raccomandazioni saranno continuamente aggiornate e migliorate. In ogni caso, considerare che le raccomandazioni sono *opzionali e che ogni sviluppatore può decidere se adottarle oppure no. Se si preferisce continuare a sviluppare utilizzando altre pratiche e metodologie, si può continuare a farlo. Symfony è abbastanza flessibile da adattarsi a ogni necessità e questo non cambierà mai. A chi è rivolto il libro? (Suggerimento: non è un tutorial) Questa guida è pensata per qualsiasi sviluppatore Symfony, sia esperto che principiante. Non essendo un tutorial passo passo, però, è necessaria una conoscenza basilare di Symfony, per seguire la guida al meglio. Per chi è proprio agli inizi, benvenuto nella comunità! Meglio iniziare con il tutorial la guida rapida. Inoltre è stato deciso di mantenere questa guida più piccola possibile, per essere molto facile da leggere. Non ci si soffermerà su spiegazioni che si possono trovare nella documentazione ufficiale di Symfony, come discussioni sulla dependency injection o sui front controller. Ci si soffermerà unicamente a spiegare come fare ciò che già si conosce. L'applicazione Insieme a questa guida ci sarà un'applicazione di esempio, sviluppata seguendo le best practice. L'applicazione è un semplice blog, che consentirà di concentrarsi sui concetti di Symfony, senza sconfinare in particolarità proprie dell'applicazione. Invece di sviluppare l'applicazione passo passo, ci saranno pezzi di codice all'interno dei singoli capitoli. Fare riferimento all'ultimo capitolo di questa guida per maggiori dettagli sull'applicazione e le istruzioni per installarla. Non aggiornare un'applicazione esistente Dopo aver letto questo manuale, qualcuno potrebbe pensare di rifattorizzare la sua applicazione Symfon. La raccomandazione è chiara e netta: meglio non rifattorizzare applicazioni esistenti per aderire a queste best practice. Le ragioni per non farlo sono diverse: Le applicazioni esistenti non sono sbagliate, seguono semplicemente un insieme diverso di linee guida; Una rifattorizzazione totale espone a possibili errori nell'applicazione; L'ammontare di lavoro speso potrebbe essere dedicato con più profitto a migliorare i test o ad aggiungere funzionalità che forniscano valore reale agli utenti finali. generated on September, 0 Chapter : Best Practice Symfony Framework

6 Chapter Creare il progetto Installazione di Symfony In passato, i progetti Symfony erano creati con Composer, il gestore di dipendenze per applicazioni PHP. Tuttavia, la raccomandazione attuale è di usare l'installatore di Symfony, che deve essere installato prima della creazione del primo progetto. Usare l'installatore di Symfony per creare nuovi progetti basati su Symfony. Leggere il capitolo dell'installazione del libro di Symfony per sapere come installare e usare l'installatore di Symfony. Creare un'applicazione Blog Ora che è tutto pronto, si può creare un nuovo progetto, basato su Symfony. Nella console dei comandi, andare nella cartelle in cui si hanno i permessi per creare file ed eseguire i comandi seguenti: Listing - # Linux, Mac OS X $ cd progetti/ $ symfony new blog # Windows c:\> cd progetti/ c:\progetti\> php symfony.phar new blog Questo comando crea una nuova cartella chiamata blog, con dentro un nuovo progetto, basato sulla versione stabile più recente di Symfony al momento disponibile. Inoltre, l'installatore verifica se il sistema soddisfa i requisiti tecnici per eseguire le applicazioni Symfony. In caso contrario, si vedrà una lista di modifiche necessarie per soddisfare tali requisiti.. generated on September, 0 Chapter : Creare il progetto

7 Per ragioni di sicurezza, tutte le versioni di Symfony sono firmate digitalmente. Se si vuole verificare l'integrità di una versione di Symfony, dare un'occhiata al repository dei checksum pubblici e seguire questi passi. Strutturare l'applicazione Dopo aver creato l'applicazione, spostandosi nella cartella blog/, si vedrà il seguente insieme di file e cartelle, generato automaticamente: Listing - 0 blog/ app/ console cache/ config/ logs/ Resources/ src/ AppBundle/ vendor/ web/ Questa gerarchia di file e cartelle è la struttura proposta da Symfony per organizzare un'applicazione. Lo scopo di ciascuna cartella è il seguente: app/cache/ contiene tutti i file di cache generati dall'applicazione; app/config/ contiene la configurazione definita per ciascun ambiente; app/logs/ contiene tutti i file di log generati dall'applicazione; app/resources/ contiene tutti i file template e di traduzione dell'applicazione; src/appbundle/ contiene codice specifico per Symfony (controllori e rotte), codice di dominio (p.e. le classi Doctrine) e tutta la logica di business; vendor/ in questa cartella Composer installa tutte le dipendenze dell'applicazione; non si dovrebbe mai modificare il suo contenuto; web/ contiene il front controller e tutti le risorse per il web, come i fogli di stile, i file JavaScript e le immagini. I bundle dell'applicazione Quando è stato rilasciato Symfony.0, la maggior parte degli sviluppatori ha adottato, in modo naturale, lo stesso approccio usato in symfony.x, suddividendo l'applicazione in moduli logici. Proprio per questo, molte applicazioni Symfony separano i bundle dal punto di vista logico: UserBundle, ProductBundle, InvoiceBundle, eccetera. Tuttavia, i bundle sono stati concepiti come moduli software da riutilizzare in maniera autonoma. Se UserBundle non può essere riusato "così com'è" in un'altra applicazione Symfony, allora non è più un. generated on September, 0 Chapter : Creare il progetto

8 bundle. Inoltre, InvoiceBundle dipende da ProductBundle, quindi non esiste alcun vantaggio ad avere due bundle separati. Creare solamente un bundle, chiamato AppBundle, per la logica dell'applicazione Implementando solamente il bundle AppBundle in un progetto, si renderà il codice più conciso e facile da capire. A partire da Symfony., la documentazione ufficiale di Symfony mostra gli esempi con il bundle AppBundle. Non è necessario aggiungere il prefisso dell'azienda (vendor) ad AppBundle (p.e. AcmeAppBundle), dato che questo bundle, specifico dell'applicazione, non verrà mai condiviso con terzi. Detto questo, la struttura di cartelle raccomandata di un'applicazione Symfony è la seguente: Listing - 0 blog/ app/ console cache/ config/ logs/ Resources/ src/ AppBundle/ vendor/ web/ app.php app_dev.php Se l'installazione di Symfony non dispone di un AppBundle già generato, lo si può generare a mano, con questo comando: Listing - $ php app/console generate:bundle --namespace=appbundle --dir=src --format=annotation --no-interaction Estendere la struttura delle cartelle Se un progetto o un'infrastruttura richiedono alcune modifiche alla struttura predefinita delle cartelle, è possibile ridefinire la posizione delle cartelle principali: cache/, logs/ e web/. Symfony, inoltre, userà una struttura di cartelle leggermente diversa, quando sarà rilasciato: Listing - 0 blog-symfony/ app/ config/ Resources/ bin/ console src/ var/ cache/ logs/ generated on September, 0 Chapter : Creare il progetto

9 vendor/ web/ Le modifiche sono piuttosto superficiali ma, per ora, si consiglia di utilizzare la struttura di cartelle di Symfony. generated on September, 0 Chapter : Creare il progetto

10 Chapter Configurazione La configurazione di un'applicazione, normalmente, coinvolge diverse parti (ad es. infrastruttura tecnologica e sicurezza) e diversi ambienti (sviluppo, produzione). Proprio per questo, Symfony raccomanda di suddividere la configurazione in tre parti. Configurazione relativa all'infrastruttura Definire le opzioni della configurazione relativa all'infrastruttura tecnologica nel file app/config/ parameters.yml. Il file parameters.yml segue questa regola e definisce le opzioni relative alla base dati e al server di posta: Listing - 0 # app/config/parameters.yml parameters: database_driver: pdo_mysql database_host:.0.0. database_port: ~ database_name: symfony database_user: root database_password: ~ mailer_transport: smtp mailer_host:.0.0. mailer_user: ~ mailer_password: ~ #... Queste opzioni non sono definite nel file app/config/config.yml, perché non hanno niente a che fare con il comportamento dell'applicazione. In altre parole, l'applicazione non si deve preoccupare di sapere dov'è posizionata la base dati o come vi accede. L'unica cosa che gli importa sapere è che la base dati sia configurata correttamente. generated on September, 0 Chapter : Configurazione 0

11 Parametri canonici Definire tutti i parametri dell'applicazione nel file ` app/config/parameters.dist.yml``. Dalla versione., Symfony include un file di configurazione chiamato parameters.dist.yml, che contiene tutti i parametri di configurazione che devono essere definiti affinché l'applicazione funzioni correttamente. Ogni volta che viene definito un nuovo parametro di configurazione per l'applicazione, esso dovrebbe essere aggiunto a questo file e tale modifica dovrebbe essere registrata anche sul sistema di controllo di versione. Quando lo sviluppatore aggiorna il progetto o esegue un deploy, Symfony controllerà eventuali differenze tra il file canonico parameters.dist.yml` e il file locale parameters.yml. In presenza di differenze Symfony, chiederà di fornire un valore per il nuovo parametro e lo aggiungerà al file locale parameters.yml. Configurazione relativa all'applicazione Definire le opzioni di configurazione relative all'applicazione nel file app/config/config.yml. Il file config.yml contiene le opzioni usate dall'applicazione per modificare il suo comportamento, come ad esempio il mittente delle o l'abilitazione di feature toggle. È possibile definire questi valori anche in parameters.yml, ma questo aggiungerebbe un livello di configurazione extra non necessario, perché solitamente non si vuole che questi valori cambino su ogni server. Le opzioni di configurazione definite nel file config.yml solitamente variano da un ambiente all'altro. È per questo che Symfony include già i file app/config/config_dev.yml e app/config/ config_prod.yml, in modo che si possano ridefinire valori specifici per ciascun ambiente. Costanti od opzioni di Configurazione Uno degli errori più comuni nel definire la configurazione dell'applicazione è creare nuove opzioni per valori che non cambieranno mai, come ad esempio il numero degli elementi mostrati in una paginazione. Usare costanti per definire opzioni di configurazione che cambieranno raramente. L'approccio tradizionale della definizione delle opzioni di configurazione ha costretto molte applicazioni Symfony a includere opzioni come la seguente, che controlla il numero di post da mostrare nell'homepage del blog. Listing - # app/config/config.yml parameters: homepage.num_items: 0 Se chiedete a voi stessi quando è stata l'ultima volta che avete modificato il valore di una opzione come questa, è probabile che la risposta sia mai. Creare un'opzione di configurazione per un valore che non si andrà mai a modificare è inutile. La nostra raccomandazione è di definire questi valori come costanti nell'applicazione. Si potrebbe, ad esempio, definire una costante NUM_ITEMS nell'entità Post: Listing -. generated on September, 0 Chapter : Configurazione

12 // src/appbundle/entity/post.php namespace AppBundle\Entity; class Post const NUM_ITEMS = 0; Il vantaggio più importante nella definizione di costanti è che si possono utilizzare dappertutto nell'applicazione. A differenza i parametri sono disponibili solamente tramite il contenitore di Symfony. Le costanti possono essere usate, per esempio, nei template di Twig, grazie alla funzione constant(): Listing - <p> Displaying the constant('num_items', post) most recent results. </p> Così facendo, sia le entità di Doctrine che i repository possono accedere facilmente a questi valori, mentre le stesse classi non posso accedere ai parametri del contenitore. Listing - 0 namespace AppBundle\Repository; use Doctrine\ORM\EntityRepository; use AppBundle\Entity\Post; class PostRepository extends EntityRepository public function findlatest($limit = Post::NUM_ITEMS) L'unico svantaggio da considerare, nell'utilizzo delle costanti come opzioni di configurazione, è che non possono essere ridefinite facilmente nei test. Non usare la configurazione semantica Non definire nei bundle una configurazione semantica per il contenitore. Come spiegato nella ricetta Caricare la configurazione di un servizio in un bundle, i bundle di Symfony possono gestire le opzioni di configurazione in due modi: la configurazione normale del servizio, attraverso il file services.yml, e la configurazione semantica, attraverso una classe speciale di tipo *Extension. Sebbene la configurazione semantica è molto più potente e fornisce interessanti caratteristiche, come la validazione delle opzioni di configurazione, la quantità di lavoro necessaria per la definizione del bundle è notevole e non vale la pena cimentarsi per bundle non rivolti a terzi. generated on September, 0 Chapter : Configurazione

13 Spostare le opzioni di configurazione sensibili al di fuori di Symfony Quando si lavora con opzioni sensibili, come le credenziali di accesso alla base dati, si raccomanda di spostarle al di fuori dell'applicazione Symfony e di renderle disponibili tramite variabili d'ambiente. Si può imparare come farlo nella seguente ricetta: Configurare parametri esterni nel contenitore dei servizi generated on September, 0 Chapter : Configurazione

14 Chapter Organizzare la logica di business In informatica, La logica di business è "la parte del programma che codifica le regole di business della vita reale, che determinano il modo in cui i dati possono essere creati, memorizzati e modificati" (vedere la definizione completa ). Nelle applicazioni Symfony, la logica di business comprende tutto il codice implementato per l'applicazione non relativo al framework. Le classi di dominio, le entità Doctrine e classiche classi PHP utilizzate come servizi rappresentano buoni esempi di logica di business. Nella maggior parte dei progetti, la logica di business dovrebbe essere inserita dentro AppBundle. All'interno di tale bundle è possibile creare qualsiasi gerarchia di cartelle, come struttura organizzativa. Listing - progetto-symfony/ app/ src/ AppBundle/ Utils/ MiaClasse.php vendor/ web/ Mettere classi fuori dal bundle? Non vi è alcuna limitazione tecnica che ci impedisca di mettere la logica di business fuori dal bundle. Se si vuole si può creare il proprio namespace dentro src/ e mettere tutto là dentro: Listing - progetto-symfony/ app/ src/ Acme/ Utils/ MiaClasse.php. generated on September, 0 Chapter : Organizzare la logica di business

15 AppBundle/ vendor/ web/ La raccomandazione di usare il bundle AppBundle è giustificata dal voler rendere tutto più facile da gestire. Se sei così esperto da sapere cosa è necessario mettere dentro un bundle e cosa mettere invece fuori, sentiti libero di farlo. Servizi: nomi e formati La nostra applicazione blog ha bisogno di una utility in grado di trasformare il titolo di ogni post (ad es. "Ciao mondo") nel suo relativo slug (ad es. "ciao-mondo"). Lo slug verrà quindi usato come parte dell'url del post. Creiamo una classe Slugger dentro src/appbundle/utils/ e aggiungiamo il metodo slugify(): Listing - 0 // src/appbundle/utils/slugger.php namespace AppBundle\Utils; class Slugger public function slugify($string) return preg_replace( '/[^a-z0-]/', '-', strtolower(trim(strip_tags($string))) ); Definiamo quindi un nuovo servizio per tale classe. Listing - # app/config/services.yml services: # keep your service names short app.slugger: class: AppBundle\Utils\Slugger Per la definizione dei nomi dei servizi solitamente si sceglie di utilizzare il nome e la posizione della classe, per evitare collisioni di nomi. Pertanto il servizio dovrebbe chiamarsi app.utils.slugger. Tuttavia, se si usano nomi dei servizi brevi, il codice risulterà più facile da leggere e da usare. Il nome di un servizio dovrebbe essere il più breve possibile, ma abbastanza univoco da poter cercare il servizio nel progetto, se necessario. Adesso è possibile usare lo slugger da ogni controllore, come AdminController: Listing - public function createaction(request $request) if ($form->issubmitted() && $form->isvalid()) $slug = $this->get('app.slugger')->slugify($post->gettitle()); generated on September, 0 Chapter : Organizzare la logica di business

16 0 $post->setslug($slug); Formato dei servizi: YAML Per la definizione del servizio, nella sezione precedente, è stato usato il formato YAML. Per la definizione dei propri servizi usare il formato YAML. Si sa che questa raccomandazione è molto controversa. È noto che sia il formato YAML sia il formato XML sono ugualmente utilizzati tra gli sviluppatori, con una leggere preferenza verso YAML. Entrambi i formati hanno le stesse prestazioni, quindi la scelta di quale utilizzare è una questione di gusti personali. Si raccomanda di usare YAML, perché risulta più semplice da gestire dai nuovi programmatori e perché più conciso. Ovviamente, si può usare il formato che si preferisce. Servizi: niente parametri di classe Qualcuno potrebbe aver notato che nella definizione del servizio precedente non è stato creato un parametro di configurazione per definire la classe di servizio: Listing - # app/config/services.yml # definzione di servizio con classe come parametro parameters: slugger.class: AppBundle\Utils\Slugger services: app.slugger: class: "%slugger.class%" Questa pratica risulta scomoda e assolutamente non necessaria per i propri servizi: Non definire parametri di configurazione per le classi dei servizi. Questa abitudine trae la sua origine da un'erronea imitazione dei bundle di terze parti. Se si sviluppa un bundle da condividere, è possibile allora definire parametri di configurazione per le classi. Ma se si sviluppa un servizio per la propria applicazione, non c'è bisogno che le sue classi siano configurabili. Usare uno strato di persistenza Symfony è un framework HTTP, che si preoccupa solo di generare una risposta HTTP per ogni richiesta HTTP. Questo è il motivo per cui Symfony non prevede una sua modalità per comunicare con uno strato di persistenza (come una base dati o API esterne) È possibile quindi scegliere la libreria o la strategia preferita. generated on September, 0 Chapter : Organizzare la logica di business

17 In pratica, molte applicazioni Symfony si appoggiano al progetto Doctrine per definire il loro modello tramite entità e repository. Così come per la logica di business, si raccomanda di creare le entità di Doctrine in AppBundle. Le tre entità definite dall'applicazione blog sono un buon esempio di come rappresentare le classi: Listing - progetto-symfony/... src/ AppBundle/ Entity/ Comment.php Post.php User.php Per gli sviluppatori esperti, si possono creare classi in uno spazio dei nomi in src/. Informazioni di mappatura di Doctrine Le entità doctrine sono semplici classi PHP le cui informazioni vengono memorizzate in qualche "database". Le uniche informazioni conosciute da Doctrine su queste entità sono informazioni di mapping di metadati sul modello. Doctrine supporta quattro formati per definire queste informazioni: YAML, XML, PHP e annotazioni. Usare le annotazioni per definire la mappatura delle entità Doctrine. Le annotazioni sono di gran lunga il modo più conveniente e agile per definire e cercare le informazioni di mappatura: Listing namespace AppBundle\Entity; use Doctrine\ORM\Mapping as ORM; use Doctrine\Common\Collections\ArrayCollection; /** */ class Post const NUM_ITEMS = 0; /** */ private $id; /** */. generated on September, 0 Chapter : Organizzare la logica di business

18 private $title; /** */ private $slug; /** */ private $content; /** */ private $author ; /** */ private $publishedat; /** * targetentity="comment", * mappedby="post", * orphanremoval=true * ) = "ASC") */ private $comments; public function construct() $this->publishedat = new \DateTime(); $this->comments = new ArrayCollection(); // getter e setter... Tutti i formati hanno le stesse prestazioni, quindi la scelta su quale formato usare dipende, ancora una volta, dai gusti personali. Fixture dei dati Symfony non ha un supporto predefinito per le fixture, è necessario installare il bundle di gestione delle fixture in Doctrine, eseguendo il seguente comando: Listing - $ composer require "doctrine/doctrine-fixtures-bundle" Quindi è necessario abilitare il bundle in AppKernel.php, ma solo per gli ambienti dev e test: Listing -0 use Symfony\Component\HttpKernel\Kernel; generated on September, 0 Chapter : Organizzare la logica di business

19 0 0 class AppKernel extends Kernel public function registerbundles() $bundles = array( ); if (in_array($this->getenvironment(), array('dev', 'test'))) $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle(); return $bundles; Per semplicità, si raccomanda di creare solamente una classe fixture, anche se è consentito averne di più, se questa classe diventa troppo grande. Ipotizzando di avere almeno una classe fixture e che l'accesso alla base dati sia configurato correttamente, è possibile caricare il tutto eseguendo il seguente comando: Listing - $ php app/console doctrine:fixtures:load Careful, database will be purged. Do you want to continue Y/N? Y > purging database > loading AppBundle\DataFixtures\ORM\LoadFixtures Standard di codice Il codice sorgente di Symfony rispetta gli standard PSR- e PSR-, definiti dalla comunità PHP. Per saperne di più, vedere gli standard di codice di Symfony. Inoltre, usare PHP-CS-Fixer, una utility a riga di comando in grado di riformattare tutto il codice sorgente dell'applicazione in pochi secondi generated on September, 0 Chapter : Organizzare la logica di business

20 Chapter Controllori Symfony segue la filosofia "controllori magri e modelli grassi". Ciò significa che i controllori dovrebbero contenere solo il codice strettamente necessario per coordinare le diversi parti dell'applicazione. La regola d'oro per i controllori è sintetizzata nella tripla Ogni controllore dovrebbe definire al massimo variabili, contenere al massimo 0 azioni, ciascuna delle quali formate al massimo da 0 righe di codice. Anche se possono esserci eccezioni alla regola, essa mette in evidenza quando sarebbe opportuno iniziare a rifattorizzare il codice del controllore e spostarlo in un servizio. Estendere il controllore dalla classe base fornita da FrameworkBundle e usare le annotazioni per configurare rotte, cache e sicurezza, quando possibile. L'accoppiamento dei controllore al framework sottostante consente di sfruttare tutte le funzionalità del framework stesso, aumentando la produttività. Poiché i controllori dovrebbero essere leggeri e contenere niente di più che poche linee di codice, per coordinare il flusso della richiesta, spendere ore provando a disaccoppiarlo dal framework non porterà grandi benefici nel lungo periodo. La quantità di tempo sprecato non vale il beneficio. Inoltre usare le annotazioni per le rotte, la cache e la sicurezza semplifica enormemente la configurazione dell'applicazione. Non sarà necessario esplorare decine di file di formati diversi (YAML, XML, PHP): tutta la configurazione è lì dove serve e in un solo formato. Complessivamente, quindi, si dovrebbe disaccoppiare totalmente la logica di business dal framework e nello stesso tempo accoppiare totalmente al framework controllori e rotte, in modo da ottenere il massimo da Symfony. Configurazione delle rotte Per caricare tutte le rotte definite nelle annotazioni dei controllori del bundle AppBundle aggiungete la seguente configurazione al file principale delle rotte: Listing - # app/config/routing.yml app: resource: "@AppBundle/Controller/" type: annotation generated on September, 0 Chapter : Controllori 0

21 Questa configurazione caricherà le annotazioni da ogni controllore presente sia nella cartella src/ AppBundle/Controller/ sia nelle sue sottocartelle. Se l'applicazione definisce molti controllori, è perfettamente lecito organizzare il tutto in sottocartelle. Listing - 0 <progetto>/... src/ AppBundle/... Controller/ DefaultController.php... Api/ Backend/ Configurazione dei template Non usare per configurare il template usato dal controllore. Anche se risulta molto utile, essa nasconde qualche trucco. Ritenendo che il gioco non valga la candela, si raccomanda di non usarla. La maggior parte delle è usato senza parametri, il che rende più difficile sapere quale template viene reso. Il suo utilizzo inoltre rende meno ovvio ai principianti che un controllore deve sempre restituire un oggetto Response (a meno che non si usi il livello della vista). Come dovrebbe essere il controllore Considerando tutto, ecco un esempio di come dovrebbe essere il controllore per l'homepage di un'applicazione: Listing - 0 namespace AppBundle\Controller; use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; class DefaultController extends Controller /** name="homepage") */ public function indexaction() $posts = $this->getdoctrine() ->getrepository('appbundle:post') ->findlatest(); return $this->render('default/index.html.twig', array( 'posts' => $posts generated on September, 0 Chapter : Controllori

22 0 )); Usare ParamConverter Se l'applicazione usa Doctrine, è possibile usare opzionalmente ParamConverter per effettuare la ricerca dell'entity in modo automatico e passarla come parametro del controllore. Usare ParamConverter per caricare automaticamente le entità di Doctrine, nei casi più semplici. Per esempio: Listing - 0 use AppBundle\Entity\Post; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; /** name="admin_post_show") */ public function showaction(post $post) $deleteform = $this->createdeleteform($post); return $this->render('admin/post/show.html.twig', array( 'post' => $post, 'delete_form' => $deleteform->createview(), )); Solitamente ci si aspetterebbe un parametro $id nel metodo showaction. Invece, creando un nuovo parametro ($post) e specificando il tipo di classe Post (che è un'entità Doctrine), ParamConverter cercherà automaticamente un oggetto la cui proprietà $id corrisponde al valore id. Nel caso in cui non venga trovato alcun Post, verrà mostrato la pagina 0. Esecuzione di ricerche più avanzate Nell'esempio precedente tutto funziona senza nessuna configurazione, perché il nome del segnaposto id corrisponde esattamente al nome della proprietà dell'entità. Quando questo non succede, o se si ha perfino una logica più complessa, la cosa più facile da fare è cercare l'entità manualmente. Questo è per esempio quello che succede nella classe CommentController dell'applicazione: Listing - /** name = "comment_new") */ public function newaction(request $request, $postslug) $post = $this->getdoctrine() ->getrepository('appbundle:post') ->findoneby(array('slug' => $postslug));. generated on September, 0 Chapter : Controllori

23 0 if (!$post) throw $this->createnotfoundexception(); Naturalmente è possibile in modo più avanzato, perché è abbastanza flessibile: Listing - 0 use AppBundle\Entity\Post; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter; use Symfony\Component\HttpFoundation\Request; /** name = "comment_new") options="mapping": "postslug": "slug") */ public function newaction(request $request, Post $post) Si può infine dire che la scorciatoia di ParamConverter è buona nelle situazioni semplici. Nonostante ciò, non si dovrebbe mai dimenticare che la ricerca diretta di entity è un'operazione molto facile. Eseguire codice prima e dopo Se si ha la necessità di eseguire del codice prima o dopo l'esecuzione dei controllore, è possibile usare il componente EventDispatcher configurando i filtri prima e dopo. generated on September, 0 Chapter : Controllori

24 Chapter Template Quando è nato PHP, 0 anni fa, gli sviluppatori rimasero incantati dalla sua semplicità e dalla possibilità di mescolare facilamente HTML e codice dinamico. Con il passare del tempo, sono nati tanti linguaggi per i template, come Twig, in grado di gestire i template dell'applicazione in modo migliore. Usare Twig per i template Generalmente parlando, i template in PHP sono più prolissi di Twig, per la mancanza di supporto nativo a molte caratteristiche necessarie nei template moderni, come l'ereditarietà, l'escape automatico, i filtri e le funzioni. Twig è il formato predefinito per i template in Symfony e può contare sul supporto della più grande comunità di utenti fra tutti gli engine non PHP (è usato in progetti molto importanti, come Drupal ). Inoltre, Twig è l'unico formato con supporto garantito in Symfony.0. Il formato PHP potrebbe non essere più supportato ufficialmente. Posizione dei template Inserire tutti i template dell'applicazione nella cartella app/resource/views/ Solitamente gli sviluppatori Symfony mettevano i template dell'applicazione nella cartella Resources/ views/ di ciascun bundle. Per riferirsi ad essi usavano il nome logico (p.e. AcmeDemoBundle:Default:index.html.twig). Anche se per i bundle di terzi questa abitudine è corretta, è molto più conveniente, invece, inserire i template dell'applicazione nella cartella app/resources/views/. Innanzitutto questo semplifica drasticamente il nome logico dei template: Template dentro i bundle AcmeDemoBundle:Default:index.html.twig ::layout.html.twig AcmeDemoBundle::index.html.twig Template dentro app/ default/index.html.twig layout.html.twig index.html.twig generated on September, 0 Chapter : Template

25 Template dentro i bundle AcmeDemoBundle:Default:subdir/index.html.twig AcmeDemoBundle:Default/subdir:index.html.twig Template dentro app/ default/subdir/index.html.twig default/subdir/index.html.twig Un altro vantaggio è che centralizzare i template semplifica il lavoro dei grafici. Essi non dovranno cercare più i template in tante cartelle sparpagliate fra i bundle. Usare la notazione_serpente in minuscolo per nomi di cartelle e template. Estensioni Twig Definire le estensioni di Twig nella cartella AppBundle/Twig, configurandole nel file app/config/ services.yml. All'applicazione serve un filtro Twig personalizzato mhtml in modo da poter trasformare il contenuto di ogni post da Markdown in HTML. Per fare questo, per prima cosa, installare l'ottimo parser Markdown Parsedown come nuova dipendenza del progetto: Listing - $ composer require erusev/parsedown Quindi creare un nuovo servizio chiamato Markdown, che sarà usato successivamente dall' estensione Twig. La definizione del servizio richiede solamente di specificare il percorso della classe. Listing - # app/config/services.yml services: #... markdown: class: AppBundle\Utils\Markdown La classe Markdown definisce un unico metodo per trasformare il contenuto Markdown in contenuto HTML: Listing - 0 namespace AppBundle\Utils; class Markdown private $parser; public function construct() $this->parser = new \Parsedown(); public function tohtml($text) $html = $this->parser->text($text); return $html;. generated on September, 0 Chapter : Template

26 Quindi, creare un'estensione Twig e definire un nuovo filtro chiamato mdhtml, utilizzando la classe Twig_SimpleFilter. Iniettare il nuovo servizio, appena definito, markdown nel costruttore dell'estensione Twig: Listing namespace AppBundle\Twig; use AppBundle\Utils\Markdown; class AppExtension extends \Twig_Extension private $parser; public function construct(markdown $parser) $this->parser = $parser; public function getfilters() return array( new \Twig_SimpleFilter( 'mdhtml', array($this, 'markdowntohtml'), array('is_safe' => array('html')) ), ); public function markdowntohtml($content) return $this->parser->tohtml($content); public function getname() return 'app_extension'; Infine, definire un nuovo servizio, assegnandogli il tag twig.extension (il nome del servizio è irrilevante, perché non verrà mai usato nel codice). Listing - # app/config/services.yml services: app.twig.app_extension: class: AppBundle\Twig\AppExtension arguments: ["@markdown"] public: false tags: - name: twig.extension generated on September, 0 Chapter : Template

27 Chapter Form I form sono uno dei componenti più abusati di Symfony; questo è dovuto sia al suo vasto campo di applicazione sia alla sua lista infinita di funzionalità. In questo capitolo, mostreremo alcune best practices in modo da poterli sfruttare al meglio. Creazione dei form Definire i form come classi PHP. Il componente Form consente di creare form direttamente dal controllore. A meno che non si voglia riusare il form da qualche altra parte, quest'abitudine non è del tutto sbagliata. Nonostante ciò, per form più complessi da poter riutilizzare in altri controllori si raccomanda di definire ogni form nella propria classe PHP: Listing namespace AppBundle\Form; use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class PostType extends AbstractType public function buildform(formbuilderinterface $builder, array $options) $builder ->add('title') ->add('summary', 'textarea') ->add('content', 'textarea') ->add('author ', ' ') ->add('publishedat', 'datetime') ; public function setdefaultoptions(optionsresolverinterface $resolver) generated on September, 0 Chapter : Form

28 0 $resolver->setdefaults(array( 'data_class' => 'AppBundle\Entity\Post' )); public function getname() return 'post'; Per creare il form, chiamare il metodo createform e instanziare la nuova classe: Listing - 0 use AppBundle\Form\PostType; public function newaction(request $request) $post = new Post(); $form = $this->createform(new PostType(), $post); Registrazione dei form come servizi È possibile registrare i tipi di form come servizi, anche se non si consiglia di farlo a meno che non si pianifichi di riusare lo stesso form in altri posti o di incorporarlo all'interno di altri form, usando il tipo collection. Per la maggior parte dei casi in cui il form viene usato solo per modifica o creazione, la registrazione come servizio è eccessiva e rende più difficile capire esattamente quale classe sia usata nel controllore. Configurazione dei bottoni Le classe dei form dovrebbe essere agnostica rispetto a dove viene utilizzata. In questo modo, i form possono essere riusati più facilmente. Aggiungere i bottoni nel template, non nelle classi dei form o nei controllori. A partire da Symfony. è possibile aggiugere campi button all'interno del form. Il vantaggio è che si semplifica il codice del template che visualizza il form. Lo svantaggio è che aggiungere il bottone alla classe form ne limita la sua riusabilità. Listing - class PostType extends AbstractType public function buildform(formbuilderinterface $builder, array $options) $builder ->add('save', 'submit', array('label' => 'Create Post')) ; generated on September, 0 Chapter : Form

29 0 Questo form potrebbe essere stato progettato per la creazione di post, ma, se si volesse riusarlo anche per la modifica, la label del bottone sarebbe sbagliata. Alcuni sviluppatori configurano invece i bottoni del form nel controllore: Listing namespace AppBundle\Controller\Admin; use Symfony\Component\HttpFoundation\Request; use Symfony\Bundle\FrameworkBundle\Controller\Controller; use AppBundle\Entity\Post; use AppBundle\Form\PostType; class PostController extends Controller public function newaction(request $request) $post = new Post(); $form = $this->createform(new PostType(), $post); $form->add('submit', 'submit', array( 'label' => 'Crea', 'attr' => array('class' => 'btn btn-default pull-right') )); Anche questa soluzione è sbagliata, perché si sta mischiando codice markup relativo alla presentazione (etichette, classi CSS, ecc.) con codice PHP. La separazione delle competenze è una buona regola da seguire sempre, quindi tutto ciò che è relativo alla vista deve essere messo nel livello della vista: Listing - form_start(form) form_widget(form) <input type="submit" value="create" class="btn btn-default pull-right" /> form_end(form) Rendere il Form Symfony mette a disposizione diversi modi per rendere un form, dal rendere tutto il form con un unico comando al rendere ogni singolo campo in modo indipendente. Il modo migliore dipende dalla quantità di personalizzazione necessaria nel form. Il modo più semplice, utile specialmente durante lo sviluppo, è la funzione form_widget() per rendere tutti i campi insieme: Listing - generated on September, 0 Chapter : Form

30 form_start(form, 'attr': 'class': 'my-form-class' ) form_widget(form) form_end(form) Se si ha bisogno di un controllo più preciso sulla renderizzazione del form non usare la funzione form_widget(form) e rendere i campi individualmente. Cnsultare la ricetta Personalizzare la resa dei form per maggiori informazioni su come rendere i form e su come impostare un tema in modo globale. Gestire l'invio La gestione di un form in Symonfy generalmente segue la seguente struttura: Listing - 0 public function newaction(request $request) // costruire il form... $form->handlerequest($request); if ($form->issubmitted() && $form->isvalid()) $em = $this->getdoctrine()->getmanager(); $em->persist($post); $em->flush(); return $this->redirect($this->generateurl( 'admin_post_show', array('id' => $post->getid()) )); // rendere il template Nel codice precedente è importante evidenziare due cose. In primo luogo, si raccomanda di usare un'unica azione sia per rendere il form che per la gestione dell'invio. Per esempio, si potrebbe avere newaction solo per rendere il form e createaction solo per gestire l'invio. Entrambe le azioni però sono quasi identiche, quindi è più semplice lasciare che sia newaction a gestire il tutto. In secondo luogo si raccomand di usare $form->issubmitted() nel costrutto if, per rendere il codice più chiaro. Tecnicamente non è necessario, dato che isvalid() esegue prima issubmitted(). Senza questo, tuttavia, il flusso risulterebbe un po' strano e il form sembrerebbe sempre processato, anche per le richieste GET. TIpi di campo personalizzati Aggiungere il prefisso app_ ai campi personalizzati, per evitare collisioni. I tipi di campo personalizzati ereditano dalla classe AbstractType, che definisce il metodo getname() per configurare il nome del tipo. Tali nomi devono essere univoci nell'applicazione. Se un tipo personalizzato usa lo stesso nome di uno dei tipi di Symfony, lo sovrascriverà. Lo stesso accade quando il tipo personalizzato corrisponde a un qualsiasi tipo definito da bundle di terze parti installati nell'applicazione. Aggiungere il prefisso app_ ai campi personalizzati, per evitare collisioni che potrebbero portare a errori. generated on September, 0 Chapter : Form 0

31 Chapter Internationalizzazione L'internazionalizzazione e la localizzazione hanno come obiettivo quello di adattare l'applicazione e il suo contenuto ad una specifica nazione o alla lingua dei suoi utenti. In Symfony questa funzionalità è opzionale e per poter essere utilizzata bisogna prima abilitarla. Per farlo, scommentare l'opzione di configurazione translator, impostando il locale dell'applicazione: Listing - # app/config/config.yml framework: #... translator: fallback: "%locale%" # app/config/parameters.yml parameters: #... locale: it Formato dei file di traduzione Il componente Translation di Symfony supporta diversi formati di file di traduzione: PHP, Qt,.po,.mo, JSON, CSV, INI, ecc. Usare il formato XLIFF per i file di traduzione. Fra tutti i formati di traduzione disponibili solo XLIFF e gettext sono ampiamente supportati nei tool usati dai traduttori professionali. Poiché XLIFF è basato su XML, è possibile validare il contenuto del file appena viene creato. Symfony. ha aggiunto il supporto per le note e commenti all'interno dei file XLIFF, rendendoli più amichevoli per i traduttori. Dato che una buona traduzione dipende fortemente dal contesto, le note del formato XLIFF rappresentano il modo migliore per contenere queste informazioni. generated on September, 0 Chapter : Internationalizzazione

32 Il bundle JMSTranslationBundle, sotto licenza Apache, fornisce un'interfaccia web per la visualizzazione e la modifica dei file di traduzione. Inoltre dispone di uno strumento avanzato in grado di leggere il progetto, estrarre il testo da tradurre dai template e automaticamente aggiornare i file XLIFF. Posizione dei file di traduzione Mettere i file di traduzione nella cartella app/resources/translations/ Solitamente, gli sviluppatori Symfony mettevano questi file nella cartella Resources/translations/ di ogni bundle. Poiché la cartella app/resources/ è considerata la posizione globale delle risorse dell'applicazione, mettendo le traduzioni in app/resources/translations, esse risulteranno centralizzate e prioritarie su ogni altro file di traduzione. Questo consentirà di effettuare l'override delle traduzioni definite nei bundle di terze parti. Chiavi per le traduzioni Per le traduzioni usare sempre chiavi invece di contenuti stringa. Usare le chiavi semplifica la gestione dei file di traduzione, poiché è possibile modificare il contenuto della lingua originale, senza la necessità di aggiornare tutti i file di tutte le lingue. Le chiavi dovrebbero sempre descrivere il loro scopo e non la loro posizione. Per esempio, se un form ha un campo con l'etichetta "Username", una chiave idonea sarà label.username e non edit_form.label.username. Esempio di file di traduzione Applicando tutte le best practice precedenti, un file di traduzione di esempio per la lingua inglese sarà: Listing - 0 <!-- app/resources/translations/messages.en.xliff --> <?xml version=".0"?> <xliff version="." xmlns="urn:oasis:names:tc:xliff:document:."> <file source-language="en" target-language="it" datatype="plaintext" original="file.ext"> <body> <trans-unit id=""> <source>title.post_list</source> <target>elenco dei post</target> </trans-unit> </body> </file> </xliff>. generated on September, 0 Chapter : Internationalizzazione

33 Chapter Sicurezza Autenticazione e firewall (recuperare le credenziali dell'utente) Per autenticare gli utenti è possibile configurare Symfony in molti modi. Inoltre è possibile caricare le informazioni degli utenti da qualsiasi fonte. Questo è un argomento abbastanza complesso, per maggiori informazioni si rimanda alla sezione sicurezza del ricettario. A prescindere dalle necessità, l'autenticazione è configurata in security.yml, sotto la voce firewalls. La maggior parte delle applicazioni utilizza solamente un meccanismo di autenticazione e un insieme di utenti. Per questa tipologia di applicazioni basta soltanto un unico firewall. Ovviamente esistono delle eccezioni, ad esempio quando in un sito si devono proteggere delle API dalla sezione web. L'importante è mantenere le cose semplici. Si dovrebbe inoltre abilitare sempre l'opzione anonymous nel firewall. Se si ha bisogno che gli utenti accedano a sezioni differenti del sito (o forse a tutte le sezioni), utilizzare la configurazione dell'opzione access_control. Usare bcrypt per codificare le password degli utenti. Se si memorizzano le password degli utenti nel sistema, si raccomanda di usare l'encoder bcrypt, invece della tradizionale codifica SHA-. I vantaggi più importanti di bcrypt sono l'inclusione di un valore salt per la protezione contro gli attacchi di tipo rainbow table e la sua natura adattiva, che consente di rallentare la sua esecuzione e resistere meglio agli attacchi di forza bruta. Detto questo, ecco un esempio di autenticazione di un'applicazione che usa un form login per caricare gli utenti dalla base dati: Listing - # app/config/security.yml security: encoders: AppBundle\Entity\User: bcrypt providers: database_users: generated on September, 0 Chapter : Sicurezza

34 0 0 entity: class: AppBundle:User, property: username firewalls: secured_area: pattern: ^/ anonymous: true form_login: check_path: security_login_check login_path: security_login_form logout: path: security_logout target: homepage #... c'è anche access_control, ma non viene mostrato qui Il codice sorgente dell'applicazione di prova include commenti che spiegheranno dettagliatamente ogni parte del file. Autorizzazione (negare l'accesso) Symfony definisce vari modi per configurare l'autorizzazione, inclusa l'opzione access_control in security.yml la e l'uso di isgranted direttamente dal servizio security.authorization_checker. Per la protezione di schemi di URL ampi, usare access_control Dove possibile, usare Per logiche di sicurezza più complesse, usare direttamente il servizio security.authorization_checker Esistono anche diversi modi per centralizzare la logica di autorizzazione, come i votanti e le ACL (o lista di controllo degli accessi). Personalizzare un votante per definire restrizioni a grana fine; Usare le ACL per definire logiche di sicurezza complesse (per gestire l'accesso di ogni oggetto da ogni utente attraverso un'interfaccia di amministrazione). Per controllare l'accesso su un controller usa oltre ad essere di facile lettura essa è collocata sempre sopra ogni azione. In questa applicazione di prova, per creare un nuovo post, è necessario disporre del ruolo ROLE_ADMIN. Usando il codice del controllore sarà: Listing - use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security; generated on September, 0 Chapter : Sicurezza