The Cookbook Version:. generated on September, 0
The Cookbook (.) This work is licensed under the Attribution-Share Alike.0 Unported license (http://creativecommons.org/ 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 (http://github.com/symfony/symfony-docs/issues). Based on tickets and users feedback, this book is continuously updated.
Contents at a Glance Comment utiliser Assetic pour gérer vos ressources... Comment minifier les JavaScripts et les feuilles de style avec YUI Compressor... Comment utiliser Assetic et les fonctions Twig pour optimiser les images... Comment appliquer un filtre Assetic à une extension de fichier spécifique... Comment utiliser les bonnes pratiques pour structurer vos Bundles... Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle... Comment surcharger n'importe quelle partie d'un bundle... Comment supprimer le AcmeDemoBundle... Comment exposer une configuration sémantique pour un Bundle... Comment utiliser Varnish pour accélérer mon site Web... Comment Maîtriser et Créer de nouveaux Environnements... Comment surcharger la structure de répertoires par défaut de Symfony... Comment configurer les paramètres externes dans le conteneur de services... Comment stocker les sessions dans la base de données grâce à PdoSessionStorage... Comment utiliser le routeur Apache... Comment créer une commande pour la Console...0 Comment utiliser la Console... Comment générer des URLs et envoyer des emails depuis la Console... Comment activer les logs dans la commande console... Comment personnaliser les pages d'erreur... Comment définir des contrôleurs en tant que Services... Comment optimiser votre environnement pour le debuggage... Déployer une application Symfony... Comment gérer les uploads de fichier avec Doctrine... Comment utiliser les extensions Doctrine: Timestampable, Sluggable, Translatable, etc... Comment enregistrer des listeners («écouteurs» en français) et des souscripteurs d'évènement...0 Comment utiliser la couche DBAL de Doctrine... Comment générer des Entités à partir d'une base de données existante... Comment travailler avec plusieurs gestionnaires d'entités et connexions... Comment définir des fonctions DQL personnalisées... 0 Comment définir des Relations avec des Classes Abstraites et des Interfaces... 0 Comment implémenter un simple formulaire de création de compte... 0 Comment envoyer un Email... Comment utiliser Gmail pour envoyer des Emails... Comment travailler avec les Emails pendant le Développement... Comment utiliser le «Spool» d'email... generated on September, 0 Contents at a Glance iii
Comment mettre en place des filtres avant et après un processus donné... Comment étendre une Classe sans utiliser l'héritage... Comment personnaliser le Comportement d'une Méthode sans utiliser l'héritage... Comment personnaliser le rendu de formulaire... Comment utiliser les Convertisseurs de Données... 0 Comment modifier dynamiquement les formulaires en utilisant les évènements... Comment imbriquer une Collection de Formulaires... Comment Créer un Type de Champ de Formulaire Personnalisé... Comment créer une extension de type de formulaire... Comment réduire la duplication de code avec "inherit_data"... 0 Comment tester unitairement vos formulaires... Comment configurer des données vierges pour une classe de Formulaire... Comment utiliser la fonction submit() pour gérer les soumissions de formulaires... 0 Comment utiliser l'option de Champ de Formulaire Virtual... Comment utiliser Monolog pour écrire des Logs... Comment configurer Monolog pour envoyer les erreurs par Email... 00 Comment loguer des messages dans différents fichiers... 0 Comment créer un Collecteur de Données personnalisé... 0 Comment déclarer un nouveau Format de Requête et un Type Mime... 0 Comment forcer les routes à toujours utiliser HTTPS ou HTTP... 0 Comment autoriser un caractère «/» dans un paramètre de route... Comment configurer une redirection vers une autre route sans contrôleur personnalisé... Comment utiliser des méthodes HTTP autres que GET et POST dans les routes... Comment utiliser des paramètres du conteneur de services dans vos routes... Comment charger les utilisateurs depuis la base de données (le fournisseur d'entité)... Comment ajouter la fonctionnalité de login «Se souvenir de moi»... Comment implémenter votre propre Voteur pour ajouter des adresses IP sur une liste noire... 0 Comment utiliser les Access Control Lists (ACLs) («liste de contrôle d'accès» en français)... Comment utiliser les concepts d'acl avancés... Comment forcer HTTPS ou HTTP pour des URLs Différentes... Comment personnaliser votre formulaire de login... Comment sécuriser n'importe quel service ou méthode de votre application... Comment créer un Fournisseur d'utilisateur personnalisé... 0 Comment créer un Fournisseur d'authentification Personnalisé... Comment changer le comportement par défaut du chemin cible... Comment utiliser le Serializer... Comment créer un «listener» («écouteur» en français) d'évènement... Comment travailler avec les champs d'applications («scopes» en anglais)... Comment travailler avec les Passes de Compilation dans les Bundles... Exemple de Session Proxy... Faire que la Locale soit "persistente" durant la session de l'utilisateur... Configurer le Dossier où les Fichiers pour les Sessions sont Enregistrés... 0 Combler une application legacy avec les sessions de Symfony... En quoi Symfony diffère de Symfony... Comment injecter des variables dans tous les modèles (i.e. Variables Globales)... 0 Comment utiliser et enregistrer des chemins Twig namespacés... Comment utiliser PHP plutôt que Twig dans les templates... iv Contents at a Glance Contents at a Glance
Comment écrire une Extension Twig personnalisée... Comment rendre un template sans passer par un contrôleur... 0 Comment simuler une authentification HTTP dans un Test Fonctionnel... 0 Comment simuler une authentification avec un token dans un test fonctionnel... 0 Comment tester les interactions de multiples clients... 0 Comment utiliser le Profiler dans un test fonctionnel... 0 Comment tester du code interagissant avec une base de données... Comment tester les dépôts Doctrine... Comment personnaliser le processus de bootstrap avant les tests... Comment créer une Contrainte de Validation Personnalisée... Comment créer des web services SOAP à l'intérieur d'un contrôleur Symfony... Comment créer et stocker un projet Symfony dans git... Comment créer et stocker un projet Symfony dans Subversion... 0 generated on September, 0 Contents at a Glance v
Chapter Comment utiliser Assetic pour gérer vos ressources Assetic associe deux concepts majeurs : les ressources et les filtres. Les ressources sont des fichiers comme les feuilles de style, les JavaScript et les images. Les filtres peuvent être appliqués à ces fichiers avant qu'ils ne soient servis au navigateur. Cela permet de gérer séparément les fichiers ressources qui sont stockés par l'application des fichiers qui sont réellement présentés à l'utilisateur. Sans Assetic, vous servez directement les fichiers qui sont stockés dans votre application : Listing - <script src=" asset('js/script.js') " type="text/javascript" /> Mais avec Assetic, vous pouvez manipuler ces ressources de la manière dont vous le désirez (ou les charger de n'importe où) avant de les servir. Cela signifie que vous pouvez : Minifier et combiner toutes vos CSS ou vos fichiers JavaScript Exécuter tous (ou juste une partie) vos fichiers CSS ou JS en passant par des compilateurs comme LESS, SASS ou CoffeeScript. Optimiser vos images Ressources Utiliser Assetic plutôt que servir les fichiers directement offre de nombreux avantages. Les fichiers n'ont pas besoin d'être stockés là où il seront servis, et peuvent provenir de plusieurs sources, notamment d'un bundle. Vous pouvez utiliser Assetic pour vos fichiers CSS ou Javascript Le principe est identique entre les deux à l'exception d'une syntaxe qui différe légèrement. Inclure des fichiers Javascript Pour inclure des fichiers Javascript, utilisez le tag javascripts dans n'importe quel template. On va en général s'en servir dans le block javascripts, si vous utilisez les noms de block par défaut de la Distribution Standard de Symfony : generated on September, 0 Chapter : Comment utiliser Assetic pour gérer vos ressources
Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' % <script type="text/javascript" src=" asset_url "></script> % endjavascripts % Vous pouvez aussi inclure vos feuilles de style: voir Inclure des fichiers CSS. Dans cet exemple, tous les fichiers du dossier Resources/public/js/ du bundle AcmeFooBundle vont être chargés et servis depuis un autre endroit. Le tag réellement affiché pourrait ressembler à: Listing - <script src="/app_dev.php/js/abcd.js"></script> C'est un point clé: Une fois que vous avez laissé Assetic gérer vos ressources, les fichiers sont servis depuis un autre endroit. Ceci pourra provoquer des problèmes pour les fichiers CSS contenant des chemins relatifs pour leurs images. Voir Corriger les chemins CSS avec le filtre cssrewrite. Inclure des fichiers CSS Pour vos feuilles de styles CSS, vous pouvez utiliser la même méthodologie mais avec le tag stylesheets. Si vous utilisez les block par défaut de la Distribution Standard, ce tag prendra place dans un block stylesheets : Listing - % stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' % <link rel="stylesheet" href=" asset_url " /> % endstylesheets % Mais comme Assetic modifie les chemins de vos ressources, les images de fond (ou autres) qui utilisent des chemins relatifs se retrouveront cassés, sauf si vous utilisez le filtre cssrewrite. Remarquez que dans le premier exemple qui inclut les fichiers javascripts, vous faites référence aux fichiers avec un chemin comme suit : @AcmeFooBundle/Resources/public/file.js, mais dans celui-ci, vous faites référence aux fichiers CSS avec leur vrai chemin public : bundles/acme_foo/ css. Vous pouvez utiliser l'un ou l'autre. Sachez juste qu'il existe un problème connu qui peut faire échouer le filtre cssrewrite avec la syntaxe @AcmeFooBundle. Corriger les chemins CSS avec le filtre cssrewrite Vu que Assetic génère de nouvelles URLs pour vos ressource, tous les chemins relatifs dans vos fichiers CSS vont être cassés. Pour corriger ça, assurez-vous d'utiliser le filtre cssrewrite avec votre tag stylesheets. Il va parser votre CSS et corriger les chemins pour prendre en compte le nouvel emplacement. Vous pouvez voir un exemple dans la section précédente : Quand vous utilisez le filtre cssrewrite, ne faites pas à appel à vos CSS avec la syntaxe @AcmeFooBundle. Pour plus de détails, voir la note dans la section du dessus. generated on September, 0 Chapter : Comment utiliser Assetic pour gérer vos ressources
Combiner des ressources Vous pouvez aussi combiner plusieurs fichiers en un seul. Cela aide à réduire le nombre de requêtes HTTP, ce qui est très important pour les performances. Cela vous permet aussi de maintenir les fichiers plus facilement en les découpants en petites parties plus faciles à gérer. Cela peut être un plus pour la réusabilité de votre projet puisque vous pouvez facilement séparer les fichiers spécifiques au projet des fichiers qui peuvent être réutilisés dans d'autres applications, mais toujours les servir comme un fichier unique : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' '@AcmeBarBundle/Resources/public/js/form.js' '@AcmeBarBundle/Resources/public/js/calendar.js' % <script src=" asset_url "></script> % endjavascripts % En environnement de dev, chaque fichier est toujours servi individuellement pour que vous puissiez débugguer plus facilement. Cependant, en environnement de prod (ou plus précisément, quand l'option debug est à false), ils seront affichés dans une unique balise script qui contiendra le contenu de tous vos fichiers JavaScript. Si vous découvrez Assetic et essayez d'utiliser votre application en environnement de prod (en utilisant le contrôleur app.php), vous verrez probablement que vos CSS et JS plantent. Pas de panique! C'est fait exprès. Pour plus de détails sur l'utilisation d'assetic en environnement de prod, lisez Exporter les ressources. Et combiner les fichiers ne s'applique pas uniquement à vos fichiers. Vous pouvez aussi utiliser Assetic pour combiner les ressources tierces, comme jquery, à vos fichiers dans un fichier unique : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js' '@AcmeFooBundle/Resources/public/js/*' % <script src=" asset_url "></script> % endjavascripts % Filtres Une fois qu'elles sont gérées par Assetic, vous pouvez appliquer des filtres à vos ressources avant qu'elles ne soient servies. Cela inclut les filtres qui compressent vos ressources pour réduire la taille des fichiers (pour de meilleures performances). D'autres filtres peuvent compiler des fichiers CoffeeScript en JavaScript ou convertir vos fichiers SASS en CSS. En fait, Assetic possède une longue liste de filtres disponibles. Plusieurs de ces filtres ne font pas le travail directement, mais utilisent des bibliothèques tierces pour faire le gros du travail. Cela signifie que vous devrez souvent installer une bibliothèque tierce pour utiliser un filtre. Le grand avantage d'utiliser Assetic pour faire appel à ces bibliothèques (plutôt que de les utiliser directement) est qu'au lieu de les exécuter à la main après avoir modifié les fichiers, Assetic prendra tout en charge pour vous, et supprimera définitivement cette étape du processus de développement et de déploiement. Pour utiliser un filtre, vous aurez d'abord besoin de le spécifier dans la configuration d'assetic. Ajouter un filtre dans la configuration ne signifie pas qu'il est utilisé, mais juste qu'il est prêt à l'être (vous allez l'utiliser ci-dessous). Par exemple, pour utiliser le JavaScript YUI Compressor, la configuration suivante doit être ajoutée : generated on September, 0 Chapter : Comment utiliser Assetic pour gérer vos ressources
Listing - # app/config/config.yml assetic: filters: yui_js: jar: "%kernel.root_dir%/resources/java/yuicompressor.jar" Maintenant, pour vraiment utiliser le filtre sur un groupe de fichiers JavaScript, ajoutez ce code dans votre template : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' % <script src=" asset_url "></script> % endjavascripts % Vous pouvez trouver un guide plus détaillé sur la configuration et l'utilisation des filtres Assetic ainsi que des informations sur le mode debug d'assetic en lisant Comment minifier les JavaScripts et les feuilles de style avec YUI Compressor. Contrôler l'url utilisée Si vous le souhaitez, vous pouvez contrôler les URLs générées par Assetic. Cela se fait dans le template, et le chemin est relatif par rapport à la racine publique : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' % <script src=" asset_url "></script> % endjavascripts % Symfony contient également une méthode pour le cache busting (technique empêchant la mise en cache), où l'url générée par Assetic contient un paramètre qui peut être incrémenté, via la configuration, à chaque déploiement. Pour plus d'informations, lisez l'option de configuration assets_version. Exporter les ressources En environnement de dev, Assetic génère des chemins vers des fichiers CSS et JavaScript qui n'existent pas physiquement sur votre ordinateur. Mais ils sont néanmoins affichés car un contrôleur interne de Symfony ouvre les fichiers et sert leur contenu (après avoir exécuté tous les filtres). Cette manière dynamique de servir des ressources traitées est géniale car cela signifie que vous pouvez immédiatement voir les modifications que vous apportez à vos fichiers. Mais l'inconvénient est que cela peut parfois être un peu lent. Si vous utilisez beaucoup de filtres, cela peut être carrément frustrant. Heureusement, Assetic fournit un moyen pour exporter vos ressources vers des fichiers réels au lieu de les générer dynamiquement. Exporter les ressources en environnement de prod En environnement de prod, vos fichiers JS et CSS sont représentés chacun par une balise unique. En d'autres termes, plutôt que de voir chacun des fichiers JavaScript que vous incluez dans votre code source, vous verrez quelque chose comme ceci : Listing -0 generated on September, 0 Chapter : Comment utiliser Assetic pour gérer vos ressources
<script src="/app_dev.php/js/abcd.js"></script> De plus, ce fichier n'existe pas vraiment et n'est pas non plus affiché dynamiquement par Symfony (car les ressources sont en environnement de dev). C'est fait exprès : laisser Symfony générer ces fichiers dynamiquement en production serait tout simplement trop lent. Au lieu de cela, chaque fois que vous exécutez votre application dans l'environnement de prod (et par conséquent, chaque fois que vous déployez), vous devriez exécuter la commande suivante : Listing - $ php app/console assetic:dump --env=prod --no-debug Cela génèrera et écrira physiquement chaque fichier dont vous avez besoin (ex /js/abcd.js). Si vous mettez à jour vos ressources, vous aurez besoin de relancer cette commande pour regénérer vos fichiers. Exporter les ressources en environnement de dev Par défaut, chaque chemin de ressource généré en environnement de dev est pris en charge dynamiquement par Symfony. Cela n'a pas d'inconvénient (vous pouvez voir vos changements immédiatement), sauf que les ressources peuvent être lentes à charger. Si vous trouvez que vos ressources sont chargés trop lentement, suivez ce guide. Premièrement, dites à Symfony de ne plus essayer de traiter ces fichiers dynamiquement. Apportez les modifications suivantes dans le fichier config_dev.yml : Listing - # app/config/config_dev.yml assetic: use_controller: false Ensuite, puisque Symfony ne génère plus ces fichiers pour vous, vous aurez besoin de les exporter manuellement. Pour ce faire, lancez la commande suivante : Listing - $ php app/console assetic:dump Elle écrit physiquement tous les fichiers de ressource dont vous avez besoin pour l'environnement de dev. Le gros inconvénient est que vous devrez faire cela chaque fois que vous modifiez une ressource. Heureusement, en passant l'option --watch, la commande regénèrera automatiquement les ressources modifiées : Listing - $ php app/console assetic:dump --watch Lancer cette commande en environnement de dev peut générer un florilège de fichiers. Pour conserver votre projet bien organisé, il peut être intéressant de mettre les fichiers générés dans un répertoire séparé (ex /js/compiled) : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' % <script src=" asset_url "></script> % endjavascripts % generated on September, 0 Chapter : Comment utiliser Assetic pour gérer vos ressources 0
Chapter Comment minifier les JavaScripts et les feuilles de style avec YUI Compressor Yahoo! fournit un excellent utilitaire pour minifier les JavaScripts et les feuilles de style pour qu'elles soient plus rapides à charger, YUI Compressor. Grâce à Assetic, vous pourrez tirer profit de cet outil très facilement. Téléchargez le JAR YUI Compressor YUI Compressor est écrit en Java est distribué sous forme de JAR. Téléchargez le JAR sur le site de Yahoo! et enregistrez le sous app/resources/java/yuicompressor.jar. Configurez les filtres YUI Maintenant vous devez configurer les deux filtres Assetic dans votre application, l'un pour minifier les JavaScripts avec YUI Compressor et l'autre pour minifier les feuilles de style : Listing - # app/config/config.yml assetic: # java: "/usr/bin/java" filters: yui_css: jar: "%kernel.root_dir%/resources/java/yuicompressor.jar" yui_js: jar: "%kernel.root_dir%/resources/java/yuicompressor.jar". http://developer.yahoo.com/yui/compressor/. http://yuilibrary.com/projects/yuicompressor/ generated on September, 0 Chapter : Comment minifier les JavaScripts et les feuilles de style avec YUI Compressor
Les utilisateurs de Windows ne doivent pas oublier de mettre à jour l'emplacement de Java. Dans Windows x bit, il s'agit de C:\Program Files (x)\java\jre\bin\java.exe par défaut Vous avez maintenant accès aux deux nouveaux filtres Assetic dans votre application : yui_css et yui_js. Ils utiliseront YUI Compressor pour minifier respectivement les feuilles de style et les JavaScripts. Minifiez vos Ressources Maintenant YUI Compressor est configuré, mais rien ne se passera tant que vous n'appliquez pas ces filtres à une ressource (asset). Puisque vos ressources font partie de la couche Vue, ce travail doit être fait dans vos templates : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' % <script src=" asset_url "></script> % endjavascripts % L'exemple ci-dessus part du principe que vous avez un bundle appelé AcmeFooBundle et que vos fichiers JavaScript se trouvent dans le répertoire Resources/public/js dans votre bundle. Ce n'est, en fait, pas très important car vous pouvez inclure vos fichiers JavaScript où vous le voulez. En rajoutant le filtre yui_js à la ressource ci-dessus, vous devriez voir que les JavaScripts minifiés sont chargés beaucoup plus rapidement. Le même procédé peut être utilisé pour minifier vos feuilles de style. Listing - % stylesheets '@AcmeFooBundle/Resources/public/css/*' filter='yui_css' % <link rel="stylesheet" type="text/css" media="screen" href=" asset_url " /> % endstylesheets % Désactiver la minification en Mode Debug Les JavaScripts et feuilles de styles minifiés sont très difficiles à lire; et encore moins à débugguer. Pour palier cela, Assetic vous permet de désactiver un filtre lorsque votre application est en mode debug. Vous pouvez faire cela en préfixant le nom du filtre dans votre template par un point d'interrogation :?. Cela indique à Assetic de n'appliquer les filtres que si le mode debug n'est pas actif. Listing - % javascripts '@AcmeFooBundle/Resources/public/js/*' filter='?yui_js' % <script src=" asset_url "></script> % endjavascripts % Plutôt que d'ajouter le filtre à vos balises assets, vous pouvez aussi l'activer de façon globale en ajoutant l'attribut apply-to à la configuration du filtre, par exemple apply_to: "\.js$" pour le filtre yui_js. Pour que le filtre ne s'applique qu'en production, ajoutez le au fichier config_prod au lieu du fichier de configuration commun. Pour plus de détails sur comment appliquer des filtres en fonction des extensions de fichiers, lisez Filtrer en se basant sur les extensions. generated on September, 0 Chapter : Comment minifier les JavaScripts et les feuilles de style avec YUI Compressor
Chapter Comment utiliser Assetic et les fonctions Twig pour optimiser les images Parmi ses nombreux filtres, Assetic possède quatre filtres qui peuvent être utilisés pour optimiser les images à la volée. Cela vous permet de tirer profit de tailles de fichiers réduites sans utiliser d'éditeur d'image pour réduire chaque image. Les résultats sont mis en cache et peuvent être réutilisés en production pour qu'il n'y ait pas d'impact sur les performances pour vos utilisateurs finaux. Utiliser Jpegoptim Jpegoptim est un utilitaire pour optimiser les fichiers JPEG. Pour l'utiliser avec Assetic, ajoutez le bout de code suivant à votre configuration Assetic : Listing - # app/config/config.yml assetic: filters: jpegoptim: bin: path/to/jpegoptim Notez que pour utiliser jpegoptim, il faut qu'il soit déjà installé sur votre système. L'option bin pointe vers le fichier binaire compilé. Il peut maintenant être utilisé dans un template : Listing - % image '@AcmeFooBundle/Resources/public/images/example.jpg' filter='jpegoptim' output='/images/example.jpg' % <img src=" asset_url " alt="example"/> % endimage %. http://www.kokkonen.net/tjko/projects.html generated on September, 0 Chapter : Comment utiliser Assetic et les fonctions Twig pour optimiser les images
Supprimer toutes les données EXIF Par défaut, appliquer ce filtre ne supprime que certaines meta-informations du fichier. Les données EXIF et les commentaires ne sont pas supprimés, mais vous pouvez les supprimer en utilisant l'option strip_all : Listing - # app/config/config.yml assetic: filters: jpegoptim: bin: path/to/jpegoptim strip_all: true Réduire la qualité maximum Le niveau de qualité du JPEG n'est pas modifié par défaut. Vous pouvez réduire un peu la taille des images en définissant un niveau de qualité maximum plus bas que le niveau actuel. Cela se fera évidemment au détriment de la qualité de l'image : Listing - # app/config/config.yml assetic: filters: jpegoptim: bin: path/to/jpegoptim max: 0 Fonctions Twig : syntaxe courte Si vous utilisez Twig, il est possible de faire tout ceci avec une syntaxe raccourcie en activant et en utilisant une fonction spéciale Twig. Commencez par ajouter la configuration suivante : Listing - # app/config/config.yml assetic: filters: jpegoptim: bin: path/to/jpegoptim twig: functions: jpegoptim: ~ Le template Twig peut maintenant être modifié comme suit : Listing - <img src=" jpegoptim('@acmefoobundle/resources/public/images/example.jpg') " alt="example"/> Vous pouvez spécifier le répertoire cible dans la configuration de la manière suivante : Listing - # app/config/config.yml assetic: filters: jpegoptim: bin: path/to/jpegoptim twig: generated on September, 0 Chapter : Comment utiliser Assetic et les fonctions Twig pour optimiser les images
functions: jpegoptim: output: images/*.jpg generated on September, 0 Chapter : Comment utiliser Assetic et les fonctions Twig pour optimiser les images
Chapter Comment appliquer un filtre Assetic à une extension de fichier spécifique Les filtres Assetic peuvent être appliqués à des fichiers individuels, à des groupes de fichiers ou même, comme vous allez le voir ici, à des fichiers qui ont une extension spécifique. Pour vous montrer comment gérer chaque cas, supposons que vous ayez le filtre Assetic CoffeeScript qui compile les fichiers CoffeeScript en JavaScript. La configuration principale contient juste les chemins vers coffee et node. Leurs valeurs par défaut respectives sont /usr/bin/coffee et /usr/bin/node: Listing - # app/config/config.yml assetic: filters: coffee: bin: /usr/bin/coffee node: /usr/bin/node Filtrer un fichier unique Vous pouvez maintenant compiler un fichier unique CoffeeScript en JavaScript depuis vos templates : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/example.coffee' filter='coffee' % <script src=" asset_url " type="text/javascript"></script> % endjavascripts % C'est tout ce dont vous avez besoin pour compiler ce fichier CoffeeScript et le servir comme JavaScript compilé. generated on September, 0 Chapter : Comment appliquer un filtre Assetic à une extension de fichier spécifique
Filtrer des fichiers multiples Vous pouvez aussi combiner plusieurs fichiers CoffeeScript en un unique fichier en sortie : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/example.coffee' '@AcmeFooBundle/Resources/public/js/another.coffee' filter='coffee' % <script src=" asset_url " type="text/javascript"></script> % endjavascripts % Les deux fichiers seront maintenant servis comme un unique fichier compilé en JavaScript. Filtrer en se basant sur les extensions Un des plus grands avantages d'assetic est de pouvoir réduire le nombre de ressources pour réduire le nombre de requêtes HTTP. Dans le but d'en tirer le plus grand avantage possible, il pourrait être intéressant de combiner tous vos fichiers CoffeeScript et JavaScript ensembles puisqu'ils seront finalement délivrés comme JavaScript. Malheureusement, se contenter d'ajouter les fichiers JavaScript aux fichiers à combiner ne fonctionnera pas car le JavaScript ne passera pas la compilation CoffeeScript. Ce problème peut être évité en ajoutant l'option apply_to à la configuration, ce qui vous permettra de spécifier qu'un filtre devra toujours être appliqué à une extension de fichier particulière. Dans ce cas, vous pouvez spécifier que le filtre Coffee s'applique à tous les fichiers.coffee : Listing - # app/config/config.yml assetic: filters: coffee: bin: /usr/bin/coffee node: /usr/bin/node apply_to: "\.coffee$" Avec cela, vous n'avez plus besoin de spécifier le filtre coffee dans le template. Vous pouvez aussi lister les fichiers JavaScript classique, chacun d'eux sera combiné et délivré en un unique fichier JavaScript (seuls les fichiers.coffee passeront à travers le filtre CoffeeScript) : Listing - % javascripts '@AcmeFooBundle/Resources/public/js/example.coffee' '@AcmeFooBundle/Resources/public/js/another.coffee' '@AcmeFooBundle/Resources/public/js/regular.js' % <script src=" asset_url " type="text/javascript"></script> % endjavascripts % generated on September, 0 Chapter : Comment appliquer un filtre Assetic à une extension de fichier spécifique
Chapter Comment utiliser les bonnes pratiques pour structurer vos Bundles Un bundle est un répertoire qui a une structure bien définie et qui peut héberger à peu près tout : des classes aux contrôleurs en passant par les ressources web. Même si les bundles sont très flexibles, vous devriez suivre quelques unes des bonnes pratiques si vous voulez les distribuer. Nom du Bundle Un bundle est aussi un espace de noms PHP. Ce dernier doit suivre les standards d'intéropérabilité technique pour les espaces de noms PHP. et les noms de classes : il commence par un segment «vendor», suivi par zéro ou plusieurs segments catégories, et il se termine par le nom raccourci de l'espace de noms, qui doit finir par un suffixe Bundle. Un espace de noms devient un bundle aussitôt que vous lui ajoutez une classe bundle. Le nom de la classe bundle doit suivre ces règles simples : Utiliser uniquement des caractères alphanumériques et des tirets bas («underscore» en anglais) ; Utiliser un nom en notation dite «CamelCase» ; Utiliser un nom court et descriptif (pas plus de mots) ; Préfixer le nom avec la concaténation du «vendor» (et optionnellement l'espace de noms de la catégorie) ; Suffixer le nom avec Bundle. Vous trouverez ci-dessous des espaces de noms de bundle et des noms de classes valides : Espace de noms Acme\Bundle\BlogBundle Acme\Bundle\Social\BlogBundle Nom de la Classe Bundle AcmeBlogBundle AcmeSocialBlogBundle. http://www.php-fig.org/psr/psr-0/fr/ generated on September, 0 Chapter : Comment utiliser les bonnes pratiques pour structurer vos Bundles
Espace de noms Acme\BlogBundle Nom de la Classe Bundle AcmeBlogBundle Par convention, la méthode getname() de la classe bundle devrait retourner le nom de la classe. Si vous partagez publiquement votre bundle, vous devez utiliser le nom de la classe bundle comme nom de dépôt (AcmeBlogBundle et non pas BlogBundle par exemple). Les Bundles du coeur de Symfony ne préfixent pas la classe Bundle avec Symfony et ajoutent toujours un sous-espace de noms Bundle ; par exemple : FrameworkBundle. Chaque bundle possède un alias, qui est la version raccourcie en miniscules du nom du bundle en utilisant des tirets bas (acme_hello pour AcmeHelloBundle, ou acme_social_blog pour Acme\Social\BlogBundle par exemple). Cet alias est utilisé pour renforcer l'unicité à l'intérieur d'un bundle (voir ci-dessous pour des exemples d'utilisation). Structure de Répertoires La structure basique du répertoire d'un bundle HelloBundle doit être comme suit : Listing - 0 XXX/... HelloBundle/ HelloBundle.php Controller/ Resources/ meta/ LICENSE config/ doc/ index.rst translations/ views/ public/ Tests/ Le(s) répertoire(s) XXX reflète(nt) la structure de l'espace de noms du bundle. Les fichiers suivants sont obligatoires : HelloBundle.php ; Resources/meta/LICENSE: La licence complète pour le code ; Resources/doc/index.rst: Le fichier racine pour la documentation du bundle. Ces conventions assurent que les outils automatisés puissent compter sur cette structure par défaut pour travailler.. http://api.symfony.com/./symfony/bundle/frameworkbundle/frameworkbundle.html generated on September, 0 Chapter : Comment utiliser les bonnes pratiques pour structurer vos Bundles
La profondeur des sous-répertoires devrait être réduite au minimum pour les classes et fichiers les plus utilisés ( niveaux au maximum). Plus de niveaux peuvent être définis pour les fichiers non-stratégiques et moins utilisés. Le répertoire du bundle est en lecture seule. Si vous avez besoin d'écrire des fichiers temporaires, stockezles dans le dossier cache/ ou log/ de l'application hébergeant votre bundle. Des outils peuvent générer des fichiers dans la structure du répertoire du bundle, mais uniquement si les fichiers générés vont faire partie du dépôt. Les classes et fichiers suivants ont des emplacements spécifiques : Type Commandes Contrôleurs Extensions du Conteneur de Services Listeners d'évènements Configuration Ressources Web Fichiers de traduction Templates Tests Unitaires et Fonctionnels Répertoire Command/ Controller/ DependencyInjection/ EventListener/ Resources/config/ Resources/public/ Resources/translations/ Resources/views/ Tests/ Classes La structure du répertoire du bundle est utilisée en tant que hiérarchie d'espace de noms. Par exemple, un contrôleur HelloController est stocké dans Bundle/HelloBundle/Controller/HelloController.php et le nom complet qualifié de la classe est Bundle\HelloBundle\Controller\HelloController. Tous les fichiers et classes doivent suivre les standards de codage de Symfony («coding standards» en anglais). Certaines classes devraient être vues comme des façades et donc être aussi courtes que possible, comme les «Commands», «Helpers», «Listeners» et «Controllers». Les classes se connectant au dispatcher («répartiteur» en français) d'évènements devraient être suffixées avec Listener. Les classes d'exceptions devraient être stockées dans un sous-espace de noms Exception. Vendors Un bundle ne doit pas embarquer de bibliothèques PHP tierces. Il devrait compter sur le chargement automatique («autoloading» en anglais) standard de Symfony à la place. Un bundle ne devrait pas embarquer de bibliothèques tierces écrites en JavaScript, CSS, ou quelconque autre langage. generated on September, 0 Chapter : Comment utiliser les bonnes pratiques pour structurer vos Bundles 0
Tests Un bundle devrait venir avec un ensemble de tests écrits avec PHPUnit et stockés dans le répertoire Tests/. Les tests devraient suivre les principes suivants : La suite de tests doit être exécutable avec une simple commande phpunit lancée depuis une application ; Les tests fonctionnels devraient être utilisés uniquement pour tester la sortie de la réponse et quelques informations de profilage si vous en avez ; Les tests devraient couvrir au moins % de tout votre code. Une suite de test ne doit pas contenir de script AllTests.php, mais doit reposer sur l'existence d'un fichier phpunit.xml.dist. Documentation Toutes les classes et fonctions doivent contenir une PHPDoc complète. Une documentation complète devrait aussi être fournie dans le format restructuredtext, dans le répertoire Resources/doc/ ; le fichier Resources/doc/index.rst est l'unique fichier obligatoire et doit être le point d'entrée de la documentation. Contrôleurs En tant que bonne pratique, les contrôleurs dans un bundle prévu pour être distribué à d'autres ne doivent pas étendre la classe de base Controller. Ils peuvent implémenter ContainerAwareInterface ou étendre ContainerAware à la place. Si vous jetez un oeil aux méthodes de la classe Controller, vous verrez qu'elles ne sont que des raccourcis pratiques pour faciliter la courbe d'apprentissage. Routage Si le bundle fournit des routes, elles doivent être préfixées avec l'alias du bundle. Par exemple, pour un «AcmeBlogBundle», toutes les routes doivent être préfixées avec acme_blog_. Templates Si un bundle fournit des templates, ils doivent utiliser Twig. Un bundle ne doit pas fournir de «layout» principal, excepté s'il fournit une application entièrement fonctionnelle.. http://api.symfony.com/./symfony/bundle/frameworkbundle/controller/controller.html. http://api.symfony.com/./symfony/component/dependencyinjection/containerawareinterface.html. http://api.symfony.com/./symfony/component/dependencyinjection/containeraware.html. http://api.symfony.com/./symfony/bundle/frameworkbundle/controller/controller.html generated on September, 0 Chapter : Comment utiliser les bonnes pratiques pour structurer vos Bundles
Fichiers de Traduction Si un bundle fournit des traductions de messages, ces dernières doivent être définies au format XLIFF ; le domaine devrait être nommé après le nom du bundle (bundle.hello). Un bundle ne doit pas «écraser» les messages existants venant d'un autre bundle. Configuration Pour fournir plus de flexibilité, un bundle peut procurer des paramètres configurables en utilisant les mécanismes intégrés de Symfony. Pour des paramètres de configuration simples, comptez sur les entrées par défaut de parameters de la configuration de Symfony. Les paramètres Symfony sont de simples paires clé/valeur ; une valeur étant n'importe quelle valeur PHP valide. Chaque nom de paramètre devrait commencer avec l'alias du bundle, bien que ceci ne soit qu'une suggestion de bonne pratique. Le reste du nom du paramètre va utiliser un point (.) pour séparer les différentes parties (par exemple : acme_hello.email.from). L'utilisateur final peut fournir des valeurs dans différents types de fichier de configuration : Listing - # app/config/config.yml parameters: acme_hello.email.from: fabien@example.com Récupérez les paramètres de configuration dans votre code depuis le conteneur: Listing - $container->getparameter('acme_hello.email.from'); Même si ce mécanisme est assez simple, vous êtes grandement encouragé à utiliser la configuration sémantique décrite dans le cookbook. Si vous définissez des services, ils devraient aussi être préfixés avec l'alias du bundle. En savoir plus grâce au Cookbook Comment exposer une configuration sémantique pour un Bundle generated on September, 0 Chapter : Comment utiliser les bonnes pratiques pour structurer vos Bundles
Chapter Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle Lorsque vous travaillerez avec des bundles tiers, vous allez probablement rencontrer une situation où vous voudrez surcharger un fichier de ce bundle tiers en le remplacant par un fichier de l'un de vos propres bundles. Symfony vous fournit une manière très pratique de surcharger des fichiers comme des contrôleurs, des templates et d'autres fichiers présents dans le dossier Resources/ d'un bundle. Par exemple, supposons que vous installiez le FOSUserBundle, mais que vous souhaitez surcharger son template de base layout.html.twig, ainsi que l'un de ses contrôleurs. Supposons aussi que vous ayez votre propre AcmeUserBundle où vous voulez avoir les fichiers de substitution. Commencez par déclarer le FOSUserBundle comme parent de votre bundle: Listing - 0 // src/acme/userbundle/acmeuserbundle.php namespace Acme\UserBundle; use Symfony\Component\HttpKernel\Bundle\Bundle; class AcmeUserBundle extends Bundle public function getparent() return 'FOSUserBundle'; En effectuant ce simple changement, vous pouvez désormais surcharger plusieurs parties du FOSUserBundle en créant simplement un fichier ayant le même nom. Malgré le nom de la méthode, il n'y a pas de relation parent/enfant entre les bundles. Il s'agit juste d'une manière d'étendre et de surcharger un bundle existant.. https://github.com/friendsofsymfony/fosuserbundle generated on September, 0 Chapter : Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle
Surcharger des contrôleurs Supposons que vous vouliez ajouter de la fonctionnalité à registeraction du RegistrationController résidant dans le FOSUserBundle. Pour faire cela, créez simplement votre propre fichier RegistrationController.php, surcharger la méthode originale du bundle, et changez sa fonctionnalité: Listing - 0 // src/acme/userbundle/controller/registrationcontroller.php namespace Acme\UserBundle\Controller; use FOS\UserBundle\Controller\RegistrationController as BaseController; class RegistrationController extends BaseController public function registeraction() $response = parent::registeraction(); // do custom stuff return $response; Suivant le degré de changement de fonctionnalité dont vous avez besoin, vous pourriez appeler parent::registeraction() ou alors remplacer complètement sa logique par la vôtre. Surcharger des contrôleurs de cette façon fonctionne uniquement si le bundle réfère au contrôleur en utilisant la syntaxe standard FOSUserBundle:Registration:register dans les routes et templates. Ceci est la bonne pratique. Surcharger des ressources : templates, routage, validation, etc. La plupart des ressources peuvent aussi être surchargées en créant simplement un fichier au même emplacement que dans votre bundle parent. Par exemple, il est très courant d'avoir besoin de surcharger le template layout.html.twig du FOSUserBundle afin qu'il utilise le layout de base de votre application. Comme le fichier réside à l'emplacement Resources/views/layout.html.twig dans le FOSUserBundle, vous pouvez créer votre propre fichier au même endroit dans le AcmeUserBundle. Symfony va complètement ignorer le fichier étant dans le FOSUserBundle, et utiliser le vôtre à la place. Il en va de même pour les fichiers de routage, de configuration de la validation et pour les autres ressources. Surcharger des ressources fonctionne uniquement lorsque vous référez à des ressources via la méthode @FosUserBundle/Resources/config/routing/security.xml. Si vous référez à des ressources sans utiliser le raccourci @NomDuBundle, ces dernières ne peuvent alors pas être surchargées. generated on September, 0 Chapter : Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle
Les fichiers de traduction ne fonctionnent pas de la même manière que celle décrite ci-dessus. Tous les fichiers de traduction sont accumulés dans un ensemble de «groupements» (un pour chaque domaine). Symfony charge les fichiers de traduction des bundles en premier (dans l'ordre dans lequel les bundles sont initialisés) et ensuite ceux de votre répertoire app/resources. Si la même traduction est spécifiée dans deux ressources, c'est la traduction venant de la ressource chargée en dernier qui gagnera. generated on September, 0 Chapter : Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle
Chapter Comment surcharger n'importe quelle partie d'un bundle Ce document est une référence succincte sur comment surcharger différentes partie d'un bundle tiers. Templates Pour des informations sur la surcharge de templates, lisez * La Surcharge de templates de Bundle * Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle Routage Le routage n'est jamais importé automatiquement dans Symfony. Si vous voulez inclure les routes d'un bundle, alors elles doivent être importées manuellement à un endroit de votre application (ex app/ config/routing.yml). La manière la plus simple de «surcharger» les routes d'un bundle est de ne pas les importer du tout. Plutôt que d'importer les routes d'un bundle tiers, copiez simplement le fichier de routage dans votre application, modifiez le, et importez le. Contrôleurs En partant du principe que les bundles tiers n'utisent pas de contrôleurs qui ne soient pas des services (ce qui est presque toujours le cas), vous pouvez facilement surcharger les contrôleurs grâce à l'héritage de bundle. Pour plus d'informations, lisez Comment utiliser l'héritage de bundle pour surcharger certaines parties d'un bundle. generated on September, 0 Chapter : Comment surcharger n'importe quelle partie d'un bundle
Services & Configuration Pour surcharger/étendre un service, vous avez deux options. Premièrement, vous pouvez redéfinir la valeur du paramètre qui contient le nom de la classe du service en spécifiant votre propre classe dans app/ config/config.yml. Bien sûr, cela n'est possible que si le nom de la classe est défini comme paramètre dans la configuration du service du bundle. Par exemple, pour surcharger la classe utilisé par le service translator``de Symfony, vous pouvez surcharger le paramètre ``translator.class. Savoir quel paramètre surcharger peut nécessiter un peu de recherche. Pour le Translator, le paramètre est défini et utilisé dans le fichier Resources/config/translation.xml du FrameworkBundle : Listing - # app/config/config.yml parameters: translator.class: Acme\HelloBundle\Translation\Translator Deuxièmement, si la classe n'est pas spécifiée dans les paramètres, si vous voulez vous assurer que la classe est bien toujours surchargée lorsque votre bundle est utilisé, ou si vous avez besoin de faire un peu plus de modifications, vous devrez utiliser une passe de compilation: Listing - 0 // src/acme/demobundle/dependencyinjection/compiler/overrideservicecompilerpass.php namespace Acme\DemoBundle\DependencyInjection\Compiler; use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface; use Symfony\Component\DependencyInjection\ContainerBuilder; class OverrideServiceCompilerPass implements CompilerPassInterface public function process(containerbuilder $container) $definition = $container->getdefinition('original-service-id'); $definition->setclass('acme\demobundle\yourservice'); Dans cet exemple, vous retrouvez la définition du service original, et vous changez son nom de classe en votre propre nom de classe. Lisez Comment travailler avec les Passes de Compilation dans les Bundles pour savoir comment utiliser les passes de compilation. Si vous voulez faire plus que simplement surcharger la classe, comme par exemple ajouter une méthode, vous ne pouvez utiliser que la méthode de la passe de compilation. Entités et mapping En cours... Formulaires Pour surcharger un type de formulaire, il faut l'enregistrer comme service (c'est-à-dire que vous devez le tagger avec «form.type»). Vous pourrez alors le surchargez comme vous surchargeriez n'importe quel service, comme c'est expliqué dans Services & Configuration. Bien sûr, cela ne fonctionnera que si le type est appelé par son alias, et non pas s'il est instancié. Exemple: Listing - $builder->add('name', 'custom_type'); generated on September, 0 Chapter : Comment surcharger n'importe quelle partie d'un bundle
au lieu de: Listing - $builder->add('name', new CustomType()); Métadonnées de Validation En cours... Traductions En cours... generated on September, 0 Chapter : Comment surcharger n'importe quelle partie d'un bundle
Chapter Comment supprimer le AcmeDemoBundle La Standard Edition de Symfony est livré avec une démo complète qui vit à l'intérieur d'un bundle appelé AcmeDemoBundle. C'est un bon repère pour tout démarrage d'un projet, mais vous aurez probablement envie de finalement le retirer. Cet article présente AcmeDemoBundle comme exemple, mais vous pouvez suivre les mêmes étapes pour supprimer n'importe quel bundle.. Désinscrire le bundle dans AppKernel Pour déconnecter le bundle du framework, vous devez le supprimer de la méthode AppKernel::registerBundles(). Le bundle se trouve normalement dans le tableau $bundles mais il n'est enregistré que pour l'environnement de développement. Vous pouvez le trouver à l'interieur de l'instruction if ci-dessous Listing - 0 // app/appkernel.php //... class AppKernel extends Kernel public function registerbundles() $bundles = array(...); if (in_array($this->getenvironment(), array('dev', 'test'))) // commentez ou supprimez cette ligne // $bundles[] = new Acme\DemoBundle\AcmeDemoBundle(); //... generated on September, 0 Chapter : Comment supprimer le AcmeDemoBundle
. Supprimer la configuration du bundle Maintenant que Symfony ne connaît plus le bundle, vous devez supprimer toute configuration ou configuration de routing qui se réfère au bundle dans le répertoire app/config.. Supprimer le routing du bundle Vous pouvez trouver le routing du AcmeDemoBundle dans le fichier app/config/routing_dev.yml. Supprimez la notation _acme_demo en bas de ce fichier.. Supprimer la configuration du bundle Certains bundles contiennent des configurations dans l'un des fichiers app/config/config*.yml. Assurez-vous de supprimer la configuration associée à ces fichiers. Vous pouvez rapidement repérer la configuration d'un bundle en cherchant la chaine acme_demo (ou n'importe quel autre nom de bundle, i.e fos_user pour le le FOSUserBundle). Le AcmeDemoBundle n'a pas de configuration. Toutefois, le bundle est utilisé dans la configuration de sécurité dans le fichier app/config/security.yml. Vous pouvez l'utiliser pour votre configuration de sécurité mais vous pouvez aussi la supprimer.. Supprimer le bundle depuis le système de fichier Maintenant que vous avez supprimé toutes les références du bundle dans votre application, vous pouvez supprimer le bundle depuis le système de fichier. Le bundle se trouve dans le répertoire src/acme/ DemoBundle. Vous devez supprimer ce dossier et vous pouvez aussi supprimer le dossier Acme. Si vous ne connaissez pas où se trouve le bundle, vous pouvez utiliser la méthode getpath() pour récupérer le chemin vers le bundle: Listing - echo $this->container->get('kernel')->getbundle('acmedemobundle')->getpath();. Supprimer l'integration dans d'autres bundles Ceci ne concerne pas le bundle AcmeDemoBundle - aucun autre bundle ne dépend de lui, donc pouvez sauter cette étape. Certains bundles s'appuient sur d'autres, si vous supprimez l'un d'eux, l'autre bundle ne fonctionnera probablement plus. Assurez-vous donc avant de supprimer un bundle qu'aucun autre bundle, tiers ou votre propre bundle, ne dépend de ce bundle.. http://api.symfony.com/./symfony/component/httpkernel/bundle/bundleinterface.html#getpath() generated on September, 0 Chapter : Comment supprimer le AcmeDemoBundle 0