The Cookbook

for Symfony 2.4

generated on February 10, 2014

The Cookbook (2.4) This work is licensed under the Attribution-Share Alike 3.0 Unported license (http://creativecommons.org/ licenses/by-sa/3.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
How to Use Assetic for Asset Management ..........................................................................................6 How to Minify CSS/JS Files (using UglifyJS and UglifyCSS)................................................................12 How to Minify JavaScripts and Stylesheets with YUI Compressor.......................................................16 How to Use Assetic For Image Optimization with Twig Functions .....................................................18 How to Apply an Assetic Filter to a Specific File Extension.................................................................21 How to install 3rd party Bundles .......................................................................................................23 How to use Best Practices for Structuring Bundles..............................................................................26 How to use Bundle Inheritance to Override parts of a Bundle .............................................................31 How to Override any Part of a Bundle ...............................................................................................33 How to remove the AcmeDemoBundle ..............................................................................................36 How to expose a Semantic Configuration for a Bundle .......................................................................39 How to simplify configuration of multiple Bundles ............................................................................48 How to use Varnish to speed up my Website .....................................................................................51 How to Master and Create new Environments ...................................................................................56 How to override Symfony's Default Directory Structure......................................................................61 Understanding how the Front Controller, Kernel and Environments work together.............................64 How to Set External Parameters in the Service Container ...................................................................67 How to use PdoSessionHandler to store Sessions in the Database .......................................................70 How to use the Apache Router ..........................................................................................................73 Configuring a web server...................................................................................................................75 How to create a Console Command ..................................................................................................78 How to use the Console ....................................................................................................................82 How to generate URLs and send Emails from the Console..................................................................84 How to enable logging in Console Commands ...................................................................................86 How to customize Error Pages...........................................................................................................90 How to define Controllers as Services ................................................................................................92 How to optimize your development Environment for debugging ........................................................96 How to deploy a Symfony2 application..............................................................................................98 How to handle File Uploads with Doctrine ...................................................................................... 102 How to use Doctrine Extensions: Timestampable, Sluggable, Translatable, etc. ................................ 111 How to Register Event Listeners and Subscribers ............................................................................. 112 How to use Doctrine's DBAL Layer ................................................................................................. 115 How to generate Entities from an Existing Database......................................................................... 117 How to work with Multiple Entity Managers and Connections......................................................... 121 How to Register Custom DQL Functions......................................................................................... 124 How to Define Relationships with Abstract Classes and Interfaces.................................................... 125
PDF brought to you by generated on February 10, 2014

Contents at a Glance | iii

How to provide model classes for several Doctrine implementations................................................. 128 How to implement a simple Registration Form ................................................................................ 131 How to send an Email ..................................................................................................................... 137 How to use Gmail to send Emails .................................................................................................... 140 How to Work with Emails During Development .............................................................................. 141 How to Spool Emails....................................................................................................................... 143 How to test that an Email is sent in a functional Test ....................................................................... 145 How to setup before and after Filters ............................................................................................... 147 How to extend a Class without using Inheritance............................................................................. 151 How to customize a Method Behavior without using Inheritance...................................................... 154 How to use Expressions in Security, Routing, Services, and Validation ............................................. 156 How to customize Form Rendering ................................................................................................. 157 How to use Data Transformers........................................................................................................ 169 How to Dynamically Modify Forms Using Form Events ................................................................... 175 How to Embed a Collection of Forms .............................................................................................. 186 How to Create a Custom Form Field Type....................................................................................... 199 How to Create a Form Type Extension ............................................................................................ 204 How to Reduce Code Duplication with "inherit_data" ..................................................................... 209 How to Unit Test your Forms.......................................................................................................... 212 How to configure Empty Data for a Form Class ............................................................................... 217 How to use the submit() Function to handle Form Submissions ....................................................... 219 How to use the Virtual Form Field Option....................................................................................... 222 How to use Monolog to write Logs.................................................................................................. 223 How to Configure Monolog to Email Errors .................................................................................... 227 How to Configure Monolog to Display Console Messages................................................................ 229 How to Configure Monolog to Exclude 404 Errors from the Log ...................................................... 231 How to log Messages to different Files ............................................................................................. 232 How to create a custom Data Collector............................................................................................ 234 How to use Matchers to enable the Profiler Conditionally ................................................................ 237 Switching the Profiler Storage .......................................................................................................... 239 How to register a new Request Format and Mime Type.................................................................... 240 How to force routes to always use HTTPS or HTTP......................................................................... 242 How to allow a "/" character in a route parameter ............................................................................ 243 How to Configure a Redirect without a Custom Controller .............................................................. 244 How to use HTTP Methods beyond GET and POST in Routes......................................................... 246 How to use Service Container Parameters in your Routes ................................................................. 248 How to create a custom Route Loader ............................................................................................. 250 Redirect URLs with a Trailing Slash................................................................................................. 254 How to load Security Users from the Database (the Entity Provider) ................................................. 256 How to add "Remember Me" Login Functionality ............................................................................ 269 How to Impersonate a User ............................................................................................................. 272 How to implement your own Voter to blacklist IP Addresses............................................................ 274 How to use Access Control Lists (ACLs).......................................................................................... 277 How to use Advanced ACL Concepts .............................................................................................. 281 How to force HTTPS or HTTP for Different URLs ........................................................................... 285 How to Restrict Firewalls to a Specific Host ..................................................................................... 286 How to customize your Form Login ................................................................................................ 287

iv | Contents at a Glance

Contents at a Glance | 4

How to secure any Service or Method in your Application................................................................ 290 How to create a custom User Provider ............................................................................................. 294 How to Create a Custom Form Password Authenticator................................................................... 299 How to Authenticate Users with API Keys ....................................................................................... 303 How to create a custom Authentication Provider ............................................................................. 310 How to change the Default Target Path Behavior ............................................................................. 320 Using CSRF in the Login Form ........................................................................................................ 322 How to use the Serializer ................................................................................................................. 324 How to create an Event Listener ...................................................................................................... 326 How to Work with Scopes .............................................................................................................. 329 How to work with Compiler Passes in Bundles ................................................................................ 334 Session Proxy Examples .................................................................................................................. 335 Making the Locale "Sticky" during a User's Session .......................................................................... 337 Configuring the Directory Where Sessions Files are Saved ................................................................ 339 Bridge a legacy application with Symfony Sessions ........................................................................... 341 Limit Session Metadata Writes ........................................................................................................ 343 How Symfony2 differs from symfony1 ............................................................................................. 344 How to Inject Variables into all Templates (i.e. Global Variables) ..................................................... 349 How to use and Register namespaced Twig Paths ............................................................................ 351 How to use PHP instead of Twig for Templates ............................................................................... 353 How to write a custom Twig Extension ........................................................................................... 359 How to render a Template without a custom Controller................................................................... 362 How to simulate HTTP Authentication in a Functional Test ............................................................ 364 How to simulate Authentication with a Token in a Functional Test .................................................. 365 How to test the Interaction of several Clients ................................................................................... 367 How to use the Profiler in a Functional Test..................................................................................... 369 How to test code that interacts with the Database ............................................................................ 371 How to test Doctrine Repositories ................................................................................................... 374 How to customize the Bootstrap Process before running Tests.......................................................... 376 How to create a Custom Validation Constraint ................................................................................ 378 How to Create a SOAP Web Service in a Symfony2 Controller ......................................................... 382 How to Create and store a Symfony2 Project in Git .......................................................................... 386 How to Create and store a Symfony2 Project in Subversion .............................................................. 390

PDF brought to you by generated on February 10, 2014

Contents at a Glance | v

Chapter 1

How to Use Assetic for Asset Management

Assetic combines two major ideas: assets and filters. The assets are files such as CSS, JavaScript and image files. The filters are things that can be applied to these files before they are served to the browser. This allows a separation between the asset files stored in the application and the files actually presented to the user. Without Assetic, you just serve the files that are stored in the application directly:
Listing 1-1

1 <script src="{{ asset('js/script.js') }}" type="text/javascript"></script>

But with Assetic, you can manipulate these assets however you want (or load them from anywhere) before serving them. This means you can: Minify and combine all of your CSS and JS files Run all (or just some) of your CSS or JS files through some sort of compiler, such as LESS, SASS or CoffeeScript Run image optimizations on your images

Assets
Using Assetic provides many advantages over directly serving the files. The files do not need to be stored where they are served from and can be drawn from various sources such as from within a bundle. You can use Assetic to process CSS stylesheets, JavaScript files and images. The philosophy behind adding either is basically the same, but with a slightly different syntax.

Including JavaScript Files

To include JavaScript files, use the javascripts tag in any template:
Listing 1-2

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' %} 2 <script type="text/javascript" src="{{ asset_url }}"></script> 3 {% endjavascripts %}

PDF brought to you by generated on February 10, 2014

Chapter 1: How to Use Assetic for Asset Management | 6

If you're using the default block names from the Symfony Standard Edition, the javascripts tag will most commonly live in the javascripts block:
Listing 1-3

1 2 3 4 5 6 7

{# ... #} {% block javascripts %} {% javascripts '@AcmeFooBundle/Resources/public/js/*' %} <script type="text/javascript" src="{{ asset_url }}"></script> {% endjavascripts %} {% endblock %} {# ... #}

You can also include CSS Stylesheets: see Including CSS Stylesheets.

In this example, all of the files in the Resources/public/js/ directory of the AcmeFooBundle will be loaded and served from a different location. The actual rendered tag might simply look like:
Listing 1-4

1 <script src="/app_dev.php/js/abcd123.js"></script>

This is a key point: once you let Assetic handle your assets, the files are served from a different location. This will cause problems with CSS files that reference images by their relative path. See Fixing CSS Paths with the cssrewrite Filter.

Including CSS Stylesheets

To bring in CSS stylesheets, you can use the same methodologies seen above, except with the stylesheets tag:
Listing 1-5

1 {% stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' %} 2 <link rel="stylesheet" href="{{ asset_url }}" /> 3 {% endstylesheets %}

If you're using the default block names from the Symfony Standard Edition, the stylesheets tag will most commonly live in the stylesheets block:
Listing 1-6

1 2 3 4 5 6 7

{# ... #} {% block stylesheets %} {% stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' %} <link rel="stylesheet" href="{{ asset_url }}" /> {% endstylesheets %} {% endblock %} {# ... #}

But because Assetic changes the paths to your assets, this will break any background images (or other paths) that uses relative paths, unless you use the cssrewrite filter.

PDF brought to you by generated on February 10, 2014

Chapter 1: How to Use Assetic for Asset Management | 7

Notice that in the original example that included JavaScript files, you referred to the files using a path like @AcmeFooBundle/Resources/public/file.js, but that in this example, you referred to the CSS files using their actual, publicly-accessible path: bundles/acme_foo/css. You can use either, except that there is a known issue that causes the cssrewrite filter to fail when using the @AcmeFooBundle syntax for CSS Stylesheets.

Including images
To include an image you can use the image tag.
Listing 1-7

1 {% image '@AcmeFooBundle/Resources/public/images/example.jpg' %} 2 <img src="{{ asset_url }}" alt="Example" /> 3 {% endimage %}

You can also use Assetic for image optimization. More information in How to Use Assetic For Image Optimization with Twig Functions.

Fixing CSS Paths with the cssrewrite Filter

Since Assetic generates new URLs for your assets, any relative paths inside your CSS files will break. To fix this, make sure to use the cssrewrite filter with your stylesheets tag. This parses your CSS files and corrects the paths internally to reflect the new location. You can see an example in the previous section.
When using the cssrewrite filter, don't refer to your CSS files using the @AcmeFooBundle syntax. See the note in the above section for details.

Combining Assets
One feature of Assetic is that it will combine many files into one. This helps to reduce the number of HTTP requests, which is great for front end performance. It also allows you to maintain the files more easily by splitting them into manageable parts. This can help with re-usability as you can easily split project-specific files from those which can be used in other applications, but still serve them as a single file:
Listing 1-8

1 {% javascripts 2 '@AcmeFooBundle/Resources/public/js/*' 3 '@AcmeBarBundle/Resources/public/js/form.js' 4 '@AcmeBarBundle/Resources/public/js/calendar.js' %} 5 <script src="{{ asset_url }}"></script> 6 {% endjavascripts %}

In the dev environment, each file is still served individually, so that you can debug problems more easily. However, in the prod environment (or more specifically, when the debug flag is false), this will be rendered as a single script tag, which contains the contents of all of the JavaScript files.
If you're new to Assetic and try to use your application in the prod environment (by using the app.php controller), you'll likely see that all of your CSS and JS breaks. Don't worry! This is on purpose. For details on using Assetic in the prod environment, see Dumping Asset Files.

PDF brought to you by generated on February 10, 2014

Chapter 1: How to Use Assetic for Asset Management | 8

And combining files doesn't only apply to your files. You can also use Assetic to combine third party assets, such as jQuery, with your own into a single file:
Listing 1-9

1 {% javascripts 2 '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js' 3 '@AcmeFooBundle/Resources/public/js/*' %} 4 <script src="{{ asset_url }}"></script> 5 {% endjavascripts %}

Using Named Assets

AsseticBundle configuration directives allow you to define named asset sets. You can do so by defining the input files, filters and output files in your configuration under the assetic section. Read more in the assetic config reference.
Listing 1-10

1 # app/config/config.yml 2 assetic: 3 assets: 4 jquery_and_ui: 5 inputs: 6 - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js' 7 - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js'

After you have defined the named assets, you can reference them in your templates with the @named_asset notation:
Listing 1-11

1 {% javascripts 2 '@jquery_and_ui' 3 '@AcmeFooBundle/Resources/public/js/*' %} 4 <script src="{{ asset_url }}"></script> 5 {% endjavascripts %}

Filters
Once they're managed by Assetic, you can apply filters to your assets before they are served. This includes filters that compress the output of your assets for smaller file sizes (and better front-end optimization). Other filters can compile JavaScript file from CoffeeScript files and process SASS into CSS. In fact, Assetic has a long list of available filters. Many of the filters do not do the work directly, but use existing third-party libraries to do the heavylifting. This means that you'll often need to install a third-party library to use a filter. The great advantage of using Assetic to invoke these libraries (as opposed to using them directly) is that instead of having to run them manually after you work on the files, Assetic will take care of this for you and remove this step altogether from your development and deployment processes. To use a filter, you first need to specify it in the Assetic configuration. Adding a filter here doesn't mean it's being used - it just means that it's available to use (you'll use the filter below). For example to use the UglifyJS JavaScript minifier the following config should be added:
Listing 1-12

1 # app/config/config.yml 2 assetic: 3 filters:

PDF brought to you by generated on February 10, 2014

Chapter 1: How to Use Assetic for Asset Management | 9

4 5

uglifyjs2: bin: /usr/local/bin/uglifyjs

Now, to actually use the filter on a group of JavaScript files, add it into your template:
Listing 1-13

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='uglifyjs2' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

A more detailed guide about configuring and using Assetic filters as well as details of Assetic's debug mode can be found in How to Minify CSS/JS Files (using UglifyJS and UglifyCSS).

Controlling the URL used

If you wish to, you can control the URLs that Assetic produces. This is done from the template and is relative to the public document root:
Listing 1-14

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

Symfony also contains a method for cache busting, where the final URL generated by Assetic contains a query parameter that can be incremented via configuration on each deployment. For more information, see the assets_version configuration option.

Dumping Asset Files

In the dev environment, Assetic generates paths to CSS and JavaScript files that don't physically exist on your computer. But they render nonetheless because an internal Symfony controller opens the files and serves back the content (after running any filters). This kind of dynamic serving of processed assets is great because it means that you can immediately see the new state of any asset files you change. It's also bad, because it can be quite slow. If you're using a lot of filters, it might be downright frustrating. Fortunately, Assetic provides a way to dump your assets to real files, instead of being generated dynamically.

Dumping Asset Files in the prod environment

In the prod environment, your JS and CSS files are represented by a single tag each. In other words, instead of seeing each JavaScript file you're including in your source, you'll likely just see something like this:
Listing 1-15

1 <script src="/js/abcd123.js"></script>

Moreover, that file does not actually exist, nor is it dynamically rendered by Symfony (as the asset files are in the dev environment). This is on purpose - letting Symfony generate these files dynamically in a production environment is just too slow.

PDF brought to you by generated on February 10, 2014

Chapter 1: How to Use Assetic for Asset Management | 10

Instead, each time you use your app in the prod environment (and therefore, each time you deploy), you should run the following task:
Listing 1-16

1 $ php app/console assetic:dump --env=prod --no-debug

This will physically generate and write each file that you need (e.g. /js/abcd123.js). If you update any of your assets, you'll need to run this again to regenerate the file.

Dumping Asset Files in the dev environment

By default, each asset path generated in the dev environment is handled dynamically by Symfony. This has no disadvantage (you can see your changes immediately), except that assets can load noticeably slow. If you feel like your assets are loading too slowly, follow this guide. First, tell Symfony to stop trying to process these files dynamically. Make the following change in your config_dev.yml file:
Listing 1-17

1 # app/config/config_dev.yml 2 assetic: 3 use_controller: false

Next, since Symfony is no longer generating these assets for you, you'll need to dump them manually. To do so, run the following:
Listing 1-18

1 $ php app/console assetic:dump

This physically writes all of the asset files you need for your dev environment. The big disadvantage is that you need to run this each time you update an asset. Fortunately, by passing the --watch option, the command will automatically regenerate assets as they change:
Listing 1-19

1 $ php app/console assetic:dump --watch

Since running this command in the dev environment may generate a bunch of files, it's usually a good idea to point your generated assets files to some isolated directory (e.g. /js/compiled), to keep things organized:
Listing 1-20

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

PDF brought to you by generated on February 10, 2014

Chapter 1: How to Use Assetic for Asset Management | 11

Chapter 2

How to Minify CSS/JS Files (using UglifyJS and UglifyCSS)

UglifyJS1 is a JavaScript parser/compressor/beautifier toolkit. It can be used to combine and minify JavaScript assets so that they require less HTTP requests and make your site load faster. UglifyCSS2 is a CSS compressor/beautifier that is very similar to UglifyJS. In this cookbook, the installation, configuration and usage of UglifyJS is shown in detail. UglifyCSS works pretty much the same way and is only talked about briefly.

Install UglifyJS
UglifyJS is available as an Node.js3 npm module and can be installed using npm. First, you need to install Node.js4. Afterwards you can install UglifyJS using npm:
Listing 2-1

1 $ npm install -g uglify-js

This command will install UglifyJS globally and you may need to run it as a root user.

1. https://github.com/mishoo/UglifyJS 2. https://github.com/fmarcia/UglifyCSS 3. http://nodejs.org/ 4. http://nodejs.org/

PDF brought to you by generated on February 10, 2014

Chapter 2: How to Minify CSS/JS Files (using UglifyJS and UglifyCSS) | 12

It's also possible to install UglifyJS inside your project only. To do this, install it without the -g option and specify the path where to put the module:
Listing 2-2

1 $ cd /path/to/symfony 2 $ mkdir app/Resources/node_modules 3 $ npm install uglify-js --prefix app/Resources

It is recommended that you install UglifyJS in your app/Resources folder and add the node_modules folder to version control. Alternatively, you can create an npm package.json5 file and specify your dependencies there.

Depending on your installation method, you should either be able to execute the uglifyjs executable globally, or execute the physical file that lives in the node_modules directory:
Listing 2-3

1 $ uglifyjs --help 2 3 $ ./app/Resources/node_modules/.bin/uglifyjs --help

Configure the uglifyjs2 Filter

Now we need to configure Symfony2 to use the uglifyjs2 filter when processing your JavaScripts:
Listing 2-4

1 # app/config/config.yml 2 assetic: 3 filters: 4 uglifyjs2: 5 # the path to the uglifyjs executable 6 bin: /usr/local/bin/uglifyjs

The path where UglifyJS is installed may vary depending on your system. To find out where npm stores the bin folder, you can use the following command:
Listing 2-5

1 $ npm bin -g

It should output a folder on your system, inside which you should find the UglifyJS executable. If you installed UglifyJS locally, you can find the bin folder inside the node_modules folder. It's called .bin in this case.

You now have access to the uglifyjs2 filter in your application.

Minify your Assets

In order to use UglifyJS on your assets, you need to apply it to them. Since your assets are a part of the view layer, this work is done in your templates:
Listing 2-6

5. http://package.json.nodejitsu.com/

PDF brought to you by generated on February 10, 2014

Chapter 2: How to Minify CSS/JS Files (using UglifyJS and UglifyCSS) | 13

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='uglifyjs2' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

The above example assumes that you have a bundle called AcmeFooBundle and your JavaScript files are in the Resources/public/js directory under your bundle. This isn't important however you can include your JavaScript files no matter where they are.

With the addition of the uglifyjs2 filter to the asset tags above, you should now see minified JavaScripts coming over the wire much faster.

Disable Minification in Debug Mode

Minified JavaScripts are very difficult to read, let alone debug. Because of this, Assetic lets you disable a certain filter when your application is in debug (e.g. app_dev.php) mode. You can do this by prefixing the filter name in your template with a question mark: ?. This tells Assetic to only apply this filter when debug mode is off (e.g. app.php):
Listing 2-7

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='?uglifyjs2' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

To try this out, switch to your prod environment (app.php). But before you do, don't forget to clear your cache and dump your assetic assets.
Instead of adding the filter to the asset tags, you can also globally enable it by adding the apply_to attribute to the filter configuration, for example in the uglifyjs2 filter apply_to: "\.js$". To only have the filter applied in production, add this to the config_prod file rather than the common config file. For details on applying filters by file extension, see Filtering based on a File Extension.

Install, configure and use UglifyCSS

The usage of UglifyCSS works the same way as UglifyJS. First, make sure the node package is installed:
Listing 2-8

1 $ npm install -g uglifycss

Next, add the configuration for this filter:

Listing 2-9

1 # app/config/config.yml 2 assetic: 3 filters: 4 uglifycss: 5 bin: /usr/local/bin/uglifycss

To use the filter for your CSS files, add the filter to the Assetic stylesheets helper:
Listing 2-10

1 {% stylesheets '@AcmeFooBundle/Resources/public/css/*' filter='uglifycss' %} 2 <link rel="stylesheet" href="{{ asset_url }}" /> 3 {% endstylesheets %}

PDF brought to you by generated on February 10, 2014

Chapter 2: How to Minify CSS/JS Files (using UglifyJS and UglifyCSS) | 14

Just like with the uglifyjs2 filter, if you prefix the filter name with ? (i.e. ?uglifycss), the minification will only happen when you're not in debug mode.

PDF brought to you by generated on February 10, 2014

Chapter 2: How to Minify CSS/JS Files (using UglifyJS and UglifyCSS) | 15

Chapter 3

How to Minify JavaScripts and Stylesheets with YUI Compressor

Yahoo! provides an excellent utility for minifying JavaScripts and stylesheets so they travel over the wire faster, the YUI Compressor1. Thanks to Assetic, you can take advantage of this tool very easily.
The YUI Compressor is going through a deprecation process2. But don't worry! See How to Minify CSS/JS Files (using UglifyJS and UglifyCSS) for an alternative.

Download the YUI Compressor JAR

The YUI Compressor is written in Java and distributed as a JAR. Download the JAR3 from the Yahoo! site and save it to app/Resources/java/yuicompressor.jar.

Configure the YUI Filters

Now you need to configure two Assetic filters in your application, one for minifying JavaScripts with the YUI Compressor and one for minifying stylesheets:
Listing 3-1

1 # app/config/config.yml 2 assetic: 3 # java: "/usr/bin/java" 4 filters: 5 yui_css: 6 jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar"

1. http://developer.yahoo.com/yui/compressor/ 2. http://www.yuiblog.com/blog/2012/10/16/state-of-yui-compressor/ 3. https://github.com/yui/yuicompressor/releases

PDF brought to you by generated on February 10, 2014

Chapter 3: How to Minify JavaScripts and Stylesheets with YUI Compressor | 16

7 8

yui_js: jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar"

Windows users need to remember to update config to proper Java location. In Windows7 x64 bit by default it's C:\Program Files (x86)\Java\jre6\bin\java.exe.

You now have access to two new Assetic filters in your application: yui_css and yui_js. These will use the YUI Compressor to minify stylesheets and JavaScripts, respectively.

Minify your Assets

You have YUI Compressor configured now, but nothing is going to happen until you apply one of these filters to an asset. Since your assets are a part of the view layer, this work is done in your templates:
Listing 3-2

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

The above example assumes that you have a bundle called AcmeFooBundle and your JavaScript files are in the Resources/public/js directory under your bundle. This isn't important however you can include your JavaScript files no matter where they are.

With the addition of the yui_js filter to the asset tags above, you should now see minified JavaScripts coming over the wire much faster. The same process can be repeated to minify your stylesheets.
Listing 3-3

1 {% stylesheets '@AcmeFooBundle/Resources/public/css/*' filter='yui_css' %} 2 <link rel="stylesheet" type="text/css" media="screen" href="{{ asset_url }}" /> 3 {% endstylesheets %}

Disable Minification in Debug Mode

Minified JavaScripts and Stylesheets are very difficult to read, let alone debug. Because of this, Assetic lets you disable a certain filter when your application is in debug mode. You can do this by prefixing the filter name in your template with a question mark: ?. This tells Assetic to only apply this filter when debug mode is off.
Listing 3-4

1 {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='?yui_js' %} 2 <script src="{{ asset_url }}"></script> 3 {% endjavascripts %}

Instead of adding the filter to the asset tags, you can also globally enable it by adding the apply_to attribute to the filter configuration, for example in the yui_js filter apply_to: "\.js$". To only have the filter applied in production, add this to the config_prod file rather than the common config file. For details on applying filters by file extension, see Filtering based on a File Extension.

PDF brought to you by generated on February 10, 2014

Chapter 3: How to Minify JavaScripts and Stylesheets with YUI Compressor | 17

Chapter 4

How to Use Assetic For Image Optimization with Twig Functions

Amongst its many filters, Assetic has four filters which can be used for on-the-fly image optimization. This allows you to get the benefits of smaller file sizes without having to use an image editor to process each image. The results are cached and can be dumped for production so there is no performance hit for your end users.

Using Jpegoptim
Jpegoptim1 is a utility for optimizing JPEG files. To use it with Assetic, add the following to the Assetic config:
Listing 4-1

1 # app/config/config.yml 2 assetic: 3 filters: 4 jpegoptim: 5 bin: path/to/jpegoptim

Notice that to use jpegoptim, you must have it already installed on your system. The bin option points to the location of the compiled binary.

It can now be used from a template:

Listing 4-2

1 {% image '@AcmeFooBundle/Resources/public/images/example.jpg' 2 filter='jpegoptim' output='/images/example.jpg' %} 3 <img src="{{ asset_url }}" alt="Example"/> 4 {% endimage %}

1. http://www.kokkonen.net/tjko/projects.html

PDF brought to you by generated on February 10, 2014

Chapter 4: How to Use Assetic For Image Optimization with Twig Functions | 18

Removing all EXIF Data

By default, running this filter only removes some of the meta information stored in the file. Any EXIF data and comments are not removed, but you can remove these by using the strip_all option:
Listing 4-3

1 # app/config/config.yml 2 assetic: 3 filters: 4 jpegoptim: 5 bin: path/to/jpegoptim 6 strip_all: true

Lowering Maximum Quality

The quality level of the JPEG is not affected by default. You can gain further file size reductions by setting the max quality setting lower than the current level of the images. This will of course be at the expense of image quality:
Listing 4-4

1 # app/config/config.yml 2 assetic: 3 filters: 4 jpegoptim: 5 bin: path/to/jpegoptim 6 max: 70

Shorter syntax: Twig Function

If you're using Twig, it's possible to achieve all of this with a shorter syntax by enabling and using a special Twig function. Start by adding the following config:
Listing 4-5

1 # app/config/config.yml 2 assetic: 3 filters: 4 jpegoptim: 5 bin: path/to/jpegoptim 6 twig: 7 functions: 8 jpegoptim: ~

The Twig template can now be changed to the following:

Listing 4-6

1 <img src="{{ jpegoptim('@AcmeFooBundle/Resources/public/images/example.jpg') }}" alt="Example"/>

You can specify the output directory in the config in the following way:
Listing 4-7

1 # app/config/config.yml 2 assetic: 3 filters: 4 jpegoptim: 5 bin: path/to/jpegoptim 6 twig:

PDF brought to you by generated on February 10, 2014

Chapter 4: How to Use Assetic For Image Optimization with Twig Functions | 19

7 8

functions: jpegoptim: { output: images/*.jpg }

PDF brought to you by generated on February 10, 2014

Chapter 4: How to Use Assetic For Image Optimization with Twig Functions | 20

Chapter 5

How to Apply an Assetic Filter to a Specific File Extension

Assetic filters can be applied to individual files, groups of files or even, as you'll see here, files that have a specific extension. To show you how to handle each option, suppose that you want to use Assetic's CoffeeScript filter, which compiles CoffeeScript files into JavaScript. The main configuration is just the paths to coffee, node and node_modules. An example configuration might look like this:
Listing 5-1

1 # app/config/config.yml 2 assetic: 3 filters: 4 coffee: 5 bin: /usr/bin/coffee 6 node: /usr/bin/node 7 node_paths: [/usr/lib/node_modules/]

Filter a Single File

You can now serve up a single CoffeeScript file as JavaScript from within your templates:
Listing 5-2

1 {% javascripts '@AcmeFooBundle/Resources/public/js/example.coffee' filter='coffee' %} 2 <script src="{{ asset_url }}" type="text/javascript"></script> 3 {% endjavascripts %}

This is all that's needed to compile this CoffeeScript file and serve it as the compiled JavaScript.

Filter Multiple Files

You can also combine multiple CoffeeScript files into a single output file:

PDF brought to you by generated on February 10, 2014

Chapter 5: How to Apply an Assetic Filter to a Specific File Extension | 21

Listing 5-3

1 {% javascripts '@AcmeFooBundle/Resources/public/js/example.coffee' 2 '@AcmeFooBundle/Resources/public/js/another.coffee' 3 filter='coffee' %} 4 <script src="{{ asset_url }}" type="text/javascript"></script> 5 {% endjavascripts %}

Both the files will now be served up as a single file compiled into regular JavaScript.

Filtering based on a File Extension

One of the great advantages of using Assetic is reducing the number of asset files to lower HTTP requests. In order to make full use of this, it would be good to combine all your JavaScript and CoffeeScript files together since they will ultimately all be served as JavaScript. Unfortunately just adding the JavaScript files to the files to be combined as above will not work as the regular JavaScript files will not survive the CoffeeScript compilation. This problem can be avoided by using the apply_to option in the config, which allows you to specify that a filter should always be applied to particular file extensions. In this case you can specify that the coffee filter is applied to all .coffee files:
Listing 5-4

# app/config/config.yml assetic: filters: coffee: bin: node: node_paths: apply_to:

/usr/bin/coffee /usr/bin/node [/usr/lib/node_modules/] "\.coffee$"

With this, you no longer need to specify the coffee filter in the template. You can also list regular JavaScript files, all of which will be combined and rendered as a single JavaScript file (with only the .coffee files being run through the CoffeeScript filter):
Listing 5-5

1 {% javascripts '@AcmeFooBundle/Resources/public/js/example.coffee' 2 '@AcmeFooBundle/Resources/public/js/another.coffee' 3 '@AcmeFooBundle/Resources/public/js/regular.js' %} 4 <script src="{{ asset_url }}" type="text/javascript"></script> 5 {% endjavascripts %}

PDF brought to you by generated on February 10, 2014

Chapter 5: How to Apply an Assetic Filter to a Specific File Extension | 22

Chapter 6

How to install 3rd party Bundles

Most bundles provide their own installation instructions. However, the basic steps for installing a bundle are the same.

Add Composer Dependencies

In Symfony, dependencies are managed with Composer. It's a good idea to learn some basics of Composer in their documentation1. Before you can use Composer to install a bundle, you should look for a Packagist2 package of that bundle. For example, if you search for the popular FOSUserBundle3 you will find a package called friendsofsymfony/user-bundle4.
Packagist is the main archive for Composer. If you are searching for a bundle, the best thing you can do is check out KnpBundles5, it is the unofficial archive of Symfony Bundles. If a bundle contains a README file, it is displayed there and if it has a Packagist package it shows a link to the package. It's a really useful site to begin searching for bundles.

Now that you have the package name, you should determine the version you want to use. Usually different versions of a bundle correspond to a particular version of Symfony. This information should be in the README file. If it isn't, you can use the version you want. If you choose an incompatible version, Composer will throw dependency errors when you try to install. If this happens, you can try a different version. Now you can add the bundle to your composer.json file and update the dependencies. You can do this manually: 1. Add it to the ``composer.json`` file:
Listing 6-1

1. http://getcomposer.org/doc/00-intro.md 2. https://packagist.org 3. https://github.com/FriendsOfSymfony/FOSUserBundle 4. https://packagist.org/packages/friendsofsymfony/user-bundle 5. http://knpbundles.com/

PDF brought to you by generated on February 10, 2014

Chapter 6: How to install 3rd party Bundles | 23

{ ..., "require": { ..., "friendsofsymfony/user-bundle": "2.0.*@dev" } }

2. Update the dependency:

Listing 6-2

1 $ php composer.phar update friendsofsymfony/user-bundle

or update all dependencies

Listing 6-3

1 $ php composer.phar update

Or you can do this in one command:

Listing 6-4

1 $ php composer.phar require friendsofsymfony/user-bundle:2.0.*@dev

Enable the Bundle

At this point, the bundle is installed in your Symfony project (in vendor/friendsofsymfony/) and the autoloader recognizes its classes. The only thing you need to do now is register the bundle in AppKernel:
Listing 6-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// app/AppKernel.php // ... class AppKernel extends Kernel { // ...

public function registerBundles() { $bundles = array( // ..., new FOS\UserBundle\FOSUserBundle(), );

// ...
} }

Configure the Bundle

Usually a bundle requires some configuration to be added to app's app/config/config.yml file. The bundle's documentation will likely describe that configuration. But you can also get a reference of the bundle's config via the config:dump-reference command. For instance, in order to look the reference of the assetic config you can use this:
Listing 6-6

1 $ app/console config:dump-reference AsseticBundle

PDF brought to you by generated on February 10, 2014

Chapter 6: How to install 3rd party Bundles | 24

or this:
Listing 6-7

1 $ app/console config:dump-reference assetic

The output will look like this:

Listing 6-8

1 assetic: 2 debug: 3 use_controller: 4 enabled: 5 profiler: 6 read_from: 7 write_to: 8 java: 9 node: 10 node_paths: 11 # ...

%kernel.debug% %kernel.debug% false %kernel.root_dir%/../web %assetic.read_from% /usr/bin/java /usr/local/bin/node []

Other Setup
At this point, check the README file of your brand new bundle to see what to do next.

PDF brought to you by generated on February 10, 2014

Chapter 6: How to install 3rd party Bundles | 25

Chapter 7

How to use Best Practices for Structuring Bundles

A bundle is a directory that has a well-defined structure and can host anything from classes to controllers and web resources. Even if bundles are very flexible, you should follow some best practices if you want to distribute them.

Bundle Name
A bundle is also a PHP namespace. The namespace must follow the technical interoperability standards1 for PHP 5.3 namespaces and class names: it starts with a vendor segment, followed by zero or more category segments, and it ends with the namespace short name, which must end with a Bundle suffix. A namespace becomes a bundle as soon as you add a bundle class to it. The bundle class name must follow these simple rules: Use only alphanumeric characters and underscores; Use a CamelCased name; Use a descriptive and short name (no more than 2 words); Prefix the name with the concatenation of the vendor (and optionally the category namespaces); Suffix the name with Bundle. Here are some valid bundle namespaces and class names: Namespace Acme\Bundle\BlogBundle Bundle Class Name AcmeBlogBundle

Acme\Bundle\Social\BlogBundle AcmeSocialBlogBundle Acme\BlogBundle AcmeBlogBundle

1. http://www.php-fig.org/psr/psr-0/

PDF brought to you by generated on February 10, 2014

Chapter 7: How to use Best Practices for Structuring Bundles | 26

By convention, the getName() method of the bundle class should return the class name.
If you share your bundle publicly, you must use the bundle class name as the name of the repository (AcmeBlogBundle and not BlogBundle for instance).

Symfony2 core Bundles do not prefix the Bundle class with Symfony and always add a Bundle subnamespace; for example: FrameworkBundle2.

Each bundle has an alias, which is the lower-cased short version of the bundle name using underscores (acme_hello for AcmeHelloBundle, or acme_social_blog for Acme\Social\BlogBundle for instance). This alias is used to enforce uniqueness within a bundle (see below for some usage examples).

Directory Structure
The basic directory structure of a HelloBundle bundle must read as follows:
Listing 7-1

1 XXX/... 2 HelloBundle/ 3 HelloBundle.php 4 Controller/ 5 Resources/ 6 meta/ 7 LICENSE 8 config/ 9 doc/ 10 index.rst 11 translations/ 12 views/ 13 public/ 14 Tests/

The XXX directory(ies) reflects the namespace structure of the bundle. The following files are mandatory: HelloBundle.php; Resources/meta/LICENSE: The full license for the code; Resources/doc/index.rst: The root file for the Bundle documentation.
These conventions ensure that automated tools can rely on this default structure to work.

The depth of sub-directories should be kept to the minimal for most used classes and files (2 levels at a maximum). More levels can be defined for non-strategic, less-used files. The bundle directory is read-only. If you need to write temporary files, store them under the cache/ or log/ directory of the host application. Tools can generate files in the bundle directory structure, but only if the generated files are going to be part of the repository. The following classes and files have specific emplacements:
2. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/FrameworkBundle.html

PDF brought to you by generated on February 10, 2014

Chapter 7: How to use Best Practices for Structuring Bundles | 27

Type Commands Controllers Event Listeners Configuration Web Resources Translation files Templates Unit and Functional Tests

Directory Command/ Controller/

Service Container Extensions DependencyInjection/ EventListener/ Resources/config/ Resources/public/ Resources/translations/ Resources/views/ Tests/

When building a reusable bundle, model classes should be placed in the Model namespace. See How to provide model classes for several Doctrine implementations for how to handle the mapping with a compiler pass.

Classes
The bundle directory structure is used as the namespace hierarchy. For instance, a HelloController controller is stored in Bundle/HelloBundle/Controller/HelloController.php and the fully qualified class name is Bundle\HelloBundle\Controller\HelloController. All classes and files must follow the Symfony2 coding standards. Some classes should be seen as facades and should be as short as possible, like Commands, Helpers, Listeners, and Controllers. Classes that connect to the event dispatcher should be suffixed with Listener. Exceptions classes should be stored in an Exception sub-namespace.

Vendors
A bundle must not embed third-party PHP libraries. It should rely on the standard Symfony2 autoloading instead. A bundle should not embed third-party libraries written in JavaScript, CSS, or any other language.

Tests
A bundle should come with a test suite written with PHPUnit and stored under the Tests/ directory. Tests should follow the following principles: The test suite must be executable with a simple phpunit command run from a sample application; The functional tests should only be used to test the response output and some profiling information if you have some; The tests should cover at least 95% of the code base.

PDF brought to you by generated on February 10, 2014

Chapter 7: How to use Best Practices for Structuring Bundles | 28

A test suite must not contain AllTests.php scripts, but must rely on the existence of a phpunit.xml.dist file.

Documentation
All classes and functions must come with full PHPDoc. Extensive documentation should also be provided in the reStructuredText format, under the Resources/ doc/ directory; the Resources/doc/index.rst file is the only mandatory file and must be the entry point for the documentation.

Controllers
As a best practice, controllers in a bundle that's meant to be distributed to others must not extend the Controller3 base class. They can implement ContainerAwareInterface4 or extend ContainerAware5 instead.
If you have a look at Controller6 methods, you will see that they are only nice shortcuts to ease the learning curve.

Routing
If the bundle provides routes, they must be prefixed with the bundle alias. For an AcmeBlogBundle for instance, all routes must be prefixed with acme_blog_.

Templates
If a bundle provides templates, they must use Twig. A bundle must not provide a main layout, except if it provides a full working application.

Translation Files
If a bundle provides message translations, they must be defined in the XLIFF format; the domain should be named after the bundle name (bundle.hello). A bundle must not override existing messages from another bundle.

3. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Controller/Controller.html 4. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/ContainerAwareInterface.html 5. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/ContainerAware.html 6. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Controller/Controller.html

PDF brought to you by generated on February 10, 2014

Chapter 7: How to use Best Practices for Structuring Bundles | 29

Configuration
To provide more flexibility, a bundle can provide configurable settings by using the Symfony2 built-in mechanisms. For simple configuration settings, rely on the default parameters entry of the Symfony2 configuration. Symfony2 parameters are simple key/value pairs; a value being any valid PHP value. Each parameter name should start with the bundle alias, though this is just a best-practice suggestion. The rest of the parameter name will use a period (.) to separate different parts (e.g. acme_hello.email.from). The end user can provide values in any configuration file:
Listing 7-2

1 # app/config/config.yml 2 parameters: 3 acme_hello.email.from: [email protected]

Retrieve the configuration parameters in your code from the container:

Listing 7-3

1 $container->getParameter('acme_hello.email.from');

Even if this mechanism is simple enough, you are highly encouraged to use the semantic configuration described in the cookbook.
If you are defining services, they should also be prefixed with the bundle alias.

Learn more from the Cookbook

How to expose a Semantic Configuration for a Bundle

PDF brought to you by generated on February 10, 2014

Chapter 7: How to use Best Practices for Structuring Bundles | 30

Chapter 8

How to use Bundle Inheritance to Override parts of a Bundle

When working with third-party bundles, you'll probably come across a situation where you want to override a file in that third-party bundle with a file in one of your own bundles. Symfony gives you a very convenient way to override things like controllers, templates, and other files in a bundle's Resources/ directory. For example, suppose that you're installing the FOSUserBundle1, but you want to override its base layout.html.twig template, as well as one of its controllers. Suppose also that you have your own AcmeUserBundle where you want the overridden files to live. Start by registering the FOSUserBundle as the "parent" of your bundle:
Listing 8-1

1 2 3 4 5 6 7 8 9 10 11 12

// src/Acme/UserBundle/AcmeUserBundle.php namespace Acme\UserBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle; class AcmeUserBundle extends Bundle { public function getParent() { return 'FOSUserBundle'; } }

By making this simple change, you can now override several parts of the FOSUserBundle simply by creating a file with the same name.
Despite the method name, there is no parent/child relationship between the bundles, it is just a way to extend and override an existing bundle.

1. https://github.com/friendsofsymfony/fosuserbundle

PDF brought to you by generated on February 10, 2014

Chapter 8: How to use Bundle Inheritance to Override parts of a Bundle | 31

Overriding Controllers
Suppose you want to add some functionality to the registerAction of a RegistrationController that lives inside FOSUserBundle. To do so, just create your own RegistrationController.php file, override the bundle's original method, and change its functionality:
Listing 8-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

// 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;

} }

Depending on how severely you need to change the behavior, you might call parent::registerAction() or completely replace its logic with your own.

Overriding controllers in this way only works if the bundle refers to the controller using the standard FOSUserBundle:Registration:register syntax in routes and templates. This is the best practice.

Overriding Resources: Templates, Routing, etc

Most resources can also be overridden, simply by creating a file in the same location as your parent bundle. For example, it's very common to need to override the FOSUserBundle's layout.html.twig template so that it uses your application's base layout. Since the file lives at Resources/views/layout.html.twig in the FOSUserBundle, you can create your own file in the same location of AcmeUserBundle. Symfony will ignore the file that lives inside the FOSUserBundle entirely, and use your file instead. The same goes for routing files and some other resources.
The overriding of resources only works when you refer to resources with the @FosUserBundle/ Resources/config/routing/security.xml method. If you refer to resources without using the @BundleName shortcut, they can't be overridden in this way.

Translation and validation files do not work in the same way as described above. Read "Translations" if you want to learn how to override translations and see "Validation metadata" for tricks to override the validation.

PDF brought to you by generated on February 10, 2014

Chapter 8: How to use Bundle Inheritance to Override parts of a Bundle | 32

Chapter 9

How to Override any Part of a Bundle

This document is a quick reference for how to override different parts of third-party bundles.

Templates
For information on overriding templates, see Overriding Bundle Templates. How to use Bundle Inheritance to Override parts of a Bundle

Routing
Routing is never automatically imported in Symfony2. If you want to include the routes from any bundle, then they must be manually imported from somewhere in your application (e.g. app/config/ routing.yml). The easiest way to "override" a bundle's routing is to never import it at all. Instead of importing a thirdparty bundle's routing, simply copying that routing file into your application, modify it, and import it instead.

Controllers
Assuming the third-party bundle involved uses non-service controllers (which is almost always the case), you can easily override controllers via bundle inheritance. For more information, see How to use Bundle Inheritance to Override parts of a Bundle. If the controller is a service, see the next section on how to override it.

PDF brought to you by generated on February 10, 2014

Chapter 9: How to Override any Part of a Bundle | 33

Services & Configuration

In order to override/extend a service, there are two options. First, you can set the parameter holding the service's class name to your own class by setting it in app/config/config.yml. This of course is only possible if the class name is defined as a parameter in the service config of the bundle containing the service. For example, to override the class used for Symfony's translator service, you would override the translator.class parameter. Knowing exactly which parameter to override may take some research. For the translator, the parameter is defined and used in the Resources/config/translation.xml file in the core FrameworkBundle:
Listing 9-1

1 # app/config/config.yml 2 parameters: 3 translator.class: Acme\HelloBundle\Translation\Translator

Secondly, if the class is not available as a parameter, you want to make sure the class is always overridden when your bundle is used, or you need to modify something beyond just the class name, you should use a compiler pass:
Listing 9-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// 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'); } }

In this example you fetch the service definition of the original service, and set its class name to your own class. See How to work with Compiler Passes in Bundles for information on how to use compiler passes. If you want to do something beyond just overriding the class - like adding a method call - you can only use the compiler pass method.

Entities & Entity mapping

Due to the way Doctrine works, it is not possible to override entity mapping of a bundle. However, if a bundle provides a mapped superclass (such as the User entity in the FOSUserBundle) one can override attributes and associations. Learn more about this feature and its limitations in the Doctrine documentation1.

Forms
In order to override a form type, it has to be registered as a service (meaning it is tagged as "form.type"). You can then override it as you would override any service as explained in Services & Configuration. This, of course, will only work if the type is referred to by its alias rather than being instantiated, e.g.:
1. http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

PDF brought to you by generated on February 10, 2014

Chapter 9: How to Override any Part of a Bundle | 34

Listing 9-3

1 $builder->add('name', 'custom_type');

rather than:
Listing 9-4

1 $builder->add('name', new CustomType());

Validation metadata
Symfony loads all validation configuration files from every bundle and combines them into one validation metadata tree. This means you are able to add new constraints to a property, but you cannot override them. To override this, the 3rd party bundle needs to have configuration for validation groups. For instance, the FOSUserBundle has this configuration. To create your own validation, add the constraints to a new validation group:
Listing 9-5

1 # src/Acme/UserBundle/Resources/config/validation.yml 2 Fos\UserBundle\Model\User: 3 properties: 4 plainPassword: 5 - NotBlank: 6 groups: [AcmeValidation] 7 - Length: 8 min: 6 9 minMessage: fos_user.password.short 10 groups: [AcmeValidation]

Now, update the FOSUserBundle configuration, so it uses your validation groups instead of the original ones.

Translations
Translations are not related to bundles, but to domains. That means that you can override the translations from any translation file, as long as it is in the correct domain.
The last translation file always wins. That mean that you need to make sure that the bundle containing your translations is loaded after any bundle whose translations you're overriding. This is done in AppKernel. The file that always wins is the one that is placed in app/Resources/translations, as those files are always loaded last.

PDF brought to you by generated on February 10, 2014

Chapter 9: How to Override any Part of a Bundle | 35

Chapter 10

How to remove the AcmeDemoBundle

The Symfony2 Standard Edition comes with a complete demo that lives inside a bundle called AcmeDemoBundle. It is a great boilerplate to refer to while starting a project, but you'll probably want to eventually remove it.
This article uses the AcmeDemoBundle as an example, but you can use these steps to remove any bundle.

1. Unregister the bundle in the AppKernel

To disconnect the bundle from the framework, you should remove the bundle from the AppKernel::registerBundles() method. The bundle is normally found in the $bundles array but the AcmeDemoBundle is only registered in the development environment and you can find it inside the if statement below:
Listing 10-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

// app/AppKernel.php // ... class AppKernel extends Kernel { public function registerBundles() { $bundles = array(...);
if (in_array($this->getEnvironment(), array('dev', 'test'))) { // comment or remove this line: // $bundles[] = new Acme\DemoBundle\AcmeDemoBundle(); // ... } } }

PDF brought to you by generated on February 10, 2014

Chapter 10: How to remove the AcmeDemoBundle | 36

2. Remove bundle configuration

Now that Symfony doesn't know about the bundle, you need to remove any configuration and routing configuration inside the app/config directory that refers to the bundle.

2.1 Remove bundle routing

The routing for the AcmeDemoBundle can be found in app/config/routing_dev.yml. Remove the _acme_demo entry at the bottom of this file.

2.2 Remove bundle configuration

Some bundles contain configuration in one of the app/config/config*.yml files. Be sure to remove the related configuration from these files. You can quickly spot bundle configuration by looking for a acme_demo (or whatever the name of the bundle is, e.g. fos_user for the FOSUserBundle) string in the configuration files. The AcmeDemoBundle doesn't have configuration. However, the bundle is used in the configuration for the app/config/security.yml file. You can use it as a boilerplate for your own security, but you can also remove everything: it doesn't matter to Symfony if you remove it or not.

3. Remove the bundle from the Filesystem

Now you have removed every reference to the bundle in your application, you should remove the bundle from the filesystem. The bundle is located in the src/Acme/DemoBundle directory. You should remove this directory and you can remove the Acme directory as well.
If you don't know the location of a bundle, you can use the getPath()1 method to get the path of the bundle:
Listing 10-2

1 echo $this->container->get('kernel')->getBundle('AcmeDemoBundle')->getPath();

4. Remove integration in other bundles

This doesn't apply to the AcmeDemoBundle - no other bundles depend on it, so you can skip this step.

Some bundles rely on other bundles, if you remove one of the two, the other will probably not work. Be sure that no other bundles, third party or self-made, rely on the bundle you are about to remove.
If one bundle relies on another, in most it means that it uses some services from the bundle. Searching for the bundle alias string may help you spot them (e.g. acme_demo for bundles depending on AcmeDemoBundle).

1. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Bundle/BundleInterface.html#getPath()

PDF brought to you by generated on February 10, 2014

Chapter 10: How to remove the AcmeDemoBundle | 37

If a third party bundle relies on another bundle, you can find that bundle mentioned in the composer.json file included in the bundle directory.

PDF brought to you by generated on February 10, 2014

Chapter 10: How to remove the AcmeDemoBundle | 38

Chapter 11

How to expose a Semantic Configuration for a Bundle

If you open your application configuration file (usually app/config/config.yml), you'll see a number of different configuration "namespaces", such as framework, twig, and doctrine. Each of these configures a specific bundle, allowing you to configure things at a high level and then let the bundle make all the low-level, complex changes that result. For example, the following tells the FrameworkBundle to enable the form integration, which involves the defining of quite a few services as well as integration of other related components:
Listing 11-1

1 framework: 2 # ... 3 form: true

When you create a bundle, you have two choices on how to handle configuration: 1. Normal Service Configuration (easy): You can specify your services in a configuration file (e.g. services.yml) that lives in your bundle and then import it from your main application configuration. This is really easy, quick and totally effective. If you make use of parameters, then you still have the flexibility to customize your bundle from your application configuration. See "Importing Configuration with imports" for more details. 2. Exposing Semantic Configuration (advanced): This is the way configuration is done with the core bundles (as described above). The basic idea is that, instead of having the user override individual parameters, you let the user configure just a few, specifically created options. As the bundle developer, you then parse through that configuration and load services inside an "Extension" class. With this method, you won't need to import any configuration resources from your main application configuration: the Extension class can handle all of this.

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 39

The second option - which you'll learn about in this article - is much more flexible, but also requires more time to setup. If you're wondering which method you should use, it's probably a good idea to start with method #1, and then change to #2 later if you need to. If you plan to distribute your bundle, the second option is recommended. The second method has several specific advantages: Much more powerful than simply defining parameters: a specific option value might trigger the creation of many service definitions; Ability to have configuration hierarchy; Smart merging when several configuration files (e.g. config_dev.yml and config.yml) override each other's configuration; Configuration validation (if you use a Configuration Class); IDE auto-completion when you create an XSD and developers use XML.

Overriding bundle parameters

If a Bundle provides an Extension class, then you should generally not override any service container parameters from that bundle. The idea is that if an Extension class is present, every setting that should be configurable should be present in the configuration made available by that class. In other words the extension class defines all the publicly supported configuration settings for which backward compatibility will be maintained.

Creating an Extension Class

If you do choose to expose a semantic configuration for your bundle, you'll first need to create a new "Extension" class, which will handle the process. This class should live in the DependencyInjection directory of your bundle and its name should be constructed by replacing the Bundle suffix of the Bundle class name with Extension. For example, the Extension class of AcmeHelloBundle would be called AcmeHelloExtension:
Listing 11-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php namespace Acme\HelloBundle\DependencyInjection;

use Symfony\Component\HttpKernel\DependencyInjection\Extension; use Symfony\Component\DependencyInjection\ContainerBuilder; class AcmeHelloExtension extends Extension { public function load(array $configs, ContainerBuilder $container) { // ... where all of the heavy logic is done } public function getXsdValidationBasePath() { return __DIR__.'/../Resources/config/'; } public function getNamespace() { return 'http://www.example.com/symfony/schema/'; } }

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 40

The getXsdValidationBasePath and getNamespace methods are only required if the bundle provides optional XSD's for the configuration.

The presence of the previous class means that you can now define an acme_hello configuration namespace in any configuration file. The namespace acme_hello is constructed from the extension's class name by removing the word Extension and then lowercasing and underscoring the rest of the name. In other words, AcmeHelloExtension becomes acme_hello. You can begin specifying configuration under this namespace immediately:
Listing 11-3

1 # app/config/config.yml 2 acme_hello: ~

If you follow the naming conventions laid out above, then the load() method of your extension code is always called as long as your bundle is registered in the Kernel. In other words, even if the user does not provide any configuration (i.e. the acme_hello entry doesn't even appear), the load() method will be called and passed an empty $configs array. You can still provide some sensible defaults for your bundle if you want.

Registering the Extension Class

An Extension class will automatically be registered by Symfony2 when following these simple conventions: The extension must be stored in the DependencyInjection sub-namespace; The extension must be named after the bundle name and suffixed with Extension (AcmeHelloExtension for AcmeHelloBundle); The extension should provide an XSD schema (but will be registered automatically regardless).

Manually Registering an Extension Class

When not following the conventions, you will have to manually register your extension. To manually register an extension class override the Bundle::build()1 method in your bundle:
Listing 11-4

1 2 3 4 5 6 7 8 9 10 11 12 13

// ... use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass;

class AcmeHelloBundle extends Bundle { public function build(ContainerBuilder $container) { parent::build($container);

// register extensions that do not follow the conventions manually $container->registerExtension(new UnconventionalExtensionClass());
} }

1. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Bundle/Bundle.html#build()

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 41

In this case, the extension class must also implement a getAlias() method and return a unique alias named after the bundle (e.g. acme_hello). This is required because the class name doesn't follow the conventions by ending in Extension. Additionally, the load() method of your extension will only be called if the user specifies the acme_hello alias in at least one configuration file. Once again, this is because the Extension class doesn't follow the conventions set out above, so nothing happens automatically.

Parsing the $configs Array

Whenever a user includes the acme_hello namespace in a configuration file, the configuration under it is added to an array of configurations and passed to the load() method of your extension (Symfony2 automatically converts XML and YAML to an array). Take the following configuration:
Listing 11-5

1 # app/config/config.yml 2 acme_hello: 3 foo: fooValue 4 bar: barValue

The array passed to your load() method will look like this:
Listing 11-6

1 array( 2 array( 3 'foo' => 'fooValue', 4 'bar' => 'barValue', 5 ), 6 )

Notice that this is an array of arrays, not just a single flat array of the configuration values. This is intentional. For example, if acme_hello appears in another configuration file - say config_dev.yml with different values beneath it, then the incoming array might look like this:
Listing 11-7

1 array( 2 array( 3 'foo' 4 'bar' 5 ), 6 array( 7 'foo' 8 'baz' 9 ), 10 )

=> 'fooValue', => 'barValue', => 'fooDevValue', => 'newConfigEntry',

The order of the two arrays depends on which one is set first. It's your job, then, to decide how these configurations should be merged together. You might, for example, have later values override previous values or somehow merge them together. Later, in the Configuration Class section, you'll learn of a truly robust way to handle this. But for now, you might just merge them manually:
Listing 11-8

1 public function load(array $configs, ContainerBuilder $container) 2 { 3 $config = array();

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 42

4 5 6 7 8 9 }

foreach ($configs as $subConfig) { $config = array_merge($config, $subConfig); }

// ... now use the flat $config array

Make sure the above merging technique makes sense for your bundle. This is just an example, and you should be careful to not use it blindly.

Using the load() Method

Within load(), the $container variable refers to a container that only knows about this namespace configuration (i.e. it doesn't contain service information loaded from other bundles). The goal of the load() method is to manipulate the container, adding and configuring any methods or services needed by your bundle.

Loading External Configuration Resources

One common thing to do is to load an external configuration file that may contain the bulk of the services needed by your bundle. For example, suppose you have a services.xml file that holds much of your bundle's service configuration:
Listing 11-9

1 2 3 4 5 6 7 8 9 10 11 12 13

use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; use Symfony\Component\Config\FileLocator; public function load(array $configs, ContainerBuilder $container) { // ... prepare your $config variable $loader = new XmlFileLoader( $container, new FileLocator(__DIR__.'/../Resources/config') ); $loader->load('services.xml'); }

You might even do this conditionally, based on one of the configuration values. For example, suppose you only want to load a set of services if an enabled option is passed and set to true:
Listing 11-10

1 public function load(array $configs, ContainerBuilder $container) 2 { 3 // ... prepare your $config variable 4 5 $loader = new XmlFileLoader( 6 $container, 7 new FileLocator(__DIR__.'/../Resources/config') 8 ); 9 10 if (isset($config['enabled']) && $config['enabled']) { 11 $loader->load('services.xml');

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 43

12 13 }

Configuring Services and Setting Parameters

Once you've loaded some service configuration, you may need to modify the configuration based on some of the input values. For example, suppose you have a service whose first argument is some string "type" that it will use internally. You'd like this to be easily configured by the bundle user, so in your service configuration file (e.g. services.xml), you define this service and use a blank parameter acme_hello.my_service_type - as its first argument:
Listing 11-11

1 <!-- src/Acme/HelloBundle/Resources/config/services.xml --> 2 <container xmlns="http://symfony.com/schema/dic/services" 3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 4 xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/ 5 dic/services/services-1.0.xsd"> 6 7 <parameters> 8 <parameter key="acme_hello.my_service_type" /> 9 </parameters> 10 11 <services> 12 <service id="acme_hello.my_service" class="Acme\HelloBundle\MyService"> 13 <argument>%acme_hello.my_service_type%</argument> 14 </service> 15 </services> </container>

But why would you define an empty parameter and then pass it to your service? The answer is that you'll set this parameter in your extension class, based on the incoming configuration values. Suppose, for example, that you want to allow the user to define this type option under a key called my_type. Add the following to the load() method to do this:
Listing 11-12

1 public function load(array $configs, ContainerBuilder $container) 2 { 3 // ... prepare your $config variable 4 5 $loader = new XmlFileLoader( 6 $container, 7 new FileLocator(__DIR__.'/../Resources/config') 8 ); 9 $loader->load('services.xml'); 10 11 if (!isset($config['my_type'])) { 12 throw new \InvalidArgumentException( 13 'The "my_type" option must be set' 14 ); 15 } 16 17 $container->setParameter( 18 'acme_hello.my_service_type', 19 $config['my_type'] 20 ); 21 }

Now, the user can effectively configure the service by specifying the my_type configuration value:
PDF brought to you by generated on February 10, 2014 Chapter 11: How to expose a Semantic Configuration for a Bundle | 44

Listing 11-13

1 # app/config/config.yml 2 acme_hello: 3 my_type: foo 4 # ...

Global Parameters
When you're configuring the container, be aware that you have the following global parameters available to use: kernel.name kernel.environment kernel.debug kernel.root_dir kernel.cache_dir kernel.logs_dir kernel.bundles kernel.charset
All parameter and service names starting with a _ are reserved for the framework, and new ones must not be defined by bundles.

Validation and Merging with a Configuration Class

So far, you've done the merging of your configuration arrays by hand and are checking for the presence of config values manually using the isset() PHP function. An optional Configuration system is also available which can help with merging, validation, default values, and format normalization.
Format normalization refers to the fact that certain formats - largely XML - result in slightly different configuration arrays and that these arrays need to be "normalized" to match everything else.

To take advantage of this system, you'll create a Configuration class and build a tree that defines your configuration in that class:
Listing 11-14

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// src/Acme/HelloBundle/DependencyInjection/Configuration.php namespace Acme\HelloBundle\DependencyInjection;

use Symfony\Component\Config\Definition\Builder\TreeBuilder; use Symfony\Component\Config\Definition\ConfigurationInterface; class Configuration implements ConfigurationInterface { public function getConfigTreeBuilder() { $treeBuilder = new TreeBuilder(); $rootNode = $treeBuilder->root('acme_hello'); $rootNode

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 45

15 16 17 18 19 20 21 }

->children() ->scalarNode('my_type')->defaultValue('bar')->end() ->end(); return $treeBuilder; }

This is a very simple example, but you can now use this class in your load() method to merge your configuration and force validation. If any options other than my_type are passed, the user will be notified with an exception that an unsupported option was passed:
Listing 11-15

1 public function load(array $configs, ContainerBuilder $container) 2 { 3 $configuration = new Configuration(); 4 5 $config = $this->processConfiguration($configuration, $configs); 6 7 // ... 8 }

The processConfiguration() method uses the configuration tree you've defined in the Configuration class to validate, normalize and merge all of the configuration arrays together. The Configuration class can be much more complicated than shown here, supporting array nodes, "prototype" nodes, advanced validation, XML-specific normalization and advanced merging. You can read more about this in the Config component documentation. You can also see it in action by checking out some of the core Configuration classes, such as the one from the FrameworkBundle Configuration2 or the TwigBundle Configuration3.

Modifying the configuration of another Bundle

If you have multiple bundles that depend on each other, it may be useful to allow one Extension class to modify the configuration passed to another bundle's Extension class, as if the end-developer has actually placed that configuration in their app/config/config.yml file. For more details, see How to simplify configuration of multiple Bundles.

Default Configuration Dump

The config:dump-reference command allows a bundle's default configuration to be output to the console in YAML. As long as your bundle's configuration is located in the standard location (YourBundle\DependencyInjection\Configuration) and does not have a __construct() it will work automatically. If you have something different, your Extension class must override the Extension::getConfiguration()4 method and return an instance of your Configuration. Comments and examples can be added to your configuration nodes using the ->info() and >example() methods:
Listing 11-16

1 // src/Acme/HelloBundle/DependencyExtension/Configuration.php 2 namespace Acme\HelloBundle\DependencyInjection;

2. https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php 3. https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php 4. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/DependencyInjection/Extension.html#getConfiguration()

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 46

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

use Symfony\Component\Config\Definition\Builder\TreeBuilder; use Symfony\Component\Config\Definition\ConfigurationInterface; class Configuration implements ConfigurationInterface { public function getConfigTreeBuilder() { $treeBuilder = new TreeBuilder(); $rootNode = $treeBuilder->root('acme_hello'); $rootNode ->children() ->scalarNode('my_type') ->defaultValue('bar') ->info('what my_type configures') ->example('example setting') ->end() ->end() ; return $treeBuilder; } }

This text appears as YAML comments in the output of the config:dump-reference command.

PDF brought to you by generated on February 10, 2014

Chapter 11: How to expose a Semantic Configuration for a Bundle | 47

Chapter 12

How to simplify configuration of multiple Bundles

When building reusable and extensible applications, developers are often faced with a choice: either create a single large Bundle or multiple smaller Bundles. Creating a single Bundle has the draw back that it's impossible for users to choose to remove functionality they are not using. Creating multiple Bundles has the draw back that configuration becomes more tedious and settings often need to be repeated for various Bundles. Using the below approach, it is possible to remove the disadvantage of the multiple Bundle approach by enabling a single Extension to prepend the settings for any Bundle. It can use the settings defined in the app/config/config.yml to prepend settings just as if they would have been written explicitly by the user in the application configuration. For example, this could be used to configure the entity manager name to use in multiple Bundles. Or it can be used to enable an optional feature that depends on another Bundle being loaded as well. To give an Extension the power to do this, it needs to implement PrependExtensionInterface1:
Listing 12-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

// src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php namespace Acme\HelloBundle\DependencyInjection;

use Symfony\Component\HttpKernel\DependencyInjection\Extension; use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface; use Symfony\Component\DependencyInjection\ContainerBuilder; class AcmeHelloExtension extends Extension implements PrependExtensionInterface { // ... public function prepend(ContainerBuilder $container) { // ... } }

1. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/Extension/PrependExtensionInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 12: How to simplify configuration of multiple Bundles | 48

Inside the prepend()2 method, developers have full access to the ContainerBuilder3 instance just before the load()4 method is called on each of the registered Bundle Extensions. In order to prepend settings to a Bundle extension developers can use the prependExtensionConfig()5 method on the ContainerBuilder6 instance. As this method only prepends settings, any other settings done explicitly inside the app/config/config.yml would override these prepended settings. The following example illustrates how to prepend a configuration setting in multiple Bundles as well as disable a flag in multiple Bundles in case a specific other Bundle is not registered:
Listing 12-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

public function prepend(ContainerBuilder $container) { // get all Bundles $bundles = $container->getParameter('kernel.bundles'); // determine if AcmeGoodbyeBundle is registered if (!isset($bundles['AcmeGoodbyeBundle'])) { // disable AcmeGoodbyeBundle in Bundles $config = array('use_acme_goodbye' => false); foreach ($container->getExtensions() as $name => $extension) { switch ($name) { case 'acme_something': case 'acme_other': // set use_acme_goodbye to false in the config of acme_something and acme_other // note that if the user manually configured use_acme_goodbye to true in the // app/config/config.yml then the setting would in the end be true and not false $container->prependExtensionConfig($name, $config); break; } } }

// process the configuration of AcmeHelloExtension $configs = $container->getExtensionConfig($this->getAlias()); // use the Configuration class to generate a config array with the settings ``acme_hello`` $config = $this->processConfiguration(new Configuration(), $configs); // check if entity_manager_name is set in the ``acme_hello`` configuration if (isset($config['entity_manager_name'])) { // prepend the acme_something settings with the entity_manager_name $config = array('entity_manager_name' => $config['entity_manager_name']); $container->prependExtensionConfig('acme_something', $config); }
}

The above would be the equivalent of writing the following into the app/config/config.yml in case AcmeGoodbyeBundle is not registered and the entity_manager_name setting for acme_hello is set to non_default:
Listing 12-3

1 # app/config/config.yml 2 acme_something:

2. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/Extension/PrependExtensionInterface.html#prepend() 3. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/ContainerBuilder.html 4. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/Extension/ExtensionInterface.html#load() 5. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/ContainerBuilder.html#prependExtensionConfig() 6. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/ContainerBuilder.html

PDF brought to you by generated on February 10, 2014

Chapter 12: How to simplify configuration of multiple Bundles | 49

3 # ... 4 use_acme_goodbye: false 5 entity_manager_name: non_default 6 7 acme_other: 8 # ... 9 use_acme_goodbye: false

PDF brought to you by generated on February 10, 2014

Chapter 12: How to simplify configuration of multiple Bundles | 50

Chapter 13

How to use Varnish to speed up my Website

Because Symfony2's cache uses the standard HTTP cache headers, the Symfony2 Reverse Proxy can easily be replaced with any other reverse proxy. Varnish1 is a powerful, open-source, HTTP accelerator capable of serving cached content quickly and including support for Edge Side Includes.

Configuration
As seen previously, Symfony2 is smart enough to detect whether it talks to a reverse proxy that understands ESI or not. It works out of the box when you use the Symfony2 reverse proxy, but you need a special configuration to make it work with Varnish. Thankfully, Symfony2 relies on yet another standard written by Akamai (Edge Architecture2), so the configuration tips in this chapter can be useful even if you don't use Symfony2.
Varnish only supports the src attribute for ESI tags (onerror and alt attributes are ignored).

First, configure Varnish so that it advertises its ESI support by adding a Surrogate-Capability header to requests forwarded to the backend application:
Listing 13-1

1 sub vcl_recv { 2 // Add a Surrogate-Capability header to announce ESI support. 3 set req.http.Surrogate-Capability = "abc=ESI/1.0"; 4 }

Then, optimize Varnish so that it only parses the Response contents when there is at least one ESI tag by checking the Surrogate-Control header that Symfony2 adds automatically:
Listing 13-2

1. https://www.varnish-cache.org 2. http://www.w3.org/TR/edge-arch

PDF brought to you by generated on February 10, 2014

Chapter 13: How to use Varnish to speed up my Website | 51

1 sub vcl_fetch { 2 /* 3 Check for ESI acknowledgement 4 and remove Surrogate-Control header 5 */ 6 if (beresp.http.Surrogate-Control ~ "ESI/1.0") { 7 unset beresp.http.Surrogate-Control; 8 9 // For Varnish >= 3.0 10 set beresp.do_esi = true; 11 // For Varnish < 3.0 12 // esi; 13 } 14 }

Compression with ESI was not supported in Varnish until version 3.0 (read GZIP and Varnish3). If you're not using Varnish 3.0, put a web server in front of Varnish to perform the compression.

Cache Invalidation
You should never need to invalidate cached data because invalidation is already taken into account natively in the HTTP cache models (see Cache Invalidation). Still, Varnish can be configured to accept a special HTTP PURGE method that will invalidate the cache for a given resource:
Listing 13-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

/* Connect to the backend server on the local machine on port 8080 */ backend default { .host = "127.0.0.1"; .port = "8080"; } sub vcl_recv { /* Varnish default behavior doesn't support PURGE. Match the PURGE request and immediately do a cache lookup, otherwise Varnish will directly pipe the request to the backend and bypass the cache */ if (req.request == "PURGE") { return(lookup); } } sub vcl_hit { // Match PURGE request if (req.request == "PURGE") { // Force object expiration for Varnish < 3.0 set obj.ttl = 0s;

3. https://www.varnish-cache.org/docs/3.0/phk/gzip.html

PDF brought to you by generated on February 10, 2014

Chapter 13: How to use Varnish to speed up my Website | 52

27 28 29 30 31 } 32 33 sub 34 35 36 37 38 39 40 41 }

// Do an actual purge for Varnish >= 3.0 // purge; error 200 "Purged"; } vcl_miss { /* Match the PURGE request and indicate the request wasn't stored in cache. */ if (req.request == "PURGE") { error 404 "Not purged"; }

PDF brought to you by generated on February 10, 2014

Chapter 13: How to use Varnish to speed up my Website | 53

You must protect the PURGE HTTP method somehow to avoid random people purging your cached data. You can do this by setting up an access list:
Listing 13-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

/* Connect to the backend server on the local machine on port 8080 */ backend default { .host = "127.0.0.1"; .port = "8080"; } // ACL's can contain IP's, subnets and hostnames acl purge { "localhost"; "192.168.55.0"/24; } sub vcl_recv { // Match PURGE request to avoid cache bypassing if (req.request == "PURGE") { // Match client IP to the ACL if (!client.ip ~ purge) { // Deny access error 405 "Not allowed."; } // Perform a cache lookup return(lookup); } } sub vcl_hit { // Match PURGE request if (req.request == "PURGE") { // Force object expiration for Varnish < 3.0 set obj.ttl = 0s; // Do an actual purge for Varnish >= 3.0 // purge; error 200 "Purged"; } } sub vcl_miss { // Match PURGE request if (req.request == "PURGE") { // Indicate that the object isn't stored in cache error 404 "Not purged"; } }

Routing and X-FORWARDED Headers

To ensure that the Symfony Router generates URLs correctly with Varnish, proper `X-Forwarded` headers must be added so that Symfony is aware of the original port number of the request. Exactly how this is done depends on your setup. As a simple example, Varnish and your web server are on the same machine and that Varnish is listening on one port (e.g. 80) and Apache on another (e.g. 8080). In this situation, Varnish should add the X-Forwarded-Port header so that the Symfony application knows that the original port number is 80 and not 8080.
PDF brought to you by generated on February 10, 2014 Chapter 13: How to use Varnish to speed up my Website | 54

If this header weren't set properly, Symfony may append 8080 when generating absolute URLs:
Listing 13-5

1 sub vcl_recv { 2 if (req.http.X-Forwarded-Proto == "https" ) { 3 set req.http.X-Forwarded-Port = "443"; 4 } else { 5 set req.http.X-Forwarded-Port = "80"; 6 } 7 }

Remember to configure framework.trusted_proxies in the Symfony configuration so that Varnish is seen as a trusted proxy and the X-Forwarded- headers are used.

PDF brought to you by generated on February 10, 2014

Chapter 13: How to use Varnish to speed up my Website | 55

Chapter 14

How to Master and Create new Environments

Every application is the combination of code and a set of configuration that dictates how that code should function. The configuration may define the database being used, whether or not something should be cached, or how verbose logging should be. In Symfony2, the idea of "environments" is the idea that the same codebase can be run using multiple different configurations. For example, the dev environment should use configuration that makes development easy and friendly, while the prod environment should use a set of configuration optimized for speed.

Different Environments, Different Configuration Files

A typical Symfony2 application begins with three environments: dev, prod, and test. As discussed, each "environment" simply represents a way to execute the same codebase with different configuration. It should be no surprise then that each environment loads its own individual configuration file. If you're using the YAML configuration format, the following files are used: for the dev environment: app/config/config_dev.yml for the prod environment: app/config/config_prod.yml for the test environment: app/config/config_test.yml This works via a simple standard that's used by default inside the AppKernel class:
Listing 14-1

1 2 3 4 5 6 7 8 9 10 11 12 13

// app/AppKernel.php // ...
class AppKernel extends Kernel { // ... public function registerContainerConfiguration(LoaderInterface $loader) { $loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml'); } }

PDF brought to you by generated on February 10, 2014

Chapter 14: How to Master and Create new Environments | 56

As you can see, when Symfony2 is loaded, it uses the given environment to determine which configuration file to load. This accomplishes the goal of multiple environments in an elegant, powerful and transparent way. Of course, in reality, each environment differs only somewhat from others. Generally, all environments will share a large base of common configuration. Opening the "dev" configuration file, you can see how this is accomplished easily and transparently:
Listing 14-2

1 imports: 2 - { resource: config.yml } 3 4 # ...

To share common configuration, each environment's configuration file simply first imports from a central configuration file (config.yml). The remainder of the file can then deviate from the default configuration by overriding individual parameters. For example, by default, the web_profiler toolbar is disabled. However, in the dev environment, the toolbar is activated by modifying the default value in the dev configuration file:
Listing 14-3

1 # app/config/config_dev.yml 2 imports: 3 - { resource: config.yml } 4 5 web_profiler: 6 toolbar: true 7 # ...

Executing an Application in Different Environments

To execute the application in each environment, load up the application using either the app.php (for the prod environment) or the app_dev.php (for the dev environment) front controller:
Listing 14-4

1 http://localhost/app.php 2 http://localhost/app_dev.php

-> *prod* environment -> *dev* environment

The given URLs assume that your web server is configured to use the web/ directory of the application as its root. Read more in Installing Symfony2.

If you open up one of these files, you'll quickly see that the environment used by each is explicitly set:
Listing 14-5

1 2 3 4 5 6

// web/app.php // ...
$kernel = new AppKernel('prod', false);

// ...

As you can see, the prod key specifies that this environment will run in the prod environment. A Symfony2 application can be executed in any environment by using this code and changing the environment string.

PDF brought to you by generated on February 10, 2014

Chapter 14: How to Master and Create new Environments | 57

The test environment is used when writing functional tests and is not accessible in the browser directly via a front controller. In other words, unlike the other environments, there is no app_test.php front controller file.

Debug Mode
Important, but unrelated to the topic of environments is the false argument as the second argument to the AppKernel constructor. This specifies whether or not the application should run in "debug mode". Regardless of the environment, a Symfony2 application can be run with debug mode set to true or false. This affects many things in the application, such as whether or not errors should be displayed or if cache files are dynamically rebuilt on each request. Though not a requirement, debug mode is generally set to true for the dev and test environments and false for the prod environment. Internally, the value of the debug mode becomes the kernel.debug parameter used inside the service container. If you look inside the application configuration file, you'll see the parameter used, for example, to turn logging on or off when using the Doctrine DBAL:
Listing 14-6

1 doctrine: 2 dbal: 3 logging: "%kernel.debug%" 4 # ...

As of Symfony 2.3, showing errors or not no longer depends on the debug mode. You'll need to enable that in your front controller by calling enable()1.

Creating a New Environment

By default, a Symfony2 application has three environments that handle most cases. Of course, since an environment is nothing more than a string that corresponds to a set of configuration, creating a new environment is quite easy. Suppose, for example, that before deployment, you need to benchmark your application. One way to benchmark the application is to use near-production settings, but with Symfony2's web_profiler enabled. This allows Symfony2 to record information about your application while benchmarking. The best way to accomplish this is via a new environment called, for example, benchmark. Start by creating a new configuration file:
Listing 14-7

1 # app/config/config_benchmark.yml 2 imports: 3 - { resource: config_prod.yml } 4 5 framework: 6 profiler: { only_exceptions: false }

And with this simple addition, the application now supports a new environment called benchmark. This new configuration file imports the configuration from the prod environment and modifies it. This guarantees that the new environment is identical to the prod environment, except for any changes explicitly made here.

1. http://api.symfony.com/2.4/Symfony/Component/Debug/Debug.html#enable()

PDF brought to you by generated on February 10, 2014

Chapter 14: How to Master and Create new Environments | 58

Because you'll want this environment to be accessible via a browser, you should also create a front controller for it. Copy the web/app.php file to web/app_benchmark.php and edit the environment to be benchmark:
Listing 14-8

1 2 3 4 5 6 7

// web/app_benchmark.php // change just this line $kernel = new AppKernel('benchmark', false); // ...

The new environment is now accessible via:

Listing 14-9

1 http://localhost/app_benchmark.php

Some environments, like the dev environment, are never meant to be accessed on any deployed server by the general public. This is because certain environments, for debugging purposes, may give too much information about the application or underlying infrastructure. To be sure these environments aren't accessible, the front controller is usually protected from external IP addresses via the following code at the top of the controller:
1 if (!in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', '::1'))) { 2 die('You are not allowed to access this file. Check 3 '.basename(__FILE__).' for more information.'); }

Listing 14-10

Environments and the Cache Directory

Symfony2 takes advantage of caching in many ways: the application configuration, routing configuration, Twig templates and more are cached to PHP objects stored in files on the filesystem. By default, these cached files are largely stored in the app/cache directory. However, each environment caches its own set of files:
Listing 14-11

1 app/cache/dev 2 app/cache/prod

- cache directory for the *dev* environment - cache directory for the *prod* environment

Sometimes, when debugging, it may be helpful to inspect a cached file to understand how something is working. When doing so, remember to look in the directory of the environment you're using (most commonly dev while developing and debugging). While it can vary, the app/cache/dev directory includes the following: appDevDebugProjectContainer.php - the cached "service container" that represents the cached application configuration; appDevUrlGenerator.php - the PHP class generated from the routing configuration and used when generating URLs; appDevUrlMatcher.php - the PHP class used for route matching - look here to see the compiled regular expression logic used to match incoming URLs to different routes; twig/ - this directory contains all the cached Twig templates.

PDF brought to you by generated on February 10, 2014

Chapter 14: How to Master and Create new Environments | 59

You can easily change the directory location and name. For more information read the article How to override Symfony's Default Directory Structure.

Going Further
Read the article on How to Set External Parameters in the Service Container.

PDF brought to you by generated on February 10, 2014

Chapter 14: How to Master and Create new Environments | 60

Chapter 15

How to override Symfony's Default Directory Structure

Symfony automatically ships with a default directory structure. You can easily override this directory structure to create your own. The default directory structure is:
Listing 15-1

1 2 3 4 5 6 7 8 9 10 11 12

app/ cache/ config/ logs/ ... src/ ... vendor/ ... web/ app.php ...

Override the cache directory

You can override the cache directory by overriding the getCacheDir method in the AppKernel class of you application:
Listing 15-2

1 2 3 4 5 6 7 8

// app/AppKernel.php // ... class AppKernel extends Kernel { // ...

public function getCacheDir()

PDF brought to you by generated on February 10, 2014

Chapter 15: How to override Symfony's Default Directory Structure | 61

9 10 11 12 }

{ return $this->rootDir.'/'.$this->environment.'/cache'; }

$this->rootDir is the absolute path to the app directory and $this->environment is the current environment (i.e. dev). In this case you have changed the location of the cache directory to app/ {environment}/cache.
You should keep the cache directory different for each environment, otherwise some unexpected behavior may happen. Each environment generates its own cached config files, and so each needs its own directory to store those cache files.

Override the logs directory

Overriding the logs directory is the same as overriding the cache directory, the only difference is that you need to override the getLogDir method:
Listing 15-3

1 2 3 4 5 6 7 8 9 10 11 12

// app/AppKernel.php // ... class AppKernel extends Kernel { // ...

public function getLogDir() { return $this->rootDir.'/'.$this->environment.'/logs'; } }

Here you have changed the location of the directory to app/{environment}/logs.

Override the web directory

If you need to rename or move your web directory, the only thing you need to guarantee is that the path to the app directory is still correct in your app.php and app_dev.php front controllers. If you simply renamed the directory, you're fine. But if you moved it in some way, you may need to modify the paths inside these files:
Listing 15-4

1 require_once __DIR__.'/../Symfony/app/bootstrap.php.cache'; 2 require_once __DIR__.'/../Symfony/app/AppKernel.php';

You also need to change the extra.symfony-web-dir option in the composer.json file:
Listing 15-5

{ ... "extra": { ... "symfony-web-dir": "my_new_web_dir"

PDF brought to you by generated on February 10, 2014

Chapter 15: How to override Symfony's Default Directory Structure | 62

} }

Some shared hosts have a public_html web directory root. Renaming your web directory from web to public_html is one way to make your Symfony project work on your shared host. Another way is to deploy your application to a directory outside of your web root, delete your public_html directory, and then replace it with a symbolic link to the web in your project.

If you use the AsseticBundle you need to configure this, so it can use the correct web directory:
Listing 15-6

1 # app/config/config.yml 2 3 # ... 4 assetic: 5 # ... 6 read_from: "%kernel.root_dir%/../../public_html"

Now you just need to dump the assets again and your application should work:
Listing 15-7

1 $ php app/console assetic:dump --env=prod --no-debug

PDF brought to you by generated on February 10, 2014

Chapter 15: How to override Symfony's Default Directory Structure | 63

Chapter 16

Understanding how the Front Controller, Kernel and Environments work together
The section How to Master and Create new Environments explained the basics on how Symfony uses environments to run your application with different configuration settings. This section will explain a bit more in-depth what happens when your application is bootstrapped. To hook into this process, you need to understand three parts that work together: The Front Controller The Kernel Class The Environments
Usually, you will not need to define your own front controller or AppKernel class as the Symfony2 Standard Edition1 provides sensible default implementations. This documentation section is provided to explain what is going on behind the scenes.

The Front Controller

The front controller2 is a well-known design pattern; it is a section of code that all requests served by an application run through. In the Symfony2 Standard Edition3, this role is taken by the app.php4 and app_dev.php5 files in the web/ directory. These are the very first PHP scripts executed when a request is processed. The main purpose of the front controller is to create an instance of the AppKernel (more on that in a second), make it handle the request and return the resulting response to the browser.

1. https://github.com/symfony/symfony-standard 2. http://en.wikipedia.org/wiki/Front_Controller_pattern 3. https://github.com/symfony/symfony-standard 4. https://github.com/symfony/symfony-standard/blob/master/web/app.php 5. https://github.com/symfony/symfony-standard/blob/master/web/app_dev.php

PDF brought to you by generated on February 10, 2014

Chapter 16: Understanding how the Front Controller, Kernel and Environments work together | 64

Because every request is routed through it, the front controller can be used to perform global initializations prior to setting up the kernel or to decorate6 the kernel with additional features. Examples include: Configuring the autoloader or adding additional autoloading mechanisms; Adding HTTP level caching by wrapping the kernel with an instance of AppCache; Enabling (or skipping) the ClassCache Enabling the Debug component.

The front controller can be chosen by requesting URLs like:

Listing 16-1

1 http://localhost/app_dev.php/some/path/...

As you can see, this URL contains the PHP script to be used as the front controller. You can use that to easily switch the front controller or use a custom one by placing it in the web/ directory (e.g. app_cache.php). When using Apache and the RewriteRule shipped with the Standard Edition7, you can omit the filename from the URL and the RewriteRule will use app.php as the default one.
Pretty much every other web server should be able to achieve a behavior similar to that of the RewriteRule described above. Check your server documentation for details or see Configuring a web server.

Make sure you appropriately secure your front controllers against unauthorized access. For example, you don't want to make a debugging environment available to arbitrary users in your production environment.

Technically, the app/console8 script used when running Symfony on the command line is also a front controller, only that is not used for web, but for command line requests.

The Kernel Class

The Kernel9 is the core of Symfony2. It is responsible for setting up all the bundles that make up your application and providing them with the application's configuration. It then creates the service container before serving requests in its handle()10 method. There are two methods declared in the KernelInterface11 that are left unimplemented in Kernel12 and thus serve as template methods13: registerBundles()14, which must return an array of all bundles needed to run the application; registerContainerConfiguration()15, which loads the application configuration.

6. http://en.wikipedia.org/wiki/Decorator_pattern 7. https://github.com/symfony/symfony-standard/blob/master/web/.htaccess) 8. https://github.com/symfony/symfony-standard/blob/master/app/console 9. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Kernel.html 10. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/HttpKernelInterface.html#handle() 11. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelInterface.html 12. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Kernel.html 13. http://en.wikipedia.org/wiki/Template_method_pattern 14. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelInterface.html#registerBundles() 15. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelInterface.html#registerContainerConfiguration()

PDF brought to you by generated on February 10, 2014

Chapter 16: Understanding how the Front Controller, Kernel and Environments work together | 65

To fill these (small) blanks, your application needs to subclass the Kernel and implement these methods. The resulting class is conventionally called the AppKernel. Again, the Symfony2 Standard Edition provides an AppKernel16 in the app/ directory. This class uses the name of the environment - which is passed to the Kernel's constructor17 method and is available via getEnvironment()18 - to decide which bundles to create. The logic for that is in registerBundles(), a method meant to be extended by you when you start adding bundles to your application. You are, of course, free to create your own, alternative or additional AppKernel variants. All you need is to adapt your (or add a new) front controller to make use of the new kernel.
The name and location of the AppKernel is not fixed. When putting multiple Kernels into a single application, it might therefore make sense to add additional sub-directories, for example app/admin/AdminKernel.php and app/api/ApiKernel.php. All that matters is that your front controller is able to create an instance of the appropriate kernel.

Having different AppKernels might be useful to enable different front controllers (on potentially different servers) to run parts of your application independently (for example, the admin UI, the frontend UI and database migrations).
There's a lot more the AppKernel can be used for, for example overriding the default directory structure. But odds are high that you don't need to change things like this on the fly by having several AppKernel implementations.

The Environments
As just mentioned, the AppKernel has to implement another method registerContainerConfiguration()19. This method is responsible for loading the application's configuration from the right environment. Environments have been covered extensively in the previous chapter, and you probably remember that the Standard Edition comes with three of them - dev, prod and test. More technically, these names are nothing more than strings passed from the front controller to the AppKernel's constructor. This name can then be used in the registerContainerConfiguration()20 method to decide which configuration files to load. The Standard Edition's AppKernel21 class implements this method by simply loading the app/config/ config_*environment*.yml file. You are, of course, free to implement this method differently if you need a more sophisticated way of loading your configuration.

16. https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php 17. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Kernel.html#__construct() 18. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Kernel.html#getEnvironment() 19. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelInterface.html#registerContainerConfiguration() 20. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelInterface.html#registerContainerConfiguration() 21. https://github.com/symfony/symfony-standard/blob/master/app/AppKernel.php

PDF brought to you by generated on February 10, 2014

Chapter 16: Understanding how the Front Controller, Kernel and Environments work together | 66

Chapter 17

How to Set External Parameters in the Service Container

In the chapter How to Master and Create new Environments, you learned how to manage your application configuration. At times, it may benefit your application to store certain credentials outside of your project code. Database configuration is one such example. The flexibility of the Symfony service container allows you to easily do this.

Environment Variables
Symfony will grab any environment variable prefixed with SYMFONY__ and set it as a parameter in the service container. Double underscores are replaced with a period, as a period is not a valid character in an environment variable name. For example, if you're using Apache, environment variables can be set using the following VirtualHost configuration:
Listing 17-1

1 <VirtualHost *:80> 2 ServerName Symfony2 3 DocumentRoot "/path/to/symfony_2_app/web" 4 DirectoryIndex index.php index.html 5 SetEnv SYMFONY__DATABASE__USER user 6 SetEnv SYMFONY__DATABASE__PASSWORD secret 7 8 <Directory "/path/to/symfony_2_app/web"> 9 AllowOverride All 10 Allow from All 11 </Directory> 12 </VirtualHost>

PDF brought to you by generated on February 10, 2014

Chapter 17: How to Set External Parameters in the Service Container | 67

The example above is for an Apache configuration, using the SetEnv1 directive. However, this will work for any web server which supports the setting of environment variables. Also, in order for your console to work (which does not use Apache), you must export these as shell variables. On a Unix system, you can run the following:
Listing 17-2

1 $ export SYMFONY__DATABASE__USER=user 2 $ export SYMFONY__DATABASE__PASSWORD=secret

Now that you have declared an environment variable, it will be present in the PHP $_SERVER global variable. Symfony then automatically sets all $_SERVER variables prefixed with SYMFONY__ as parameters in the service container. You can now reference these parameters wherever you need them.
Listing 17-3

1 doctrine: 2 dbal: 3 driver 4 dbname: 5 user: 6 password:

pdo_mysql symfony2_project "%database.user%" "%database.password%"

Constants
The container also has support for setting PHP constants as parameters. See Constants as Parameters for more details.

Miscellaneous Configuration
The imports directive can be used to pull in parameters stored elsewhere. Importing a PHP file gives you the flexibility to add whatever is needed in the container. The following imports a file named parameters.php.
Listing 17-4

1 # app/config/config.yml 2 imports: 3 - { resource: parameters.php }

A resource file can be one of many types. PHP, XML, YAML, INI, and closure resources are all supported by the imports directive.

In parameters.php, tell the service container the parameters that you wish to set. This is useful when important configuration is in a non-standard format. The example below includes a Drupal database configuration in the Symfony service container.
Listing 17-5

1. http://httpd.apache.org/docs/current/env.html

PDF brought to you by generated on February 10, 2014

Chapter 17: How to Set External Parameters in the Service Container | 68

1 // app/config/parameters.php 2 include_once('/path/to/drupal/sites/default/settings.php'); 3 $container->setParameter('drupal.database.url', $db_url);

PDF brought to you by generated on February 10, 2014

Chapter 17: How to Set External Parameters in the Service Container | 69

Chapter 18

How to use PdoSessionHandler to store Sessions in the Database

The default session storage of Symfony2 writes the session information to file(s). Most medium to large websites use a database to store the session values instead of files, because databases are easier to use and scale in a multi-webserver environment. Symfony2 has a built-in solution for database session storage called PdoSessionHandler1. To use it, you just need to change some parameters in config.yml (or the configuration format of your choice):
Listing 18-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

# app/config/config.yml framework: session: # ... handler_id: session.handler.pdo

parameters: pdo.db_options: db_table: db_id_col: db_data_col: db_time_col:

session session_id session_value session_time

services: pdo: class: PDO arguments: dsn: "mysql:dbname=mydatabase" user: myuser password: mypassword calls: - [setAttribute, [3, 2]] # \PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION session.handler.pdo:

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/Session/Storage/Handler/PdoSessionHandler.html

PDF brought to you by generated on February 10, 2014

Chapter 18: How to use PdoSessionHandler to store Sessions in the Database | 70

25 class: 26 Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler arguments: ["@pdo", "%pdo.db_options%"]

db_table: The name of the session table in your database db_id_col: The name of the id column in your session table (VARCHAR(255) or larger) db_data_col: The name of the value column in your session table (TEXT or CLOB) db_time_col: The name of the time column in your session table (INTEGER)

Sharing your Database Connection Information

With the given configuration, the database connection settings are defined for the session storage connection only. This is OK when you use a separate database for the session data. But if you'd like to store the session data in the same database as the rest of your project's data, you can use the connection settings from the parameters.yml file by referencing the database-related parameters defined there:
Listing 18-2

1 pdo: 2 class: PDO 3 arguments: 4 - "mysql:host=%database_host%;port=%database_port%;dbname=%database_name%" 5 - "%database_user%" 6 - "%database_password%"

Example SQL Statements

MySQL
The SQL statement for creating the needed database table might look like the following (MySQL):
Listing 18-3

1 CREATE TABLE `session` ( 2 `session_id` varchar(255) NOT NULL, 3 `session_value` text NOT NULL, 4 `session_time` int(11) NOT NULL, 5 PRIMARY KEY (`session_id`) 6 ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

PostgreSQL
For PostgreSQL, the statement should look like this:
Listing 18-4

1 CREATE TABLE session ( 2 session_id character varying(255) NOT NULL, 3 session_value text NOT NULL, 4 session_time integer NOT NULL, 5 CONSTRAINT session_pkey PRIMARY KEY (session_id) 6 );

PDF brought to you by generated on February 10, 2014

Chapter 18: How to use PdoSessionHandler to store Sessions in the Database | 71

Microsoft SQL Server

For MSSQL, the statement might look like the following:
Listing 18-5

1 CREATE TABLE [dbo].[session]( 2 [session_id] [nvarchar](255) NOT NULL, 3 [session_value] [ntext] NOT NULL, 4 [session_time] [int] NOT NULL, 5 PRIMARY KEY CLUSTERED( 6 [session_id] ASC 7 ) WITH ( 8 PAD_INDEX = OFF, 9 STATISTICS_NORECOMPUTE = OFF, 10 IGNORE_DUP_KEY = OFF, 11 ALLOW_ROW_LOCKS = ON, 12 ALLOW_PAGE_LOCKS = ON 13 ) ON [PRIMARY] 14 ) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]

PDF brought to you by generated on February 10, 2014

Chapter 18: How to use PdoSessionHandler to store Sessions in the Database | 72

Chapter 19

How to use the Apache Router

Symfony2, while fast out of the box, also provides various ways to increase that speed with a little bit of tweaking. One of these ways is by letting Apache handle routes directly, rather than using Symfony2 for this task.

Change Router Configuration Parameters

To dump Apache routes you must first tweak some configuration parameters to tell Symfony2 to use the ApacheUrlMatcher instead of the default one:
Listing 19-1

1 # app/config/config_prod.yml 2 parameters: 3 router.options.matcher.cache_class: ~ # disable router cache 4 router.options.matcher_class: Symfony\Component\Routing\Matcher\ApacheUrlMatcher

Note that ApacheUrlMatcher1 extends UrlMatcher2 so even if you don't regenerate the mod_rewrite rules, everything will work (because at the end of ApacheUrlMatcher::match() a call to parent::match() is done).

Generating mod_rewrite rules

To test that it's working, create a very basic route for the AcmeDemoBundle:
Listing 19-2

1 # app/config/routing.yml 2 hello: 3 path: /hello/{name} 4 defaults: { _controller: AcmeDemoBundle:Demo:hello }

1. http://api.symfony.com/2.4/Symfony/Component/Routing/Matcher/ApacheUrlMatcher.html 2. http://api.symfony.com/2.4/Symfony/Component/Routing/Matcher/UrlMatcher.html

PDF brought to you by generated on February 10, 2014

Chapter 19: How to use the Apache Router | 73

Now generate the mod_rewrite rules:

Listing 19-3

1 $ php app/console router:dump-apache -e=prod --no-debug

Which should roughly output the following:

Listing 19-4

1 2 3 4 5 6 7

# skip "real" requests RewriteCond %{REQUEST_FILENAME} -f RewriteRule .* - [QSA,L] # hello RewriteCond %{REQUEST_URI} ^/hello/([^/]+?)$ RewriteRule .* app.php [QSA,L,E=_ROUTING__route:hello,E=_ROUTING_name:%1,E=_ROUTING__controller:AcmeDemoBundle\:Demo\:hello]

You can now rewrite web/.htaccess to use the new rules, so with this example it should look like this:
Listing 19-5

1 <IfModule mod_rewrite.c> 2 RewriteEngine On 3 4 # skip "real" requests 5 RewriteCond %{REQUEST_FILENAME} -f 6 RewriteRule .* - [QSA,L] 7 8 # hello 9 RewriteCond %{REQUEST_URI} ^/hello/([^/]+?)$ 10 RewriteRule .* app.php 11 [QSA,L,E=_ROUTING__route:hello,E=_ROUTING_name:%1,E=_ROUTING__controller:AcmeDemoBundle\:Demo\:hello] </IfModule>

The procedure above should be done each time you add/change a route if you want to take full advantage of this setup.

That's it! You're now all set to use Apache routes.

Additional tweaks
To save a little bit of processing time, change occurrences of Request to ApacheRequest in web/app.php:
Listing 19-6

1 2 3 4 5 6 7 8 9 10 11 12

// web/app.php
require_once __DIR__.'/../app/bootstrap.php.cache'; require_once __DIR__.'/../app/AppKernel.php'; // require_once __DIR__.'/../app/AppCache.php'; use Symfony\Component\HttpFoundation\ApacheRequest; $kernel = new AppKernel('prod', false); $kernel->loadClassCache(); // $kernel = new AppCache($kernel); $kernel->handle(ApacheRequest::createFromGlobals())->send();

PDF brought to you by generated on February 10, 2014

Chapter 19: How to use the Apache Router | 74

Chapter 20

Configuring a web server

The web directory is the home of all of your application's public and static files. Including images, stylesheets and JavaScript files. It is also where the front controllers live. For more details, see the The Web Directory. The web directory services as the document root when configuring your web server. In the examples below, this directory is in /var/www/project/web/.

Apache2
For advanced Apache configuration options, see the official Apache1 documentation. The minimum basics to get your application running under Apache2 are:
Listing 20-1

1 <VirtualHost *:80> 2 ServerName domain.tld 3 ServerAlias www.domain.tld 4 5 DocumentRoot /var/www/project/web 6 <Directory /var/www/project/web> 7 # enable the .htaccess rewrites 8 AllowOverride All 9 Order allow,deny 10 Allow from All 11 </Directory> 12 13 ErrorLog /var/log/apache2/project_error.log 14 CustomLog /var/log/apache2/project_access.log combined 15 </VirtualHost>

For performance reasons, you will probably want to set AllowOverride None and implement the rewrite rules in the web/.htaccess into the VirtualHost config.

1. http://httpd.apache.org/docs/current/mod/core.html#documentroot

PDF brought to you by generated on February 10, 2014

Chapter 20: Configuring a web server | 75

If you are using php-cgi, Apache does not pass HTTP basic username and password to PHP by default. To work around this limitation, you should use the following configuration snippet:
Listing 20-2

1 RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

In Apache 2.4, Order allow,deny has been replaced by Require all granted, and hence you need to modify your Directory permission settings as follows:
1 <Directory /var/www/project/web> 2 # enable the .htaccess rewrites 3 AllowOverride All 4 Require all granted 5 </Directory>

Listing 20-3

Nginx
For advanced Nginx configuration options, see the official Nginx2 documentation. The minimum basics to get your application running under Nginx are:
Listing 20-4

1 server { 2 server_name domain.tld www.domain.tld; 3 root /var/www/project/web; 4 5 location / { 6 # try to serve file directly, fallback to rewrite 7 try_files $uri @rewriteapp; 8 } 9 10 location @rewriteapp { 11 # rewrite all to app.php 12 rewrite ^(.*)$ /app.php/$1 last; 13 } 14 15 location ~ ^/(app|app_dev|config)\.php(/|$) { 16 fastcgi_pass unix:/var/run/php5-fpm.sock; 17 fastcgi_split_path_info ^(.+\.php)(/.*)$; 18 include fastcgi_params; 19 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 20 fastcgi_param HTTPS off; 21 } 22 23 error_log /var/log/nginx/project_error.log; 24 access_log /var/log/nginx/project_access.log; 25 }

Depending on your PHP-FPM config, the fastcgi_pass can also be fastcgi_pass 127.0.0.1:9000.

2. http://wiki.nginx.org/Symfony

PDF brought to you by generated on February 10, 2014

Chapter 20: Configuring a web server | 76

This executes only app.php, app_dev.php and config.php in the web directory. All other files will be served as text. You must also make sure that if you do deploy app_dev.php or config.php that these files are secured and not available to any outside user (the IP checking code at the top of each file does this by default). If you have other PHP files in your web directory that need to be executed, be sure to include them in the location block above.

PDF brought to you by generated on February 10, 2014

Chapter 20: Configuring a web server | 77

Chapter 21

How to create a Console Command

The Console page of the Components section (The Console Component) covers how to create a console command. This cookbook article covers the differences when creating console commands within the Symfony2 framework.

Automatically Registering Commands

To make the console commands available automatically with Symfony2, create a Command directory inside your bundle and create a PHP file suffixed with Command.php for each command that you want to provide. For example, if you want to extend the AcmeDemoBundle (available in the Symfony Standard Edition) to greet you from the command line, create GreetCommand.php and add the following to it:
Listing 21-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// src/Acme/DemoBundle/Command/GreetCommand.php namespace Acme\DemoBundle\Command;

use use use use use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand; Symfony\Component\Console\Input\InputArgument; Symfony\Component\Console\Input\InputInterface; Symfony\Component\Console\Input\InputOption; Symfony\Component\Console\Output\OutputInterface;

class GreetCommand extends ContainerAwareCommand { protected function configure() { $this ->setName('demo:greet') ->setDescription('Greet someone') ->addArgument('name', InputArgument::OPTIONAL, 'Who do you want to greet?') ->addOption('yell', null, InputOption::VALUE_NONE, 'If set, the task will yell in uppercase letters') ; } protected function execute(InputInterface $input, OutputInterface $output)

PDF brought to you by generated on February 10, 2014

Chapter 21: How to create a Console Command | 78

24 25 26 27 28 29 30 31 32 33 34 35 36 37 }

{ $name = $input->getArgument('name'); if ($name) { $text = 'Hello '.$name; } else { $text = 'Hello'; } if ($input->getOption('yell')) { $text = strtoupper($text); } $output->writeln($text); }

This command will now automatically be available to run:

Listing 21-2

1 $ app/console demo:greet Fabien

Register Commands in the Service Container

New in version 2.4: Support for registering commands in the service container was added in version 2.4.

Instead of putting your command in the Command directory and having Symfony auto-discover it for you, you can register commands in the service container using the console.command tag:
Listing 21-3

1 # app/config/config.yml 2 services: 3 acme_hello.command.my_command: 4 class: Acme\HelloBundle\Command\MyCommand 5 tags: 6 - { name: console.command }

Registering your command as a service gives you more control over its location and the services that are injected into it. But, there are no functional advantages, so you don't need to register your command as a service.

Getting Services from the Service Container

By using ContainerAwareCommand1 as the base class for the command (instead of the more basic Command2), you have access to the service container. In other words, you have access to any configured service. For example, you could easily extend the task to be translatable:

1. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Command/ContainerAwareCommand.html 2. http://api.symfony.com/2.4/Symfony/Component/Console/Command/Command.html

PDF brought to you by generated on February 10, 2014

Chapter 21: How to create a Console Command | 79

Listing 21-4

1 protected function execute(InputInterface $input, OutputInterface $output) 2 { 3 $name = $input->getArgument('name'); 4 $translator = $this->getContainer()->get('translator'); 5 if ($name) { 6 $output->writeln($translator->trans('Hello %name%!', array('%name%' => $name))); 7 } else { 8 $output->writeln($translator->trans('Hello!')); 9 } 10 }

Testing Commands
When testing commands used as part Symfony\Bundle\FrameworkBundle\Console\Application3 Symfony\Component\Console\Application4:
Listing 21-5

of should

the be

full used

framework instead of

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

use Symfony\Component\Console\Tester\CommandTester; use Symfony\Bundle\FrameworkBundle\Console\Application; use Acme\DemoBundle\Command\GreetCommand; class ListCommandTest extends \PHPUnit_Framework_TestCase { public function testExecute() { // mock the Kernel or create one depending on your needs $application = new Application($kernel); $application->add(new GreetCommand()); $command = $application->find('demo:greet'); $commandTester = new CommandTester($command); $commandTester->execute( array( 'name' => 'Fabien', '--yell' => true, ) ); $this->assertRegExp('/.../', $commandTester->getDisplay());

// ...
} }

New in version 2.4: Since Symfony 2.4, the CommandTester automatically detects the name of the command to execute. Thus, you don't need to pass it via the command key anymore.

3. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Console/Application.html 4. http://api.symfony.com/2.4/Symfony/Component/Console/Application.html

PDF brought to you by generated on February 10, 2014

Chapter 21: How to create a Console Command | 80

In the specific case above, the name parameter and the --yell option are not mandatory for the command to work, but are shown so you can see how to customize them when calling the command.

To be able to use the fully set up service container for your console tests you can extend your test from WebTestCase5:
Listing 21-6

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

use use use use

Symfony\Component\Console\Tester\CommandTester; Symfony\Bundle\FrameworkBundle\Console\Application; Symfony\Bundle\FrameworkBundle\Test\WebTestCase; Acme\DemoBundle\Command\GreetCommand;

class ListCommandTest extends WebTestCase { public function testExecute() { $kernel = $this->createKernel(); $kernel->boot(); $application = new Application($kernel); $application->add(new GreetCommand()); $command = $application->find('demo:greet'); $commandTester = new CommandTester($command); $commandTester->execute( array( 'name' => 'Fabien', '--yell' => true, ) ); $this->assertRegExp('/.../', $commandTester->getDisplay());

// ...
} }

5. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Test/WebTestCase.html

PDF brought to you by generated on February 10, 2014

Chapter 21: How to create a Console Command | 81

Chapter 22

How to use the Console

The Using Console Commands, Shortcuts and Built-in Commands page of the components documentation looks at the global console options. When you use the console as part of the full stack framework, some additional global options are available as well. By default, console commands run in the dev environment and you may want to change this for some commands. For example, you may want to run some commands in the prod environment for performance reasons. Also, the result of some commands will be different depending on the environment. For example, the cache:clear command will clear and warm the cache for the specified environment only. To clear and warm the prod cache you need to run:
Listing 22-1

1 $ php app/console cache:clear --env=prod

or the equivalent:
Listing 22-2

1 $ php app/console cache:clear -e prod

In addition to changing the environment, you can also choose to disable debug mode. This can be useful where you want to run commands in the dev environment but avoid the performance hit of collecting debug data:
Listing 22-3

1 $ php app/console list --no-debug

There is an interactive shell which allows you to enter commands without having to specify php app/ console each time, which is useful if you need to run several commands. To enter the shell run:
Listing 22-4

1 $ php app/console --shell 2 $ php app/console -s

You can now just run commands with the command name:
Listing 22-5

1 Symfony > list

When using the shell you can choose to run each command in a separate process:
PDF brought to you by generated on February 10, 2014 Chapter 22: How to use the Console | 82

Listing 22-6

1 $ php app/console --shell --process-isolation 2 $ php app/console -s --process-isolation

When you do this, the output will not be colorized and interactivity is not supported so you will need to pass all command params explicitly.
Unless you are using isolated processes, clearing the cache in the shell will not have an effect on subsequent commands you run. This is because the original cached files are still being used.

PDF brought to you by generated on February 10, 2014

Chapter 22: How to use the Console | 83

Chapter 23

How to generate URLs and send Emails from the Console

Unfortunately, the command line context does not know about your VirtualHost or domain name. This means that if you generate absolute URLs within a Console Command you'll probably end up with something like http://localhost/foo/bar which is not very useful. To fix this, you need to configure the "request context", which is a fancy way of saying that you need to configure your environment so that it knows what URL it should use when generating URLs. There are two ways of configuring the request context: at the application level and per Command.

Configuring the Request Context globally

To configure the Request Context - which is used by the URL Generator - you can redefine the parameters it uses as default values to change the default host (localhost) and scheme (http). Starting with Symfony 2.2 you can also configure the base path if Symfony is not running in the root directory. Note that this does not impact URLs generated via normal web requests, since those will override the defaults.
Listing 23-1

1 # app/config/parameters.yml 2 parameters: 3 router.request_context.host: example.org 4 router.request_context.scheme: https 5 router.request_context.base_url: my/path

Configuring the Request Context per Command

To change it only in one command you can simply fetch the Request Context from the router service and override its settings:
Listing 23-2

PDF brought to you by generated on February 10, 2014

Chapter 23: How to generate URLs and send Emails from the Console | 84

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

// src/Acme/DemoBundle/Command/DemoCommand.php // ... class DemoCommand extends ContainerAwareCommand { protected function execute(InputInterface $input, OutputInterface $output) { $context = $this->getContainer()->get('router')->getContext(); $context->setHost('example.com'); $context->setScheme('https'); $context->setBaseUrl('my/path'); // ... your code here
} }

Using Memory Spooling

Sending emails in a console command works the same way as described in the How to send an Email cookbook except if memory spooling is used. When using memory spooling (see the How to Spool Emails cookbook for more information), you must be aware that because of how Symfony handles console commands, emails are not sent automatically. You must take care of flushing the queue yourself. Use the following code to send emails inside your console command:
Listing 23-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14

$message = new \Swift_Message();

// ... prepare the message

$container = $this->getContainer(); $mailer = $container->get('mailer'); $mailer->send($message);

// now manually flush the queue $spool = $mailer->getTransport()->getSpool(); $transport = $container->get('swiftmailer.transport.real');

$spool->flushQueue($transport);

Another option is to create an environment which is only used by console commands and uses a different spooling method.
Taking care of the spooling is only needed when memory spooling is used. If you are using file spooling (or no spooling at all), there is no need to flush the queue manually within the command.

PDF brought to you by generated on February 10, 2014

Chapter 23: How to generate URLs and send Emails from the Console | 85

Chapter 24

How to enable logging in Console Commands

The Console component doesn't provide any logging capabilities out of the box. Normally, you run console commands manually and observe the output, which is why logging is not provided. However, there are cases when you might need logging. For example, if you are running console commands unattended, such as from cron jobs or deployment scripts, it may be easier to use Symfony's logging capabilities instead of configuring other tools to gather console output and process it. This can be especially handful if you already have some existing setup for aggregating and analyzing Symfony logs. There are basically two logging cases you would need: Manually logging some information from your command; Logging uncaught Exceptions.

Manually logging from a console Command

This one is really simple. When you create a console command within the full framework as described in "How to create a Console Command", your command extends ContainerAwareCommand1. This means that you can simply access the standard logger service through the container and use it to do the logging:
Listing 24-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// src/Acme/DemoBundle/Command/GreetCommand.php namespace Acme\DemoBundle\Command;

use use use use use use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand; Symfony\Component\Console\Input\InputArgument; Symfony\Component\Console\Input\InputInterface; Symfony\Component\Console\Input\InputOption; Symfony\Component\Console\Output\OutputInterface; Psr\Log\LoggerInterface;

class GreetCommand extends ContainerAwareCommand { // ...

1. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Command/ContainerAwareCommand.html

PDF brought to you by generated on February 10, 2014

Chapter 24: How to enable logging in Console Commands | 86

15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 }

protected function execute(InputInterface $input, OutputInterface $output) { /** @var $logger LoggerInterface */ $logger = $this->getContainer()->get('logger'); $name = $input->getArgument('name'); if ($name) { $text = 'Hello '.$name; } else { $text = 'Hello'; } if ($input->getOption('yell')) { $text = strtoupper($text); $logger->warning('Yelled: '.$text); } else { $logger->info('Greeted: '.$text); } $output->writeln($text); }

Depending on the environment in which you run your command (and your logging setup), you should see the logged entries in app/logs/dev.log or app/logs/prod.log.

Enabling automatic Exceptions logging

To get your console application to automatically log uncaught exceptions for all of your commands, you can use console events.
New in version 2.3: Console events were added in Symfony 2.3.

First configure a listener for console exception events in the service container:
Listing 24-2

1 # app/config/services.yml 2 services: 3 kernel.listener.command_dispatch: 4 class: Acme\DemoBundle\EventListener\ConsoleExceptionListener 5 arguments: 6 logger: "@logger" 7 tags: 8 - { name: kernel.event_listener, event: console.exception }

Then implement the actual listener:

Listing 24-3

1 2 3 4 5 6

// src/Acme/DemoBundle/EventListener/ConsoleExceptionListener.php namespace Acme\DemoBundle\EventListener;

use Symfony\Component\Console\Event\ConsoleExceptionEvent; use Psr\Log\LoggerInterface;

PDF brought to you by generated on February 10, 2014

Chapter 24: How to enable logging in Console Commands | 87

7 class ConsoleExceptionListener 8 { 9 private $logger; 10 11 public function __construct(LoggerInterface $logger) 12 { 13 $this->logger = $logger; 14 } 15 16 public function onConsoleException(ConsoleExceptionEvent $event) 17 { 18 $command = $event->getCommand(); 19 $exception = $event->getException(); 20 21 $message = sprintf( 22 '%s: %s (uncaught exception) at %s line %s while running console command `%s`', 23 get_class($exception), 24 $exception->getMessage(), 25 $exception->getFile(), 26 $exception->getLine(), 27 $command->getName() 28 ); 29 30 $this->logger->error($message); 31 } 32 }

In the code above, when any command throws an exception, the listener will receive an event. You can simply log it by passing the logger service via the service configuration. Your method receives a ConsoleExceptionEvent2 object, which has methods to get information about the event and the exception.

Logging non-0 exit statuses

The logging capabilities of the console can be further extended by logging non-0 exit statuses. This way you will know if a command had any errors, even if no exceptions were thrown. First configure a listener for console terminate events in the service container:
Listing 24-4

1 # app/config/services.yml 2 services: 3 kernel.listener.command_dispatch: 4 class: Acme\DemoBundle\EventListener\ConsoleTerminateListener 5 arguments: 6 logger: "@logger" 7 tags: 8 - { name: kernel.event_listener, event: console.terminate }

Then implement the actual listener:

Listing 24-5

1 // src/Acme/DemoBundle/EventListener/ConsoleExceptionListener.php 2 namespace Acme\DemoBundle\EventListener; 3 4 use Symfony\Component\Console\Event\ConsoleTerminateEvent;

2. http://api.symfony.com/2.4/Symfony/Component/Console/Event/ConsoleExceptionEvent.html

PDF brought to you by generated on February 10, 2014

Chapter 24: How to enable logging in Console Commands | 88

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

use Psr\Log\LoggerInterface; class ConsoleTerminateListener { private $logger; public function __construct(LoggerInterface $logger) { $this->logger = $logger; } public function onConsoleTerminate(ConsoleTerminateEvent $event) { $statusCode = $event->getExitCode(); $command = $event->getCommand(); if ($statusCode === 0) { return; } if ($statusCode > 255) { $statusCode = 255; $event->setExitCode($statusCode); } $this->logger->warning(sprintf( 'Command `%s` exited with status code %d', $command->getName(), $statusCode )); } }

PDF brought to you by generated on February 10, 2014

Chapter 24: How to enable logging in Console Commands | 89

Chapter 25

How to customize Error Pages

When any exception is thrown in Symfony2, the exception is caught inside the Kernel class and eventually forwarded to a special controller, TwigBundle:Exception:show for handling. This controller, which lives inside the core TwigBundle, determines which error template to display and the status code that should be set for the given exception. Error pages can be customized in two different ways, depending on how much control you need: 1. Customize the error templates of the different error pages (explained below); 2. Replace the default exception controller twig.controller.exception:showAction with your own controller and handle it however you want (see exception_controller in the Twig reference). The default exception controller is registered as a service - the actual class is Symfony\Bundle\TwigBundle\Controller\ExceptionController.
The customization of exception handling is actually much more powerful than what's written here. An internal event, kernel.exception, is thrown which allows complete control over exception handling. For more information, see kernel.exception Event.

All of the error templates live inside the TwigBundle. To override the templates, simply rely on the standard method for overriding templates that live inside a bundle. For more information, see Overriding Bundle Templates. For example, to override the default error template that's shown to the end-user, create a new template located at app/Resources/TwigBundle/views/Exception/error.html.twig:
Listing 25-1

1 2 3 4 5 6 7 8 9 10 11

<!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>An Error Occurred: {{ status_text }}</title> </head> <body> <h1>Oops! An Error Occurred</h1> <h2>The server returned a "{{ status_code }} {{ status_text }}".</h2> </body> </html>

PDF brought to you by generated on February 10, 2014

Chapter 25: How to customize Error Pages | 90

You must not use is_granted in your error pages (or layout used by your error pages), because the router runs before the firewall. If the router throws an exception (for instance, when the route does not match), then using is_granted will throw a further exception. You can use is_granted safely by saying {% if app.user and is_granted('...') %}.

If you're not familiar with Twig, don't worry. Twig is a simple, powerful and optional templating engine that integrates with Symfony2. For more information about Twig see Creating and using Templates.

In addition to the standard HTML error page, Symfony provides a default error page for many of the most common response formats, including JSON (error.json.twig), XML (error.xml.twig) and even JavaScript (error.js.twig), to name a few. To override any of these templates, just create a new file with the same name in the app/Resources/TwigBundle/views/Exception directory. This is the standard way of overriding any template that lives inside a bundle.

Customizing the 404 Page and other Error Pages

You can also customize specific error templates according to the HTTP status code. For instance, create a app/Resources/TwigBundle/views/Exception/error404.html.twig template to display a special page for 404 (page not found) errors. Symfony uses the following algorithm to determine which template to use: First, it looks for a template for the given format and status code (like error404.json.twig); If it does not exist, it looks for a template for the given format (like error.json.twig); If it does not exist, it falls back to the HTML template (like error.html.twig).
To see the full list of default error templates, see the Resources/views/Exception directory of the TwigBundle. In a standard Symfony2 installation, the TwigBundle can be found at vendor/ symfony/symfony/src/Symfony/Bundle/TwigBundle. Often, the easiest way to customize an error page is to copy it from the TwigBundle into app/Resources/TwigBundle/views/Exception and then modify it.

The debug-friendly exception pages shown to the developer can even be customized in the same way by creating templates such as exception.html.twig for the standard HTML exception page or exception.json.twig for the JSON exception page.

PDF brought to you by generated on February 10, 2014

Chapter 25: How to customize Error Pages | 91

Chapter 26

How to define Controllers as Services

In the book, you've learned how easily a controller can be used when it extends the base Controller1 class. While this works fine, controllers can also be specified as services.
Specifying a controller as a service takes a little bit more work. The primary advantage is that the entire controller or any services passed to the controller can be modified via the service container configuration. This is especially useful when developing an open-source bundle or any bundle that will be used in many different projects. A second advantage is that your controllers are more "sandboxed". By looking at the constructor arguments, it's easy to see what types of things this controller may or may not do. And because each dependency needs to be injected manually, it's more obvious (i.e. if you have many constructor arguments) when your controller has become too big, and may need to be split into multiple controllers. So, even if you don't specify your controllers as services, you'll likely see this done in some opensource Symfony2 bundles. It's also important to understand the pros and cons of both approaches.

Defining the Controller as a Service

A controller can be defined as a service in the same way as any other class. For example, if you have the following simple controller:
Listing 26-1

1 2 3 4 5 6 7 8 9

// src/Acme/HelloBundle/Controller/HelloController.php namespace Acme\HelloBundle\Controller;

use Symfony\Component\HttpFoundation\Response; class HelloController { public function indexAction($name) {

1. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Controller/Controller.html

PDF brought to you by generated on February 10, 2014

Chapter 26: How to define Controllers as Services | 92

10 11 12 }

return new Response('<html><body>Hello '.$name.'!</body></html>'); }

Then you can define it as a service as follows:

Listing 26-2

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 parameters: 3 # ... 4 acme.controller.hello.class: Acme\HelloBundle\Controller\HelloController 5 6 services: 7 acme.hello.controller: 8 class: "%acme.controller.hello.class%"

Referring to the service

To refer to a controller that's defined as a service, use the single colon (:) notation. For example, to forward to the indexAction() method of the service defined above with the id acme.hello.controller:
Listing 26-3

1 $this->forward('acme.hello.controller:indexAction');

You cannot drop the Action part of the method name when using this syntax.

You can also route to the service by using the same notation when defining the route _controller value:
Listing 26-4

1 # app/config/routing.yml 2 hello: 3 path: /hello 4 defaults: { _controller: acme.hello.controller:indexAction }

You can also use annotations to configure routing using a controller defined as a service. See the FrameworkExtraBundle documentation for details.

Alternatives to Base Controller Methods

When using a controller defined as a service, it will most likely not extend the base Controller class. Instead of relying on its shortcut methods, you'll interact directly with the services that you need. Fortunately, this is usually pretty easy and the base Controller class source code2 is a great source on how to perform many common tasks. For example, if you want to render a template instead of creating the Response object directly, then your code would look like this if you were extending Symfony's base controller:

2. https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php

PDF brought to you by generated on February 10, 2014

Chapter 26: How to define Controllers as Services | 93

Listing 26-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

// src/Acme/HelloBundle/Controller/HelloController.php namespace Acme\HelloBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller; class HelloController extends Controller { public function indexAction($name) { return $this->render( 'AcmeHelloBundle:Hello:index.html.twig', array('name' => $name) ); } }

If you look at the source code for the render function in Symfony's base Controller class3, you'll see that this method actually uses the templating service:
Listing 26-6

1 public function render($view, array $parameters = array(), Response $response = null) 2 { 3 return $this->container->get('templating')->renderResponse($view, $parameters, 4 $response); }

In a controller that's defined as a service, you can instead inject the templating service and use it directly:
Listing 26-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// src/Acme/HelloBundle/Controller/HelloController.php namespace Acme\HelloBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Templating\EngineInterface; use Symfony\Component\HttpFoundation\Response; class HelloController { private $templating; public function __construct(EngineInterface $templating) { $this->templating = $templating; } public function indexAction($name) { return $this->templating->renderResponse( 'AcmeHelloBundle:Hello:index.html.twig', array('name' => $name) ); } }

The service definition also needs modifying to specify the constructor argument:
Listing 26-8

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 parameters:

3. https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php

PDF brought to you by generated on February 10, 2014

Chapter 26: How to define Controllers as Services | 94

3 # ... 4 acme.controller.hello.class: Acme\HelloBundle\Controller\HelloController 5 6 services: 7 acme.hello.controller: 8 class: "%acme.controller.hello.class%" 9 arguments: ["@templating"]

Rather than fetching the templating service from the container, you can inject only the exact service(s) that you need directly into the controller.
This does not mean that you cannot extend these controllers from your own base controller. The move away from the standard base controller is because its helper methods rely on having the container available which is not the case for controllers that are defined as services. It may be a good idea to extract common code into a service that's injected rather than place that code into a base controller that you extend. Both approaches are valid, exactly how you want to organize your reusable code is up to you.

PDF brought to you by generated on February 10, 2014

Chapter 26: How to define Controllers as Services | 95

Chapter 27

How to optimize your development Environment for debugging

When you work on a Symfony project on your local machine, you should use the dev environment (app_dev.php front controller). This environment configuration is optimized for two main purposes: Give the developer accurate feedback whenever something goes wrong (web debug toolbar, nice exception pages, profiler, ...); Be as similar as possible as the production environment to avoid problems when deploying the project.

Disabling the Bootstrap File and Class Caching

And to make the production environment as fast as possible, Symfony creates big PHP files in your cache containing the aggregation of PHP classes your project needs for every request. However, this behavior can confuse your IDE or your debugger. This recipe shows you how you can tweak this caching mechanism to make it friendlier when you need to debug code that involves Symfony classes. The app_dev.php front controller reads as follows by default:
Listing 27-1

1 2 3 4 5 6 7 8

// ...
$loader = require_once __DIR__.'/../app/bootstrap.php.cache'; require_once __DIR__.'/../app/AppKernel.php'; $kernel = new AppKernel('dev', true); $kernel->loadClassCache(); $request = Request::createFromGlobals();

To make your debugger happier, disable all PHP class caches by removing the call to loadClassCache() and by replacing the require statements like below:
Listing 27-2

PDF brought to you by generated on February 10, 2014

Chapter 27: How to optimize your development Environment for debugging | 96

1 2 3 4 5 6 7 8 9 10 11

// ... // $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; $loader = require_once __DIR__.'/../app/autoload.php'; require_once __DIR__.'/../app/AppKernel.php';

use Symfony\Component\HttpFoundation\Request; $kernel = new AppKernel('dev', true); // $kernel->loadClassCache(); $request = Request::createFromGlobals();

If you disable the PHP caches, don't forget to revert after your debugging session.

Some IDEs do not like the fact that some classes are stored in different locations. To avoid problems, you can either tell your IDE to ignore the PHP cache files, or you can change the extension used by Symfony for these files:
Listing 27-3

1 $kernel->loadClassCache('classes', '.php.cache');

PDF brought to you by generated on February 10, 2014

Chapter 27: How to optimize your development Environment for debugging | 97

Chapter 28

How to deploy a Symfony2 application

Deploying can be a complex and varied task depending on your setup and needs. This entry doesn't try to explain everything, but rather offers the most common requirements and ideas for deployment.

Symfony2 Deployment Basics

The typical steps taken while deploying a Symfony2 application include: 1. Upload your modified code to the live server; 2. Update your vendor dependencies (typically done via Composer, and may be done before uploading); 3. Running database migrations or similar tasks to update any changed data structures; 4. Clearing (and perhaps more importantly, warming up) your cache. A deployment may also include other things, such as: Tagging a particular version of your code as a release in your source control repository; Creating a temporary staging area to build your updated setup "offline"; Running any tests available to ensure code and/or server stability; Removal of any unnecessary files from web to keep your production environment clean; Clearing of external cache systems (like Memcached1 or Redis2).

How to deploy a Symfony2 application

There are several ways you can deploy a Symfony2 application. Start with a few basic deployment strategies and build up from there.

1. http://memcached.org/ 2. http://redis.io/

PDF brought to you by generated on February 10, 2014

Chapter 28: How to deploy a Symfony2 application | 98

Basic File Transfer

The most basic way of deploying an application is copying the files manually via ftp/scp (or similar method). This has its disadvantages as you lack control over the system as the upgrade progresses. This method also requires you to take some manual steps after transferring the files (see Common PostDeployment Tasks)

Using Source Control

If you're using source control (e.g. Git or SVN), you can simplify by having your live installation also be a copy of your repository. When you're ready to upgrade it is as simple as fetching the latest updates from your source control system. This makes updating your files easier, but you still need to worry about manually taking other steps (see Common Post-Deployment Tasks).

Using Build scripts and other Tools

There are also high-quality tools to help ease the pain of deployment. There are even a few tools which have been specifically tailored to the requirements of Symfony2, and which take special care to ensure that everything before, during, and after a deployment has gone correctly. See The Tools for a list of tools that can help with deployment.

Common Post-Deployment Tasks

After deploying your actual source code, there are a number of common things you'll need to do:

A) Configure your app/config/parameters.yml file

This file should be customized on each system. The method you use to deploy your source code should not deploy this file. Instead, you should set it up manually (or via some build process) on your server(s).

B) Update your vendors

Your vendors can be updated before transferring your source code (i.e. update the vendor/ directory, then transfer that with your source code) or afterwards on the server. Either way, just update your vendors as you normally do:
Listing 28-1

1 $ php composer.phar install --no-dev --optimize-autoloader

The --optimize-autoloader flag makes Composer's autoloader more performant by building a "class map". The --no-dev flag ensures that development packages are not installed in the production environment.

C) Clear your Symfony cache

Make sure you clear (and warm-up) your Symfony cache:
Listing 28-2

1 $ php app/console cache:clear --env=prod --no-debug

PDF brought to you by generated on February 10, 2014

Chapter 28: How to deploy a Symfony2 application | 99

D) Dump your Assetic assets

If you're using Assetic, you'll also want to dump your assets:
Listing 28-3

1 $ php app/console assetic:dump --env=prod --no-debug

E) Other things!
There may be lots of other things that you need to do, depending on your setup: Running any database migrations Clearing your APC cache Running assets:install (taken care of already in composer.phar install) Add/edit CRON jobs Pushing assets to a CDN ...

Application Lifecycle: Continuous Integration, QA, etc

While this entry covers the technical details of deploying, the full lifecycle of taking code from development up to production may have a lot more steps (think deploying to staging, QA, running tests, etc). The use of staging, testing, QA, continuous integration, database migrations and the capability to roll back in case of failure are all strongly advised. There are simple and more complex tools and one can make the deployment as easy (or sophisticated) as your environment requires. Don't forget that deploying your application also involves updating any dependency (typically via Composer), migrating your database, clearing your cache and other potential things like pushing assets to a CDN (see Common Post-Deployment Tasks).

The Tools
Capifony3: This tool provides a specialized set of tools on top of Capistrano, tailored specifically to symfony and Symfony2 projects. sf2debpkg4: This tool helps you build a native Debian package for your Symfony2 project. Magallanes5: This Capistrano-like deployment tool is built in PHP, and may be easier for PHP developers to extend for their needs. Bundles: There are many bundles that add deployment features6 directly into your Symfony2 console.
3. http://capifony.org/ 4. https://github.com/liip/sf2debpkg 5. https://github.com/andres-montanez/Magallanes

PDF brought to you by generated on February 10, 2014

Chapter 28: How to deploy a Symfony2 application | 100

Basic scripting: You can of course use shell, Ant7, or any other build tool to script the deploying of your project. Platform as a Service Providers: PaaS is a relatively new way to deploy your application. Typically a PaaS will use a single configuration file in your project's root directory to determine how to build an environment on the fly that supports your software. One provider with confirmed Symfony2 support is PagodaBox8.

Looking for more? Talk to the community on the Symfony IRC channel9 #symfony (on freenode) for more information.

6. http://knpbundles.com/search?q=deploy 7. http://blog.sznapka.pl/deploying-symfony2-applications-with-ant 8. https://github.com/jmather/pagoda-symfony-sonata-distribution/blob/master/Boxfile 9. http://webchat.freenode.net/?channels=symfony

PDF brought to you by generated on February 10, 2014

Chapter 28: How to deploy a Symfony2 application | 101

Chapter 29

How to handle File Uploads with Doctrine

Handling file uploads with Doctrine entities is no different than handling any other file upload. In other words, you're free to move the file in your controller after handling a form submission. For examples of how to do this, see the file type reference page. If you choose to, you can also integrate the file upload into your entity lifecycle (i.e. creation, update and removal). In this case, as your entity is created, updated, and removed from Doctrine, the file uploading and removal processing will take place automatically (without needing to do anything in your controller). To make this work, you'll need to take care of a number of details, which will be covered in this cookbook entry.

Basic Setup
First, create a simple Doctrine entity class to work with:
Listing 29-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

// src/Acme/DemoBundle/Entity/Document.php namespace Acme\DemoBundle\Entity;

use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Validator\Constraints as Assert;

/** * @ORM\Entity */ class Document { /** * @ORM\Id * @ORM\Column(type="integer") * @ORM\GeneratedValue(strategy="AUTO") */ public $id; /** * @ORM\Column(type="string", length=255)

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 102

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 }

* @Assert\NotBlank */ public $name; /** * @ORM\Column(type="string", length=255, nullable=true) */ public $path;

public function getAbsolutePath() { return null === $this->path ? null : $this->getUploadRootDir().'/'.$this->path; } public function getWebPath() { return null === $this->path ? null : $this->getUploadDir().'/'.$this->path; } protected function getUploadRootDir() { // the absolute directory path where uploaded // documents should be saved return __DIR__.'/../../../../web/'.$this->getUploadDir(); } protected function getUploadDir() { // get rid of the __DIR__ so it doesn't screw up // when displaying uploaded doc/image in the view. return 'uploads/documents'; }

The Document entity has a name and it is associated with a file. The path property stores the relative path to the file and is persisted to the database. The getAbsolutePath() is a convenience method that returns the absolute path to the file while the getWebPath() is a convenience method that returns the web path, which can be used in a template to link to the uploaded file.
If you have not done so already, you should probably read the file type documentation first to understand how the basic upload process works.

If you're using annotations to specify your validation rules (as shown in this example), be sure that you've enabled validation by annotation (see validation configuration).

To handle the actual file upload in the form, use a "virtual" file field. For example, if you're building your form directly in a controller, it might look like this:
Listing 29-2

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 103

1 public function uploadAction() 2 { 3 // ... 4 5 $form = $this->createFormBuilder($document) 6 ->add('name') 7 ->add('file') 8 ->getForm(); 9 10 // ... 11 }

Next, create this property on your Document class and add some validation rules:
Listing 29-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

use Symfony\Component\HttpFoundation\File\UploadedFile;

// ... class Document { /** * @Assert\File(maxSize="6000000") */ private $file; /** * Sets file. * * @param UploadedFile $file */ public function setFile(UploadedFile $file = null) { $this->file = $file; } /** * Get file. * * @return UploadedFile */ public function getFile() { return $this->file; }
}

Listing 29-4

1 # src/Acme/DemoBundle/Resources/config/validation.yml 2 Acme\DemoBundle\Entity\Document: 3 properties: 4 file: 5 - File: 6 maxSize: 6000000

As you are using the File constraint, Symfony2 will automatically guess that the form field is a file upload input. That's why you did not have to set it explicitly when creating the form above (->add('file')).

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 104

The following controller shows you how to handle the entire process:
Listing 29-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

// ... use Acme\DemoBundle\Entity\Document; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template; use Symfony\Component\HttpFoundation\Request; // ... /** * @Template() */ public function uploadAction(Request $request) { $document = new Document(); $form = $this->createFormBuilder($document) ->add('name') ->add('file') ->getForm();
$form->handleRequest($request); if ($form->isValid()) { $em = $this->getDoctrine()->getManager(); $em->persist($document); $em->flush(); return $this->redirect($this->generateUrl(...)); } return array('form' => $form->createView()); }

The previous controller will automatically persist the Document entity with the submitted name, but it will do nothing about the file and the path property will be blank. An easy way to handle the file upload is to move it just before the entity is persisted and then set the path property accordingly. Start by calling a new upload() method on the Document class, which you'll create in a moment to handle the file upload:
Listing 29-6

1 if ($form->isValid()) { 2 $em = $this->getDoctrine()->getManager(); 3 4 $document->upload(); 5 6 $em->persist($document); 7 $em->flush(); 8 9 return $this->redirect(...); 10 }

The upload() method will take advantage of the UploadedFile1 object, which is what's returned after a file field is submitted:
Listing 29-7

1 public function upload() 2 {

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/File/UploadedFile.html

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 105

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 }

// the file property can be empty if the field is not required if (null === $this->getFile()) { return; } // use the original file name here but you should // sanitize it at least to avoid any security issues // move takes the target directory and then the // target filename to move to $this->getFile()->move( $this->getUploadRootDir(), $this->getFile()->getClientOriginalName() ); // set the path property to the filename where you've saved the file $this->path = $this->getFile()->getClientOriginalName(); // clean up the file property as you won't need it anymore $this->file = null;

Using Lifecycle Callbacks

Using lifecycle callbacks is a limited technique that has some drawbacks. If you want to remove the hardcoded __DIR__ reference inside the Document::getUploadRootDir() method, the best way is to start using explicit doctrine listeners. There you will be able to inject kernel parameters such as kernel.root_dir to be able to build absolute paths.

Even if this implementation works, it suffers from a major flaw: What if there is a problem when the entity is persisted? The file would have already moved to its final location even though the entity's path property didn't persist correctly. To avoid these issues, you should change the implementation so that the database operation and the moving of the file become atomic: if there is a problem persisting the entity or if the file cannot be moved, then nothing should happen. To do this, you need to move the file right as Doctrine persists the entity to the database. This can be accomplished by hooking into an entity lifecycle callback:
Listing 29-8

1 2 3 4 5 6 7

/** * @ORM\Entity * @ORM\HasLifecycleCallbacks */ class Document { }

Next, refactor the Document class to take advantage of these callbacks:

Listing 29-9

1 use Symfony\Component\HttpFoundation\File\UploadedFile; 2 3 /**

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 106

4 * @ORM\Entity 5 * @ORM\HasLifecycleCallbacks 6 */ 7 class Document 8 { 9 private $temp; 10 11 /** 12 * Sets file. 13 * 14 * @param UploadedFile $file 15 */ 16 public function setFile(UploadedFile $file = null) 17 { 18 $this->file = $file; 19 // check if we have an old image path 20 if (isset($this->path)) { 21 // store the old name to delete after the update 22 $this->temp = $this->path; 23 $this->path = null; 24 } else { 25 $this->path = 'initial'; 26 } 27 } 28 29 /** 30 * @ORM\PrePersist() 31 * @ORM\PreUpdate() 32 */ 33 public function preUpload() 34 { 35 if (null !== $this->getFile()) { 36 // do whatever you want to generate a unique name 37 $filename = sha1(uniqid(mt_rand(), true)); 38 $this->path = $filename.'.'.$this->getFile()->guessExtension(); 39 } 40 } 41 42 /** 43 * @ORM\PostPersist() 44 * @ORM\PostUpdate() 45 */ 46 public function upload() 47 { 48 if (null === $this->getFile()) { 49 return; 50 } 51 52 // if there is an error when moving the file, an exception will 53 // be automatically thrown by move(). This will properly prevent 54 // the entity from being persisted to the database on error 55 $this->getFile()->move($this->getUploadRootDir(), $this->path); 56 57 // check if we have an old image 58 if (isset($this->temp)) { 59 // delete the old image 60 unlink($this->getUploadRootDir().'/'.$this->temp); 61 // clear the temp image path 62 $this->temp = null;

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 107

63 64 65 66 67 68 69 70 71 72 73 74 75 76 }

} $this->file = null; }

/** * @ORM\PostRemove() */ public function removeUpload() { if ($file = $this->getAbsolutePath()) { unlink($file); } }

The class now does everything you need: it generates a unique filename before persisting, moves the file after persisting, and removes the file if the entity is ever deleted. Now that the moving of the file is handled atomically by the entity, the call to $document->upload() should be removed from the controller:
Listing 29-10

1 if ($form->isValid()) { 2 $em = $this->getDoctrine()->getManager(); 3 4 $em->persist($document); 5 $em->flush(); 6 7 return $this->redirect(...); 8 }

The @ORM\PrePersist() and @ORM\PostPersist() event callbacks are triggered before and after the entity is persisted to the database. On the other hand, the @ORM\PreUpdate() and @ORM\PostUpdate() event callbacks are called when the entity is updated.

The PreUpdate and PostUpdate callbacks are only triggered if there is a change in one of the entity's fields that are persisted. This means that, by default, if you modify only the $file property, these events will not be triggered, as the property itself is not directly persisted via Doctrine. One solution would be to use an updated field that's persisted to Doctrine, and to modify it manually when changing the file.

Using the id as the filename

If you want to use the id as the name of the file, the implementation is slightly different as you need to save the extension under the path property, instead of the actual filename:
Listing 29-11

1 use Symfony\Component\HttpFoundation\File\UploadedFile; 2 3 /** 4 * @ORM\Entity 5 * @ORM\HasLifecycleCallbacks 6 */

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 108

7 class Document 8 { 9 private $temp; 10 11 /** 12 * Sets file. 13 * 14 * @param UploadedFile $file 15 */ 16 public function setFile(UploadedFile $file = null) 17 { 18 $this->file = $file; 19 // check if we have an old image path 20 if (is_file($this->getAbsolutePath())) { 21 // store the old name to delete after the update 22 $this->temp = $this->getAbsolutePath(); 23 } else { 24 $this->path = 'initial'; 25 } 26 } 27 28 /** 29 * @ORM\PrePersist() 30 * @ORM\PreUpdate() 31 */ 32 public function preUpload() 33 { 34 if (null !== $this->getFile()) { 35 $this->path = $this->getFile()->guessExtension(); 36 } 37 } 38 39 /** 40 * @ORM\PostPersist() 41 * @ORM\PostUpdate() 42 */ 43 public function upload() 44 { 45 if (null === $this->getFile()) { 46 return; 47 } 48 49 // check if we have an old image 50 if (isset($this->temp)) { 51 // delete the old image 52 unlink($this->temp); 53 // clear the temp image path 54 $this->temp = null; 55 } 56 57 // you must throw an exception here if the file cannot be moved 58 // so that the entity is not persisted to the database 59 // which the UploadedFile move() method does 60 $this->getFile()->move( 61 $this->getUploadRootDir(), 62 $this->id.'.'.$this->getFile()->guessExtension() 63 ); 64 65 $this->setFile(null);

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 109

66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 }

/** * @ORM\PreRemove() */ public function storeFilenameForRemove() { $this->temp = $this->getAbsolutePath(); } /** * @ORM\PostRemove() */ public function removeUpload() { if (isset($this->temp)) { unlink($this->temp); } }
public function getAbsolutePath() { return null === $this->path ? null : $this->getUploadRootDir().'/'.$this->id.'.'.$this->path; }

You'll notice in this case that you need to do a little bit more work in order to remove the file. Before it's removed, you must store the file path (since it depends on the id). Then, once the object has been fully removed from the database, you can safely delete the file (in PostRemove).

PDF brought to you by generated on February 10, 2014

Chapter 29: How to handle File Uploads with Doctrine | 110

Chapter 30

How to use Doctrine Extensions: Timestampable, Sluggable, Translatable, etc.

Doctrine2 is very flexible, and the community has already created a series of useful Doctrine extensions to help you with common entity-related tasks. One library in particular - the DoctrineExtensions1 library - provides integration functionality for Sluggable2, Translatable3, Timestampable4, Loggable5, Tree6 and Sortable7 behaviors. The usage for each of these extensions is explained in that repository. However, to install/activate each extension you must register and activate an Event Listener. To do this, you have two options: 1. Use the StofDoctrineExtensionsBundle8, which integrates the above library. 2. Implement this services directly by following the documentation for integration with Symfony2: Install Gedmo Doctrine2 extensions in Symfony29

1. https://github.com/l3pp4rd/DoctrineExtensions 2. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/sluggable.md 3. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/translatable.md 4. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/timestampable.md 5. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/loggable.md 6. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/tree.md 7. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/sortable.md 8. https://github.com/stof/StofDoctrineExtensionsBundle 9. https://github.com/l3pp4rd/DoctrineExtensions/blob/master/doc/symfony2.md

PDF brought to you by generated on February 10, 2014

Chapter 30: How to use Doctrine Extensions: Timestampable, Sluggable, Translatable, etc. | 111

Chapter 31

How to Register Event Listeners and Subscribers

Doctrine packages a rich event system that fires events when almost anything happens inside the system. For you, this means that you can create arbitrary services and tell Doctrine to notify those objects whenever a certain action (e.g. prePersist) happens within Doctrine. This could be useful, for example, to create an independent search index whenever an object in your database is saved. Doctrine defines two types of objects that can listen to Doctrine events: listeners and subscribers. Both are very similar, but listeners are a bit more straightforward. For more, see The Event System1 on Doctrine's website. The Doctrine website also explains all existing events that can be listened to.

Configuring the Listener/Subscriber

To register a service to act as an event listener or subscriber you just have to tag it with the appropriate name. Depending on your use-case, you can hook a listener into every DBAL connection and ORM entity manager or just into one specific DBAL connection and all the entity managers that use this connection.
Listing 31-1

1 doctrine: 2 dbal: 3 default_connection: default 4 connections: 5 default: 6 driver: pdo_sqlite 7 memory: true 8 9 services: 10 my.listener: 11 class: Acme\SearchBundle\EventListener\SearchIndexer 12 tags:

1. http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html

PDF brought to you by generated on February 10, 2014

Chapter 31: How to Register Event Listeners and Subscribers | 112

13 14 15 16 17 18 19 20 21

- { name: doctrine.event_listener, event: postPersist } my.listener2: class: Acme\SearchBundle\EventListener\SearchIndexer2 tags: - { name: doctrine.event_listener, event: postPersist, connection: default } my.subscriber: class: Acme\SearchBundle\EventListener\SearchIndexerSubscriber tags: - { name: doctrine.event_subscriber, connection: default }

Creating the Listener Class

In the previous example, a service my.listener was configured as a Doctrine listener on the event postPersist. The class behind that service must have a postPersist method, which will be called when the event is dispatched:
Listing 31-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

// src/Acme/SearchBundle/EventListener/SearchIndexer.php namespace Acme\SearchBundle\EventListener;

use Doctrine\ORM\Event\LifecycleEventArgs; use Acme\StoreBundle\Entity\Product; class SearchIndexer { public function postPersist(LifecycleEventArgs $args) { $entity = $args->getEntity(); $entityManager = $args->getEntityManager();

// perhaps you only want to act on some "Product" entity if ($entity instanceof Product) { // ... do something with the Product }
} }

In each event, you have access to a LifecycleEventArgs object, which gives you access to both the entity object of the event and the entity manager itself. One important thing to notice is that a listener will be listening for all entities in your application. So, if you're interested in only handling a specific type of entity (e.g. a Product entity but not a BlogPost entity), you should check for the entity's class type in your method (as shown above).

Creating the Subscriber Class

A Doctrine event subscriber must implement the Doctrine\Common\EventSubscriber interface and have an event method for each event it subscribes to:
Listing 31-3

1 2 3 4 5

// src/Acme/SearchBundle/EventListener/SearchIndexerSubscriber.php namespace Acme\SearchBundle\EventListener;

use Doctrine\Common\EventSubscriber; use Doctrine\ORM\Event\LifecycleEventArgs;

PDF brought to you by generated on February 10, 2014

Chapter 31: How to Register Event Listeners and Subscribers | 113

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

// for Doctrine 2.4: Doctrine\Common\Persistence\Event\LifecycleEventArgs; use Acme\StoreBundle\Entity\Product;

class SearchIndexerSubscriber implements EventSubscriber { public function getSubscribedEvents() { return array( 'postPersist', 'postUpdate', ); } public function postUpdate(LifecycleEventArgs $args) { $this->index($args); } public function postPersist(LifecycleEventArgs $args) { $this->index($args); } public function index(LifecycleEventArgs $args) { $entity = $args->getEntity(); $entityManager = $args->getEntityManager();

// perhaps you only want to act on some "Product" entity if ($entity instanceof Product) { // ... do something with the Product }
} }

Doctrine event subscribers can not return a flexible array of methods to call for the events like the Symfony event subscriber can. Doctrine event subscribers must return a simple array of the event names they subscribe to. Doctrine will then expect methods on the subscriber with the same name as each subscribed event, just as when using an event listener.

For a full reference, see chapter The Event System2 in the Doctrine documentation.

2. http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html

PDF brought to you by generated on February 10, 2014

Chapter 31: How to Register Event Listeners and Subscribers | 114

Chapter 32

How to use Doctrine's DBAL Layer

This article is about Doctrine DBAL's layer. Typically, you'll work with the higher level Doctrine ORM layer, which simply uses the DBAL behind the scenes to actually communicate with the database. To read more about the Doctrine ORM, see "Databases and Doctrine".

The Doctrine1 Database Abstraction Layer (DBAL) is an abstraction layer that sits on top of PDO2 and offers an intuitive and flexible API for communicating with the most popular relational databases. In other words, the DBAL library makes it easy to execute queries and perform other database actions.
Read the official Doctrine DBAL Documentation3 to learn all the details and capabilities of Doctrine's DBAL library.

To get started, configure the database connection parameters:

Listing 32-1

1 # app/config/config.yml 2 doctrine: 3 dbal: 4 driver: pdo_mysql 5 dbname: Symfony2 6 user: root 7 password: null 8 charset: UTF8

For full DBAL configuration options, see Doctrine DBAL Configuration. You can then access the Doctrine DBAL connection by accessing the database_connection service:
Listing 32-2

1. http://www.doctrine-project.org 2. http://www.php.net/pdo 3. http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/index.html

PDF brought to you by generated on February 10, 2014

Chapter 32: How to use Doctrine's DBAL Layer | 115

1 class UserController extends Controller 2 { 3 public function indexAction() 4 { 5 $conn = $this->get('database_connection'); 6 $users = $conn->fetchAll('SELECT * FROM users'); 7 8 // ... 9 } 10 }

Registering Custom Mapping Types

You can register custom mapping types through Symfony's configuration. They will be added to all configured connections. For more information on custom mapping types, read Doctrine's Custom Mapping Types4 section of their documentation.
Listing 32-3

1 # app/config/config.yml 2 doctrine: 3 dbal: 4 types: 5 custom_first: Acme\HelloBundle\Type\CustomFirst 6 custom_second: Acme\HelloBundle\Type\CustomSecond

Registering Custom Mapping Types in the SchemaTool

The SchemaTool is used to inspect the database to compare the schema. To achieve this task, it needs to know which mapping type needs to be used for each database types. Registering new ones can be done through the configuration. Now, map the ENUM type (not supported by DBAL by default) to the string mapping type:
Listing 32-4

1 # app/config/config.yml 2 doctrine: 3 dbal: 4 connections: 5 default: 6 # other connections parameters 7 mapping_types: 8 enum: string

4. http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html#custom-mapping-types

PDF brought to you by generated on February 10, 2014

Chapter 32: How to use Doctrine's DBAL Layer | 116

Chapter 33

How to generate Entities from an Existing Database

When starting work on a brand new project that uses a database, two different situations comes naturally. In most cases, the database model is designed and built from scratch. Sometimes, however, you'll start with an existing and probably unchangeable database model. Fortunately, Doctrine comes with a bunch of tools to help generate model classes from your existing database.
As the Doctrine tools documentation1 says, reverse engineering is a one-time process to get started on a project. Doctrine is able to convert approximately 70-80% of the necessary mapping information based on fields, indexes and foreign key constraints. Doctrine can't discover inverse associations, inheritance types, entities with foreign keys as primary keys or semantical operations on associations such as cascade or lifecycle events. Some additional work on the generated entities will be necessary afterwards to design each to fit your domain model specificities.

This tutorial assumes you're using a simple blog application with the following two tables: blog_post and blog_comment. A comment record is linked to a post record thanks to a foreign key constraint.
Listing 33-1

1 CREATE TABLE `blog_post` ( 2 `id` bigint(20) NOT NULL AUTO_INCREMENT, 3 `title` varchar(100) COLLATE utf8_unicode_ci NOT NULL, 4 `content` longtext COLLATE utf8_unicode_ci NOT NULL, 5 `created_at` datetime NOT NULL, 6 PRIMARY KEY (`id`) 7 ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci; 8 9 CREATE TABLE `blog_comment` ( 10 `id` bigint(20) NOT NULL AUTO_INCREMENT, 11 `post_id` bigint(20) NOT NULL, 12 `author` varchar(20) COLLATE utf8_unicode_ci NOT NULL, 13 `content` longtext COLLATE utf8_unicode_ci NOT NULL, 14 `created_at` datetime NOT NULL,

1. http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/tools.html#reverse-engineering

PDF brought to you by generated on February 10, 2014

Chapter 33: How to generate Entities from an Existing Database | 117

15 PRIMARY KEY (`id`), 16 KEY `blog_comment_post_id_idx` (`post_id`), 17 CONSTRAINT `blog_post_id` FOREIGN KEY (`post_id`) REFERENCES `blog_post` (`id`) ON 18 DELETE CASCADE ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

Before diving into the recipe, be sure your database connection parameters are correctly setup in the app/config/parameters.yml file (or wherever your database configuration is kept) and that you have initialized a bundle that will host your future entity class. In this tutorial it's assumed that an AcmeBlogBundle exists and is located under the src/Acme/BlogBundle folder. The first step towards building entity classes from an existing database is to ask Doctrine to introspect the database and generate the corresponding metadata files. Metadata files describe the entity class to generate based on table fields.
Listing 33-2

1 $ php app/console doctrine:mapping:import --force AcmeBlogBundle xml

This command line tool asks Doctrine to introspect the database and generate the XML metadata files under the src/Acme/BlogBundle/Resources/config/doctrine folder of your bundle. This generates two files: BlogPost.orm.xml and BlogComment.orm.xml.
It's also possible to generate the metadata files in YAML format by changing the last argument to yml.

The generated BlogPost.orm.xml metadata file looks as follows:

Listing 33-3

1 2 3 4 5 6 7 8 9 10 11

<?xml version="1.0" encoding="utf-8"?> <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd"> <entity name="Acme\BlogBundle\Entity\BlogPost" table="blog_post"> <id name="id" type="bigint" column="id"> <generator strategy="IDENTITY"/> </id> <field name="title" type="string" column="title" length="100" nullable="false"/> <field name="content" type="text" column="content" nullable="false"/> <field name="createdAt" type="datetime" column="created_at" nullable="false"/> </entity> </doctrine-mapping>

Once the metadata files are generated, you can ask Doctrine to build related entity classes by executing the following two commands.
Listing 33-4

1 $ php app/console doctrine:mapping:convert annotation ./src 2 $ php app/console doctrine:generate:entities AcmeBlogBundle

The first command generates entity classes with annotation mappings. But if you want to use YAML or XML mapping instead of annotations, you should execute the second command only.
If you want to use annotations, you can safely delete the XML (or YAML) files after running these two commands.

PDF brought to you by generated on February 10, 2014

Chapter 33: How to generate Entities from an Existing Database | 118

For example, the newly created BlogComment entity class looks as follow:
Listing 33-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

// src/Acme/BlogBundle/Entity/BlogComment.php namespace Acme\BlogBundle\Entity;

use Doctrine\ORM\Mapping as ORM;

/** * Acme\BlogBundle\Entity\BlogComment * * @ORM\Table(name="blog_comment") * @ORM\Entity */ class BlogComment { /** * @var integer $id * * @ORM\Column(name="id", type="bigint") * @ORM\Id * @ORM\GeneratedValue(strategy="IDENTITY") */ private $id; /** * @var string $author * * @ORM\Column(name="author", type="string", length=100, nullable=false) */ private $author; /** * @var text $content * * @ORM\Column(name="content", type="text", nullable=false) */ private $content; /** * @var datetime $createdAt * * @ORM\Column(name="created_at", type="datetime", nullable=false) */ private $createdAt; /** * @var BlogPost * * @ORM\ManyToOne(targetEntity="BlogPost") * @ORM\JoinColumn(name="post_id", referencedColumnName="id") */ private $post;
}

As you can see, Doctrine converts all table fields to pure private and annotated class properties. The most impressive thing is that it also discovered the relationship with the BlogPost entity class based on the foreign key constraint. Consequently, you can find a private $post property mapped with a BlogPost entity in the BlogComment entity class.

PDF brought to you by generated on February 10, 2014

Chapter 33: How to generate Entities from an Existing Database | 119

If you want to have a one-to-many relationship, you will need to add it manually into the entity or to the generated XML or YAML files. Add a section on the specific entities for one-to-many defining the inversedBy and the mappedBy pieces.

The generated entities are now ready to be used. Have fun!

PDF brought to you by generated on February 10, 2014

Chapter 33: How to generate Entities from an Existing Database | 120

Chapter 34

How to work with Multiple Entity Managers and Connections

You can use multiple Doctrine entity managers or connections in a Symfony2 application. This is necessary if you are using different databases or even vendors with entirely different sets of entities. In other words, one entity manager that connects to one database will handle some entities while another entity manager that connects to another database might handle the rest.
Using multiple entity managers is pretty easy, but more advanced and not usually required. Be sure you actually need multiple entity managers before adding in this layer of complexity.

The following configuration code shows how you can configure two entity managers:
Listing 34-1

1 doctrine: 2 dbal: 3 default_connection: default 4 connections: 5 default: 6 driver: "%database_driver%" 7 host: "%database_host%" 8 port: "%database_port%" 9 dbname: "%database_name%" 10 user: "%database_user%" 11 password: "%database_password%" 12 charset: UTF8 13 customer: 14 driver: "%database_driver2%" 15 host: "%database_host2%" 16 port: "%database_port2%" 17 dbname: "%database_name2%" 18 user: "%database_user2%" 19 password: "%database_password2%" 20 charset: UTF8

PDF brought to you by generated on February 10, 2014

Chapter 34: How to work with Multiple Entity Managers and Connections | 121

21 22 23 24 25 26 27 28 29 30 31 32 33

orm: default_entity_manager: default entity_managers: default: connection: default mappings: AcmeDemoBundle: ~ AcmeStoreBundle: ~ customer: connection: customer mappings: AcmeCustomerBundle: ~

In this case, you've defined two entity managers and called them default and customer. The default entity manager manages entities in the AcmeDemoBundle and AcmeStoreBundle, while the customer entity manager manages entities in the AcmeCustomerBundle. You've also defined two connections, one for each entity manager.
When working with multiple connections and entity managers, you should be explicit about which configuration you want. If you do omit the name of the connection or entity manager, the default (i.e. default) is used.

When working with multiple connections to create your databases:

Listing 34-2

1 2 3 4 5

# Play only with "default" connection $ php app/console doctrine:database:create # Play only with "customer" connection $ php app/console doctrine:database:create --connection=customer

When working with multiple entity managers to update your schema:

Listing 34-3

1 2 3 4 5

# Play only with "default" mappings $ php app/console doctrine:schema:update --force # Play only with "customer" mappings $ php app/console doctrine:schema:update --force --em=customer

If you do omit the entity manager's name when asking for it, the default entity manager (i.e. default) is returned:
Listing 34-4

1 class UserController extends Controller 2 { 3 public function indexAction() 4 { 5 // both return the "default" em 6 $em = $this->get('doctrine')->getManager(); 7 $em = $this->get('doctrine')->getManager('default'); 8 9 $customerEm = $this->get('doctrine')->getManager('customer'); 10 } 11 }

PDF brought to you by generated on February 10, 2014

Chapter 34: How to work with Multiple Entity Managers and Connections | 122

You can now use Doctrine just as you did before - using the default entity manager to persist and fetch entities that it manages and the customer entity manager to persist and fetch its entities. The same applies to repository calls:
Listing 34-5

1 class UserController extends Controller 2 { 3 public function indexAction() 4 { 5 // Retrieves a repository managed by the "default" em 6 $products = $this->get('doctrine') 7 ->getRepository('AcmeStoreBundle:Product') 8 ->findAll() 9 ; 10 11 // Explicit way to deal with the "default" em 12 $products = $this->get('doctrine') 13 ->getRepository('AcmeStoreBundle:Product', 'default') 14 ->findAll() 15 ; 16 17 // Retrieves a repository managed by the "customer" em 18 $customers = $this->get('doctrine') 19 ->getRepository('AcmeCustomerBundle:Customer', 'customer') 20 ->findAll() 21 ; 22 } 23 }

PDF brought to you by generated on February 10, 2014

Chapter 34: How to work with Multiple Entity Managers and Connections | 123

Chapter 35

How to Register Custom DQL Functions

Doctrine allows you to specify custom DQL functions. For more information on this topic, read Doctrine's cookbook article "DQL User Defined Functions1". In Symfony, you can register your custom DQL functions as follows:
Listing 35-1

1 # app/config/config.yml 2 doctrine: 3 orm: 4 # ... 5 dql: 6 string_functions: 7 test_string: Acme\HelloBundle\DQL\StringFunction 8 second_string: Acme\HelloBundle\DQL\SecondStringFunction 9 numeric_functions: 10 test_numeric: Acme\HelloBundle\DQL\NumericFunction 11 datetime_functions: 12 test_datetime: Acme\HelloBundle\DQL\DatetimeFunction

1. http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/dql-user-defined-functions.html

PDF brought to you by generated on February 10, 2014

Chapter 35: How to Register Custom DQL Functions | 124

Chapter 36

How to Define Relationships with Abstract Classes and Interfaces

One of the goals of bundles is to create discreet bundles of functionality that do not have many (if any) dependencies, allowing you to use that functionality in other applications without including unnecessary items. Doctrine 2.2 includes a new utility called the ResolveTargetEntityListener, that functions by intercepting certain calls inside Doctrine and rewriting targetEntity parameters in your metadata mapping at runtime. It means that in your bundle you are able to use an interface or abstract class in your mappings and expect correct mapping to a concrete entity at runtime. This functionality allows you to define relationships between different entities without making them hard dependencies.

Background
Suppose you have an InvoiceBundle which provides invoicing functionality and a CustomerBundle that contains customer management tools. You want to keep these separated, because they can be used in other systems without each other, but for your application you want to use them together. In this case, you have an Invoice entity with a relationship to a non-existent object, an InvoiceSubjectInterface. The goal is to get the ResolveTargetEntityListener to replace any mention of the interface with a real object that implements that interface.

Set up
This article uses the following two basic entities (which are incomplete for brevity) to explain how to set up and use the ResolveTargetEntityListener. A Customer entity:
Listing 36-1

PDF brought to you by generated on February 10, 2014

Chapter 36: How to Define Relationships with Abstract Classes and Interfaces | 125

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/AppBundle/Entity/Customer.php
namespace Acme\AppBundle\Entity; use Doctrine\ORM\Mapping as ORM; use Acme\CustomerBundle\Entity\Customer as BaseCustomer; use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;

/** * @ORM\Entity * @ORM\Table(name="customer") */ class Customer extends BaseCustomer implements InvoiceSubjectInterface { // In this example, any methods defined in the InvoiceSubjectInterface // are already implemented in the BaseCustomer }

An Invoice entity:
Listing 36-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// src/Acme/InvoiceBundle/Entity/Invoice.php
namespace Acme\InvoiceBundle\Entity; use Doctrine\ORM\Mapping AS ORM; use Acme\InvoiceBundle\Model\InvoiceSubjectInterface;

/** * Represents an Invoice. * * @ORM\Entity * @ORM\Table(name="invoice") */ class Invoice { /** * @ORM\ManyToOne(targetEntity="Acme\InvoiceBundle\Model\InvoiceSubjectInterface") * @var InvoiceSubjectInterface */ protected $subject; }

An InvoiceSubjectInterface:
Listing 36-3

1 2 3 4 5 6 7 8 9 10 11 12 13

// src/Acme/InvoiceBundle/Model/InvoiceSubjectInterface.php
namespace Acme\InvoiceBundle\Model;

/** * An interface that the invoice Subject object should implement. * In most circumstances, only a single object should implement * this interface as the ResolveTargetEntityListener can only * change the target to a single object. */ interface InvoiceSubjectInterface { // List any additional methods that your InvoiceBundle

PDF brought to you by generated on February 10, 2014

Chapter 36: How to Define Relationships with Abstract Classes and Interfaces | 126

14 15 16 17 18 19 20 21 }

// will need to access on the subject so that you can // be sure that you have access to those methods. /** * @return string */ public function getName();

Next, you need to configure the listener, which tells the DoctrineBundle about the replacement:
Listing 36-4

1 # app/config/config.yml 2 doctrine: 3 # ... 4 orm: 5 # ... 6 resolve_target_entities: 7 Acme\InvoiceBundle\Model\InvoiceSubjectInterface: Acme\AppBundle\Entity\Customer

Final Thoughts
With the ResolveTargetEntityListener, you are able to decouple your bundles, keeping them usable by themselves, but still being able to define relationships between different objects. By using this method, your bundles will end up being easier to maintain independently.

PDF brought to you by generated on February 10, 2014

Chapter 36: How to Define Relationships with Abstract Classes and Interfaces | 127

Chapter 37

How to provide model classes for several Doctrine implementations

When building a bundle that could be used not only with Doctrine ORM but also the CouchDB ODM, MongoDB ODM or PHPCR ODM, you should still only write one model class. The Doctrine bundles provide a compiler pass to register the mappings for your model classes.
For non-reusable bundles, the easiest option is to put your model classes in the default locations: Entity for the Doctrine ORM or Document for one of the ODMs. For reusable bundles, rather than duplicate model classes just to get the auto mapping, use the compiler pass.

New in version 2.3: The base mapping compiler pass was added in Symfony 2.3. The Doctrine bundles support it from DoctrineBundle >= 1.2.1, MongoDBBundle >= 3.0.0, PHPCRBundle >= 1.0.0-alpha2 and the (unversioned) CouchDBBundle supports the compiler pass since the CouchDB Mapping Compiler Pass pull request1 was merged.

If you want your bundle to support older versions of Symfony and Doctrine, you can provide a copy of the compiler pass in your bundle. See for example the FOSUserBundle mapping configuration2 addRegisterMappingsPass. In your bundle class, write the following code to register the compiler pass. This one is written for the FOSUserBundle, so parts of it will need to be adapted for your case:
Listing 37-1

1 2 3 4 5 6 7

use use use use

Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass; Doctrine\Bundle\MongoDBBundle\DependencyInjection\Compiler\DoctrineMongoDBMappingsPass; Doctrine\Bundle\CouchDBBundle\DependencyInjection\Compiler\DoctrineCouchDBMappingsPass; Doctrine\Bundle\PHPCRBundle\DependencyInjection\Compiler\DoctrinePhpcrMappingsPass;

class FOSUserBundle extends Bundle {

1. https://github.com/doctrine/DoctrineCouchDBBundle/pull/27 2. https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/FOSUserBundle.php

PDF brought to you by generated on February 10, 2014

Chapter 37: How to provide model classes for several Doctrine implementations | 128

8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58

public function build(ContainerBuilder $container) { parent::build($container); // ... $modelDir = realpath(__DIR__.'/Resources/config/doctrine/model'); $mappings = array( $modelDir => 'FOS\UserBundle\Model', ); $ormCompilerClass = 'Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass'; if (class_exists($ormCompilerClass)) { $container->addCompilerPass( DoctrineOrmMappingsPass::createXmlMappingDriver( $mappings, array('fos_user.model_manager_name'), 'fos_user.backend_type_orm' )); } $mongoCompilerClass = 'Doctrine\Bundle\MongoDBBundle\DependencyInjection\Compiler\DoctrineMongoDBMappingsPass'; if (class_exists($mongoCompilerClass)) { $container->addCompilerPass( DoctrineMongoDBMappingsPass::createXmlMappingDriver( $mappings, array('fos_user.model_manager_name'), 'fos_user.backend_type_mongodb' )); } $couchCompilerClass = 'Doctrine\Bundle\CouchDBBundle\DependencyInjection\Compiler\DoctrineCouchDBMappingsPass'; if (class_exists($couchCompilerClass)) { $container->addCompilerPass( DoctrineCouchDBMappingsPass::createXmlMappingDriver( $mappings, array('fos_user.model_manager_name'), 'fos_user.backend_type_couchdb' )); } $phpcrCompilerClass = 'Doctrine\Bundle\PHPCRBundle\DependencyInjection\Compiler\DoctrinePhpcrMappingsPass'; if (class_exists($phpcrCompilerClass)) { $container->addCompilerPass( DoctrinePhpcrMappingsPass::createXmlMappingDriver( $mappings, array('fos_user.model_manager_name'), 'fos_user.backend_type_phpcr' )); } } }

PDF brought to you by generated on February 10, 2014

Chapter 37: How to provide model classes for several Doctrine implementations | 129

Note the class_exists3 check. This is crucial, as you do not want your bundle to have a hard dependency on all Doctrine bundles but let the user decide which to use. The compiler pass provides factory methods for all drivers provided by Doctrine: Annotations, XML, Yaml, PHP and StaticPHP. The arguments are: a map/hash of absolute directory path to namespace; an array of container parameters that your bundle uses to specify the name of the Doctrine manager that it is using. In the above example, the FOSUserBundle stores the manager name that's being used under the fos_user.model_manager_name parameter. The compiler pass will append the parameter Doctrine is using to specify the name of the default manager. The first parameter found is used and the mappings are registered with that manager; an optional container parameter name that will be used by the compiler pass to determine if this Doctrine type is used at all. This is relevant if your user has more than one type of Doctrine bundle installed, but your bundle is only used with one type of Doctrine.
The factory method is using the SymfonyFileLocator of Doctrine, meaning it will only see XML and YML mapping files if they do not contain the full namespace as the filename. This is by design: the SymfonyFileLocator simplifies things by assuming the files are just the "short" version of the class as their filename (e.g. BlogPost.orm.xml) If you also need to map a base class, you can register a compiler pass with the DefaultFileLocator like this. This code is simply taken from the DoctrineOrmMappingsPass and adapted to use the DefaultFileLocator instead of the SymfonyFileLocator:
Listing 37-2

1 2 3 4 5 6 7 8 9 10 11 12 13

private function buildMappingCompilerPass() { $arguments = array(array(realpath(__DIR__ . '/Resources/config/doctrine-base')), '.orm.xml'); $locator = new Definition('Doctrine\Common\Persistence\Mapping\Driver\DefaultFileLocator', $arguments); $driver = new Definition('Doctrine\ORM\Mapping\Driver\XmlDriver', array($locator)); return new DoctrineOrmMappingsPass( $driver, array('Full\Namespace'), array('your_bundle.manager_name'), 'your_bundle.orm_enabled' ); }

Now place your mapping file into /Resources/config/doctrine-base with the fully qualified class name, separated by . instead of \, for example Other.Namespace.Model.Name.orm.xml. You may not mix the two as otherwise the SymfonyFileLocator will get confused. Adjust accordingly for the other Doctrine implementations.

3. http://php.net/manual/en/function.class-exists.php

PDF brought to you by generated on February 10, 2014

Chapter 37: How to provide model classes for several Doctrine implementations | 130

Chapter 38

How to implement a simple Registration Form

Some forms have extra fields whose values don't need to be stored in the database. For example, you may want to create a registration form with some extra fields (like a "terms accepted" checkbox field) and embed the form that actually stores the account information.

The simple User model

You have a simple User entity mapped to the database:
Listing 38-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

// src/Acme/AccountBundle/Entity/User.php namespace Acme\AccountBundle\Entity;

use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Validator\Constraints as Assert; use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;

/** * @ORM\Entity * @UniqueEntity(fields="email", message="Email already taken") */ class User { /** * @ORM\Id * @ORM\Column(type="integer") * @ORM\GeneratedValue(strategy="AUTO") */ protected $id; /** * @ORM\Column(type="string", length=255) * @Assert\NotBlank() * @Assert\Email() */ protected $email;

PDF brought to you by generated on February 10, 2014

Chapter 38: How to implement a simple Registration Form | 131

27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 }

/** * @ORM\Column(type="string", length=255) * @Assert\NotBlank() * @Assert\Length(max = 4096) */ protected $plainPassword;

public function getId() { return $this->id; } public function getEmail() { return $this->email; } public function setEmail($email) { $this->email = $email; } public function getPlainPassword() { return $this->plainPassword; } public function setPlainPassword($password) { $this->plainPassword = $password; }

This User entity contains three fields and two of them (email and plainPassword) should display on the form. The email property must be unique in the database, this is enforced by adding this validation at the top of the class.
If you want to integrate this User within the security system, you need to implement the UserInterface of the Security component.

Why the 4096 Password Limit?

Notice that the plainPassword field has a max length of 4096 characters. For security purposes (CVE-2013-57501), Symfony limits the plain password length to 4096 characters when encoding it. Adding this constraint makes sure that your form will give a validation error if anyone tries a super-long password. You'll need to add this constraint anywhere in your application where your user submits a plaintext password (e.g. change password form). The only place where you don't need to worry about this is your login form, since Symfony's Security component handles this for you.

1. http://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form

PDF brought to you by generated on February 10, 2014

Chapter 38: How to implement a simple Registration Form | 132

Create a Form for the Model

Next, create the form for the User model:
Listing 38-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

// src/Acme/AccountBundle/Form/Type/UserType.php namespace Acme\AccountBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class UserType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('email', 'email'); $builder->add('plainPassword', 'repeated', array( 'first_name' => 'password', 'second_name' => 'confirm', 'type' => 'password', )); } public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'data_class' => 'Acme\AccountBundle\Entity\User' )); } public function getName() { return 'user'; } }

There are just two fields: email and plainPassword (repeated to confirm the entered password). The data_class option tells the form the name of the underlying data class (i.e. your User entity).
To explore more things about the Form component, read Forms.

Embedding the User form into a Registration Form

The form that you'll use for the registration page is not the same as the form used to simply modify the User (i.e. UserType). The registration form will contain further fields like "accept the terms", whose value won't be stored in the database. Start by creating a simple class which represents the "registration":
Listing 38-3

1 // src/Acme/AccountBundle/Form/Model/Registration.php 2 namespace Acme\AccountBundle\Form\Model; 3 4 use Symfony\Component\Validator\Constraints as Assert;

PDF brought to you by generated on February 10, 2014

Chapter 38: How to implement a simple Registration Form | 133

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

use Acme\AccountBundle\Entity\User; class Registration { /** * @Assert\Type(type="Acme\AccountBundle\Entity\User") * @Assert\Valid() */ protected $user;

/** * @Assert\NotBlank() * @Assert\True() */ protected $termsAccepted;

public function setUser(User $user) { $this->user = $user; } public function getUser() { return $this->user; } public function getTermsAccepted() { return $this->termsAccepted; } public function setTermsAccepted($termsAccepted) { $this->termsAccepted = (Boolean) $termsAccepted; } }

Next, create the form for this Registration model:

Listing 38-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

// src/Acme/AccountBundle/Form/Type/RegistrationType.php namespace Acme\AccountBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class RegistrationType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('user', new UserType()); $builder->add( 'terms', 'checkbox', array('property_path' => 'termsAccepted') ); }

PDF brought to you by generated on February 10, 2014

Chapter 38: How to implement a simple Registration Form | 134

19 20 21 22 23 }

public function getName() { return 'registration'; }

You don't need to use a special method for embedding the UserType form. A form is a field, too - so you can add this like any other field, with the expectation that the Registration.user property will hold an instance of the User class.

Handling the Form Submission

Next, you need a controller to handle the form. Start by creating a simple controller for displaying the registration form:
Listing 38-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

// src/Acme/AccountBundle/Controller/AccountController.php namespace Acme\AccountBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\HttpFoundation\Response; use Acme\AccountBundle\Form\Type\RegistrationType; use Acme\AccountBundle\Form\Model\Registration; class AccountController extends Controller { public function registerAction() { $registration = new Registration(); $form = $this->createForm(new RegistrationType(), $registration, array( 'action' => $this->generateUrl('account_create'), )); return $this->render( 'AcmeAccountBundle:Account:register.html.twig', array('form' => $form->createView()) ); } }

And its template:

Listing 38-6

1 {# src/Acme/AccountBundle/Resources/views/Account/register.html.twig #} 2 {{ form(form) }}

Next, create the controller which handles the form submission. This performs the validation and saves the data into the database:
Listing 38-7

1 public function createAction(Request $request) 2 { 3 $em = $this->getDoctrine()->getManager(); 4 5 $form = $this->createForm(new RegistrationType(), new Registration()); 6

PDF brought to you by generated on February 10, 2014

Chapter 38: How to implement a simple Registration Form | 135

7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 }

$form->handleRequest($request); if ($form->isValid()) { $registration = $form->getData(); $em->persist($registration->getUser()); $em->flush(); return $this->redirect(...); } return $this->render( 'AcmeAccountBundle:Account:register.html.twig', array('form' => $form->createView()) );

Add New Routes

Next, update your routes. If you're placing your routes inside your bundle (as shown here), don't forget to make sure that the routing file is being imported.
Listing 38-8

1 # src/Acme/AccountBundle/Resources/config/routing.yml 2 account_register: 3 path: /register 4 defaults: { _controller: AcmeAccountBundle:Account:register } 5 6 account_create: 7 path: /register/create 8 defaults: { _controller: AcmeAccountBundle:Account:create }

Update your Database Schema

Of course, since you've added a User entity during this tutorial, make sure that your database schema has been updated properly:
Listing 38-9

1 $ php app/console doctrine:schema:update --force

That's it! Your form now validates, and allows you to save the User object to the database. The extra terms checkbox on the Registration model class is used during validation, but not actually used afterwards when saving the User to the database.

PDF brought to you by generated on February 10, 2014

Chapter 38: How to implement a simple Registration Form | 136

Chapter 39

How to send an Email

Sending emails is a classic task for any web application and one that has special complications and potential pitfalls. Instead of recreating the wheel, one solution to send emails is to use the SwiftmailerBundle, which leverages the power of the Swift Mailer1 library.
Don't forget to enable the bundle in your kernel before using it:
Listing 39-1

1 public function registerBundles() 2 { 3 $bundles = array( 4 // ... 5 6 new Symfony\Bundle\SwiftmailerBundle\SwiftmailerBundle(), 7 ); 8 9 // ... 10 }

Configuration
Before using Swift Mailer, be sure to include its configuration. The only mandatory configuration parameter is transport:
Listing 39-2

1 # app/config/config.yml 2 swiftmailer: 3 transport: smtp 4 encryption: ssl 5 auth_mode: login 6 host: smtp.gmail.com 7 username: your_username 8 password: your_password

1. http://swiftmailer.org/

PDF brought to you by generated on February 10, 2014

Chapter 39: How to send an Email | 137

The majority of the Swift Mailer configuration deals with how the messages themselves should be delivered. The following configuration attributes are available: transport (smtp, mail, sendmail, or gmail) username password host port encryption (tls, or ssl) auth_mode (plain, login, or cram-md5) spool type (how to queue the messages, file or memory is supported, see How to Spool Emails) path (where to store the messages) delivery_address (an email address where to send ALL emails) disable_delivery (set to true to disable delivery completely)

Sending Emails
The Swift Mailer library works by creating, configuring and then sending Swift_Message objects. The "mailer" is responsible for the actual delivery of the message and is accessible via the mailer service. Overall, sending an email is pretty straightforward:
Listing 39-3

1 public function indexAction($name) 2 { 3 $message = \Swift_Message::newInstance() 4 ->setSubject('Hello Email') 5 ->setFrom('[email protected]') 6 ->setTo('[email protected]') 7 ->setBody( 8 $this->renderView( 9 'HelloBundle:Hello:email.txt.twig', 10 array('name' => $name) 11 ) 12 ) 13 ; 14 $this->get('mailer')->send($message); 15 16 return $this->render(...); 17 }

To keep things decoupled, the email body has been stored in a template and rendered with the renderView() method. The $message object supports many more options, such as including attachments, adding HTML content, and much more. Fortunately, Swift Mailer covers the topic of Creating Messages2 in great detail in its documentation.

2. http://swiftmailer.org/docs/messages.html

PDF brought to you by generated on February 10, 2014

Chapter 39: How to send an Email | 138

Several other cookbook articles are available related to sending emails in Symfony2: How to use Gmail to send Emails How to Work with Emails During Development How to Spool Emails

PDF brought to you by generated on February 10, 2014

Chapter 39: How to send an Email | 139

Chapter 40

How to use Gmail to send Emails

During development, instead of using a regular SMTP server to send emails, you might find using Gmail easier and more practical. The SwiftmailerBundle makes it really easy.
Instead of using your regular Gmail account, it's of course recommended that you create a special account.

In the development configuration file, change the transport setting to gmail and set the username and password to the Google credentials:
Listing 40-1

1 # app/config/config_dev.yml 2 swiftmailer: 3 transport: gmail 4 username: your_gmail_username 5 password: your_gmail_password

You're done!
If you are using the Symfony Standard Edition, configure the parameters at parameters.yml:
Listing 40-2

1 # app/config/parameters.yml 2 parameters: 3 # ... 4 mailer_transport: gmail 5 mailer_host: ~ 6 mailer_user: your_gmail_username 7 mailer_password: your_gmail_password

The gmail transport is simply a shortcut that uses the smtp transport and sets encryption, auth_mode and host to work with Gmail.

PDF brought to you by generated on February 10, 2014

Chapter 40: How to use Gmail to send Emails | 140

Chapter 41

How to Work with Emails During Development

When developing an application which sends email, you will often not want to actually send the email to the specified recipient during development. If you are using the SwiftmailerBundle with Symfony2, you can easily achieve this through configuration settings without having to make any changes to your application's code at all. There are two main choices when it comes to handling email during development: (a) disabling the sending of email altogether or (b) sending all email to a specific address.

Disabling Sending
You can disable sending email by setting the disable_delivery option to true. This is the default in the test environment in the Standard distribution. If you do this in the test specific config then email will not be sent when you run tests, but will continue to be sent in the prod and dev environments:
Listing 41-1

1 # app/config/config_test.yml 2 swiftmailer: 3 disable_delivery: true

If you'd also like to disable deliver in the dev environment, simply add this same configuration to the config_dev.yml file.

Sending to a Specified Address

You can also choose to have all email sent to a specific address, instead of the address actually specified when sending the message. This can be done via the delivery_address option:
Listing 41-2

1 # app/config/config_dev.yml 2 swiftmailer: 3 delivery_address: [email protected]

Now, suppose you're sending an email to [email protected].

Listing 41-3

PDF brought to you by generated on February 10, 2014

Chapter 41: How to Work with Emails During Development | 141

1 public function indexAction($name) 2 { 3 $message = \Swift_Message::newInstance() 4 ->setSubject('Hello Email') 5 ->setFrom('[email protected]') 6 ->setTo('[email protected]') 7 ->setBody( 8 $this->renderView( 9 'HelloBundle:Hello:email.txt.twig', 10 array('name' => $name) 11 ) 12 ) 13 ; 14 $this->get('mailer')->send($message); 15 16 return $this->render(...); 17 }

In the dev environment, the email will instead be sent to [email protected]. Swift Mailer will add an extra header to the email, X-Swift-To, containing the replaced address, so you can still see who it would have been sent to.
In addition to the to addresses, this will also stop the email being sent to any CC and BCC addresses set for it. Swift Mailer will add additional headers to the email with the overridden addresses in them. These are X-Swift-Cc and X-Swift-Bcc for the CC and BCC addresses respectively.

Viewing from the Web Debug Toolbar

You can view any email sent during a single response when you are in the dev environment using the Web Debug Toolbar. The email icon in the toolbar will show how many emails were sent. If you click it, a report will open showing the details of the sent emails. If you're sending an email and then immediately redirecting to another page, the web debug toolbar will not display an email icon or a report on the next page. Instead, you can set the intercept_redirects option to true in the config_dev.yml file, which will cause the redirect to stop and allow you to open the report with details of the sent emails.
Listing 41-4

1 # app/config/config_dev.yml 2 web_profiler: 3 intercept_redirects: true

Alternatively, you can open the profiler after the redirect and search by the submit URL used on the previous request (e.g. /contact/handle). The profiler's search feature allows you to load the profiler information for any past requests.

PDF brought to you by generated on February 10, 2014

Chapter 41: How to Work with Emails During Development | 142

Chapter 42

How to Spool Emails

When you are using the SwiftmailerBundle to send an email from a Symfony2 application, it will default to sending the email immediately. You may, however, want to avoid the performance hit of the communication between Swift Mailer and the email transport, which could cause the user to wait for the next page to load while the email is sending. This can be avoided by choosing to "spool" the emails instead of sending them directly. This means that Swift Mailer does not attempt to send the email but instead saves the message to somewhere such as a file. Another process can then read from the spool and take care of sending the emails in the spool. Currently only spooling to file or memory is supported by Swift Mailer.

Spool using memory

When you use spooling to store the emails to memory, they will get sent right before the kernel terminates. This means the email only gets sent if the whole request got executed without any unhandled Exception or any errors. To configure swiftmailer with the memory option, use the following configuration:
Listing 42-1

1 # app/config/config.yml 2 swiftmailer: 3 # ... 4 spool: { type: memory }

Spool using a file

In order to use the spool with a file, use the following configuration:
Listing 42-2

1 # app/config/config.yml 2 swiftmailer: 3 # ... 4 spool:

PDF brought to you by generated on February 10, 2014

Chapter 42: How to Spool Emails | 143

5 6

type: file path: /path/to/spool

If you want to store the spool somewhere with your project directory, remember that you can use the %kernel.root_dir% parameter to reference the project's root:
Listing 42-3

1 path: "%kernel.root_dir%/spool"

Now, when your app sends an email, it will not actually be sent but instead added to the spool. Sending the messages from the spool is done separately. There is a console command to send the messages in the spool:
Listing 42-4

1 $ php app/console swiftmailer:spool:send --env=prod

It has an option to limit the number of messages to be sent:

Listing 42-5

1 $ php app/console swiftmailer:spool:send --message-limit=10 --env=prod

You can also set the time limit in seconds:

Listing 42-6

1 $ php app/console swiftmailer:spool:send --time-limit=10 --env=prod

Of course you will not want to run this manually in reality. Instead, the console command should be triggered by a cron job or scheduled task and run at a regular interval.

PDF brought to you by generated on February 10, 2014

Chapter 42: How to Spool Emails | 144

Chapter 43

How to test that an Email is sent in a functional Test

Sending e-mails with Symfony2 is pretty straightforward thanks to the SwiftmailerBundle, which leverages the power of the Swift Mailer1 library. To functionally test that an email was sent, and even assert the email subject, content or any other headers, you can use the Symfony2 Profiler. Start with an easy controller action that sends an e-mail:
Listing 43-1

1 public function sendEmailAction($name) 2 { 3 $message = \Swift_Message::newInstance() 4 ->setSubject('Hello Email') 5 ->setFrom('[email protected]') 6 ->setTo('[email protected]') 7 ->setBody('You should see me from the profiler!') 8 ; 9 10 $this->get('mailer')->send($message); 11 12 return $this->render(...); 13 }

Don't forget to enable the profiler as explained in How to use the Profiler in a Functional Test.

In your functional test, use the swiftmailer collector on the profiler to get information about the messages send on the previous request:
Listing 43-2

1. http://swiftmailer.org/

PDF brought to you by generated on February 10, 2014

Chapter 43: How to test that an Email is sent in a functional Test | 145

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

// src/Acme/DemoBundle/Tests/Controller/MailControllerTest.php use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class MailControllerTest extends WebTestCase { public function testMailIsSentAndContentIsOk() { $client = static::createClient();

// Enable the profiler for the next request (it does nothing if the profiler is not available) $client->enableProfiler();
$crawler = $client->request('POST', '/path/to/above/action'); $mailCollector = $client->getProfile()->getCollector('swiftmailer');

// Check that an e-mail was sent $this->assertEquals(1, $mailCollector->getMessageCount());

$collectedMessages = $mailCollector->getMessages(); $message = $collectedMessages[0];

// Asserting e-mail data $this->assertInstanceOf('Swift_Message', $message); $this->assertEquals('Hello Email', $message->getSubject()); $this->assertEquals('[email protected]', key($message->getFrom())); $this->assertEquals('[email protected]', key($message->getTo())); $this->assertEquals( 'You should see me from the profiler!', $message->getBody() );
} }

PDF brought to you by generated on February 10, 2014

Chapter 43: How to test that an Email is sent in a functional Test | 146

Chapter 44

How to setup before and after Filters

It is quite common in web application development to need some logic to be executed just before or just after your controller actions acting as filters or hooks. In symfony1, this was achieved with the preExecute and postExecute methods. Most major frameworks have similar methods but there is no such thing in Symfony2. The good news is that there is a much better way to interfere with the Request -> Response process using the EventDispatcher component.

Token validation Example

Imagine that you need to develop an API where some controllers are public but some others are restricted to one or some clients. For these private features, you might provide a token to your clients to identify themselves. So, before executing your controller action, you need to check if the action is restricted or not. If it is restricted, you need to validate the provided token.
Please note that for simplicity in this recipe, tokens will be defined in config and neither database setup nor authentication via the Security component will be used.

Before filters with the kernel.controller Event

First, store some basic token configuration using config.yml and the parameters key:
Listing 44-1

1 # app/config/config.yml 2 parameters: 3 tokens: 4 client1: pass1 5 client2: pass2

PDF brought to you by generated on February 10, 2014

Chapter 44: How to setup before and after Filters | 147

Tag Controllers to be checked

A kernel.controller listener gets notified on every request, right before the controller is executed. So, first, you need some way to identify if the controller that matches the request needs token validation. A clean and easy way is to create an empty interface and make the controllers implement it:
Listing 44-2

1 2 3 4 5 6

namespace Acme\DemoBundle\Controller; interface TokenAuthenticatedController { // ... }

A controller that implements this interface simply looks like this:

Listing 44-3

1 2 3 4 5 6 7 8 9 10 11 12 13

namespace Acme\DemoBundle\Controller; use Acme\DemoBundle\Controller\TokenAuthenticatedController; use Symfony\Bundle\FrameworkBundle\Controller\Controller; class FooController extends Controller implements TokenAuthenticatedController { // An action that needs authentication public function barAction() { // ... } }

Creating an Event Listener

Next, you'll need to create an event listener, which will hold the logic that you want executed before your controllers. If you're not familiar with event listeners, you can learn more about them at How to create an Event Listener:
Listing 44-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// src/Acme/DemoBundle/EventListener/TokenListener.php namespace Acme\DemoBundle\EventListener;

use Acme\DemoBundle\Controller\TokenAuthenticatedController; use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException; use Symfony\Component\HttpKernel\Event\FilterControllerEvent; class TokenListener { private $tokens; public function __construct($tokens) { $this->tokens = $tokens; } public function onKernelController(FilterControllerEvent $event) { $controller = $event->getController();

/*

PDF brought to you by generated on February 10, 2014

Chapter 44: How to setup before and after Filters | 148

22 * $controller passed can be either a class or a Closure. This is not usual in 23 Symfony2 but it may happen. 24 * If it is a class, it comes in array format 25 */ 26 if (!is_array($controller)) { 27 return; 28 } 29 30 if ($controller[0] instanceof TokenAuthenticatedController) { 31 $token = $event->getRequest()->query->get('token'); 32 if (!in_array($token, $this->tokens)) { 33 throw new AccessDeniedHttpException('This action needs a valid token!'); 34 } 35 } 36 } }

Registering the Listener

Finally, register your listener as a service and tag it as an event listener. By listening on kernel.controller, you're telling Symfony that you want your listener to be called just before any controller is executed.
Listing 44-5

1 # app/config/config.yml (or inside your services.yml) 2 services: 3 demo.tokens.action_listener: 4 class: Acme\DemoBundle\EventListener\TokenListener 5 arguments: ["%tokens%"] 6 tags: 7 - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }

With this configuration, your TokenListener onKernelController method will be executed on each request. If the controller that is about to be executed implements TokenAuthenticatedController, token authentication is applied. This lets you have a "before" filter on any controller that you want.

After filters with the kernel.response Event

In addition to having a "hook" that's executed before your controller, you can also add a hook that's executed after your controller. For this example, imagine that you want to add a sha1 hash (with a salt using that token) to all responses that have passed this token authentication. Another core Symfony event - called kernel.response - is notified on every request, but after the controller returns a Response object. Creating an "after" listener is as easy as creating a listener class and registering it as a service on this event. For example, take the TokenListener from the previous example and first record the authentication token inside the request attributes. This will serve as a basic flag that this request underwent token authentication:
Listing 44-6

1 public function onKernelController(FilterControllerEvent $event) 2 { 3 // ... 4

PDF brought to you by generated on February 10, 2014

Chapter 44: How to setup before and after Filters | 149

5 6 7 8 9 10 11 12 13 14 }

if ($controller[0] instanceof TokenAuthenticatedController) { $token = $event->getRequest()->query->get('token'); if (!in_array($token, $this->tokens)) { throw new AccessDeniedHttpException('This action needs a valid token!'); }

// mark the request as having passed token authentication $event->getRequest()->attributes->set('auth_token', $token);

}

Now, add another method to this class - onKernelResponse - that looks for this flag on the request object and sets a custom header on the response if it's found:
Listing 44-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

// add the new use statement at the top of your file use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
public function onKernelResponse(FilterResponseEvent $event) { // check to see if onKernelController marked this as a token "auth'ed" request if (!$token = $event->getRequest()->attributes->get('auth_token')) { return; } $response = $event->getResponse();

// create a hash and set it as a response header $hash = sha1($response->getContent().$token); $response->headers->set('X-CONTENT-HASH', $hash);
}

Finally, a second "tag" is needed on the service definition to notify Symfony that the onKernelResponse event should be notified for the kernel.response event:
Listing 44-8

1 # app/config/config.yml (or inside your services.yml) 2 services: 3 demo.tokens.action_listener: 4 class: Acme\DemoBundle\EventListener\TokenListener 5 arguments: ["%tokens%"] 6 tags: 7 - { name: kernel.event_listener, event: kernel.controller, method: 8 onKernelController } - { name: kernel.event_listener, event: kernel.response, method: onKernelResponse }

That's it! The TokenListener is now notified before every controller is executed (onKernelController) and after every controller returns a response (onKernelResponse). By making specific controllers implement the TokenAuthenticatedController interface, your listener knows which controllers it should take action on. And by storing a value in the request's "attributes" bag, the onKernelResponse method knows to add the extra header. Have fun!

PDF brought to you by generated on February 10, 2014

Chapter 44: How to setup before and after Filters | 150

Chapter 45

How to extend a Class without using Inheritance

To allow multiple classes to add methods to another one, you can define the magic __call() method in the class you want to be extended like this:
Listing 45-1

1 class Foo 2 { 3 // ... 4 5 public function __call($method, $arguments) 6 { 7 // create an event named 'foo.method_is_not_found' 8 $event = new HandleUndefinedMethodEvent($this, $method, $arguments); 9 $this->dispatcher->dispatch('foo.method_is_not_found', $event); 10 11 // no listener was able to process the event? The method does not exist 12 if (!$event->isProcessed()) { 13 throw new \Exception(sprintf('Call to undefined method %s::%s.', 14 get_class($this), $method)); 15 } 16 17 // return the listener returned value 18 return $event->getReturnValue(); 19 } }

This uses a special HandleUndefinedMethodEvent that should also be created. This is a generic class that could be reused each time you need to use this pattern of class extension:
Listing 45-2

1 use Symfony\Component\EventDispatcher\Event; 2 3 class HandleUndefinedMethodEvent extends Event 4 { 5 protected $subject;

PDF brought to you by generated on February 10, 2014

Chapter 45: How to extend a Class without using Inheritance | 151

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 }

protected protected protected protected

$method; $arguments; $returnValue; $isProcessed = false;

public function __construct($subject, $method, $arguments) { $this->subject = $subject; $this->method = $method; $this->arguments = $arguments; } public function getSubject() { return $this->subject; } public function getMethod() { return $this->method; } public function getArguments() { return $this->arguments; }

/** * Sets the value to return and stops other listeners from being notified */ public function setReturnValue($val) { $this->returnValue = $val; $this->isProcessed = true; $this->stopPropagation(); }
public function getReturnValue() { return $this->returnValue; } public function isProcessed() { return $this->isProcessed; }

Next, create a class that will listen to the foo.method_is_not_found event and add the method bar():
Listing 45-3

1 class Bar 2 { 3 public function onFooMethodIsNotFound(HandleUndefinedMethodEvent $event) 4 { 5 // only respond to the calls to the 'bar' method 6 if ('bar' != $event->getMethod()) { 7 // allow another listener to take care of this unknown method 8 return;

PDF brought to you by generated on February 10, 2014

Chapter 45: How to extend a Class without using Inheritance | 152

9 10 11 12 13 14 15 16 17 18 19 20 21 22 }

// the subject object (the foo instance) $foo = $event->getSubject(); // the bar method arguments $arguments = $event->getArguments(); // ... do something // set the return value $event->setReturnValue($someValue);
}

Finally, add the new bar method to the Foo class by registering an instance of Bar with the foo.method_is_not_found event:
Listing 45-4

1 $bar = new Bar(); 2 $dispatcher->addListener('foo.method_is_not_found', array($bar, 'onFooMethodIsNotFound'));

PDF brought to you by generated on February 10, 2014

Chapter 45: How to extend a Class without using Inheritance | 153

Chapter 46

How to customize a Method Behavior without using Inheritance

Doing something before or after a Method Call

If you want to do something just before, or just after a method is called, you can dispatch an event respectively at the beginning or at the end of the method:
Listing 46-1

1 class Foo 2 { 3 // ... 4 5 public function send($foo, $bar) 6 { 7 // do something before the method 8 $event = new FilterBeforeSendEvent($foo, $bar); 9 $this->dispatcher->dispatch('foo.pre_send', $event); 10 11 // get $foo and $bar from the event, they may have been modified 12 $foo = $event->getFoo(); 13 $bar = $event->getBar(); 14 15 // the real method implementation is here 16 $ret = ...; 17 18 // do something after the method 19 $event = new FilterSendReturnValue($ret); 20 $this->dispatcher->dispatch('foo.post_send', $event); 21 22 return $event->getReturnValue(); 23 } 24 }

PDF brought to you by generated on February 10, 2014

Chapter 46: How to customize a Method Behavior without using Inheritance | 154

In this example, two events are thrown: foo.pre_send, before the method is executed, and foo.post_send after the method is executed. Each uses a custom Event class to communicate information to the listeners of the two events. These event classes would need to be created by you and should allow, in this example, the variables $foo, $bar and $ret to be retrieved and set by the listeners. For example, assuming the FilterSendReturnValue has a setReturnValue method, one listener might look like this:
Listing 46-2

1 public function onFooPostSend(FilterSendReturnValue $event) 2 { 3 $ret = $event->getReturnValue(); 4 // modify the original ``$ret`` value 5 6 $event->setReturnValue($ret); 7 }

PDF brought to you by generated on February 10, 2014

Chapter 46: How to customize a Method Behavior without using Inheritance | 155

Chapter 47

How to use Expressions in Security, Routing, Services, and Validation

New in version 2.4: The expression functionality was introduced in Symfony 2.4.

In Symfony 2.4, a powerful ExpressionLanguage component was added to Symfony. This allows us to add highly customized logic inside configuration. The Symfony Framework leverages expressions out of the box in the following ways: Configuring services; Route matching conditions; Checking security and access controls with allow_if; Validation.

For more information about how to create and work with expressions, see The Expression Syntax.

PDF brought to you by generated on February 10, 2014

Chapter 47: How to use Expressions in Security, Routing, Services, and Validation | 156

Chapter 48

How to customize Form Rendering

Symfony gives you a wide variety of ways to customize how a form is rendered. In this guide, you'll learn how to customize every possible part of your form with as little effort as possible whether you use Twig or PHP as your templating engine.

Form Rendering Basics

Recall that the label, error and HTML widget of a form field can easily be rendered by using the form_row Twig function or the row PHP helper method:
Listing 48-1

1 {{ form_row(form.age) }}

You can also render each of the three parts of the field individually:
Listing 48-2

1 <div> 2 {{ form_label(form.age) }} 3 {{ form_errors(form.age) }} 4 {{ form_widget(form.age) }} 5 </div>

In both cases, the form label, errors and HTML widget are rendered by using a set of markup that ships standard with Symfony. For example, both of the above templates would render:
Listing 48-3

1 <div> 2 <label for="form_age">Age</label> 3 <ul> 4 <li>This field is required</li> 5 </ul> 6 <input type="number" id="form_age" name="form[age]" /> 7 </div>

To quickly prototype and test a form, you can render the entire form with just one line:
Listing 48-4

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 157

1 {{ form_widget(form) }}

The remainder of this recipe will explain how every part of the form's markup can be modified at several different levels. For more information about form rendering in general, see Rendering a Form in a Template.

What are Form Themes?

Symfony uses form fragments - a small piece of a template that renders just one part of a form - to render each part of a form - field labels, errors, input text fields, select tags, etc. The fragments are defined as blocks in Twig and as template files in PHP. A theme is nothing more than a set of fragments that you want to use when rendering a form. In other words, if you want to customize one portion of how a form is rendered, you'll import a theme which contains a customization of the appropriate form fragments. Symfony comes with a default theme (form_div_layout.html.twig1 in Twig and FrameworkBundle:Form in PHP) that defines each and every fragment needed to render every part of a form. In the next section you will learn how to customize a theme by overriding some or all of its fragments. For example, when the widget of an integer type field is rendered, an input number field is generated
Listing 48-5

1 {{ form_widget(form.age) }}

renders:
Listing 48-6

1 <input type="number" id="form_age" name="form[age]" required="required" value="33" />

Internally, Symfony uses the integer_widget fragment to render the field. This is because the field type is integer and you're rendering its widget (as opposed to its label or errors). In Twig that would default to the block integer_widget from the form_div_layout.html.twig2 template. In PHP it would rather be the integer_widget.html.php file located in the FrameworkBundle/ Resources/views/Form folder. The default implementation of the integer_widget fragment looks like this:
Listing 48-7

1 {# form_div_layout.html.twig #} 2 {% block integer_widget %} 3 {% set type = type|default('number') %} 4 {{ block('form_widget_simple') }} 5 {% endblock integer_widget %}

As you can see, this fragment itself renders another fragment - form_widget_simple:
Listing 48-8

1 {# form_div_layout.html.twig #} 2 {% block form_widget_simple %} 3 {% set type = type|default('text') %} 4 <input type="{{ type }}" {{ block('widget_attributes') }} {% if value is not empty 5 %}value="{{ value }}" {% endif %}/> {% endblock form_widget_simple %}

1. https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig 2. https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 158

The point is, the fragments dictate the HTML output of each part of a form. To customize the form output, you just need to identify and override the correct fragment. A set of these form fragment customizations is known as a form "theme". When rendering a form, you can choose which form theme(s) you want to apply. In Twig a theme is a single template file and the fragments are the blocks defined in this file. In PHP a theme is a folder and the fragments are individual template files in this folder.

Knowing which block to customize

In this example, the customized fragment name is integer_widget because you want to override the HTML widget for all integer field types. If you need to customize textarea fields, you would customize textarea_widget. As you can see, the fragment name is a combination of the field type and which part of the field is being rendered (e.g. widget, label, errors, row). As such, to customize how errors are rendered for just input text fields, you should customize the text_errors fragment. More commonly, however, you'll want to customize how errors are displayed across all fields. You can do this by customizing the form_errors fragment. This takes advantage of field type inheritance. Specifically, since the text type extends from the form type, the Form component will first look for the type-specific fragment (e.g. text_errors) before falling back to its parent fragment name if it doesn't exist (e.g. form_errors). For more information on this topic, see Form Fragment Naming.

Form Theming
To see the power of form theming, suppose you want to wrap every input number field with a div tag. The key to doing this is to customize the integer_widget fragment.

Form Theming in Twig

When customizing the form field block in Twig, you have two options on where the customized form block can live: Method Inside the same template as the form Inside a separate template Pros Quick and easy Can be reused by many templates Cons Can't be reused in other templates Requires an extra template to be created

Both methods have the same effect but are better in different situations.

Method 1: Inside the same Template as the Form

The easiest way to customize the integer_widget block is to customize it directly in the template that's actually rendering the form.
Listing 48-9

1 {% extends '::base.html.twig' %} 2

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 159

3 4 5 6 7 8 9 10 11 12 13 14 15 16

{% form_theme form _self %} {% block integer_widget %} <div class="integer_widget"> {% set type = type|default('number') %} {{ block('form_widget_simple') }} </div> {% endblock %} {% block content %} {# ... render the form #} {{ form_row(form.age) }} {% endblock %}

By using the special {% form_theme form _self %} tag, Twig looks inside the same template for any overridden form blocks. Assuming the form.age field is an integer type field, when its widget is rendered, the customized integer_widget block will be used. The disadvantage of this method is that the customized form block can't be reused when rendering other forms in other templates. In other words, this method is most useful when making form customizations that are specific to a single form in your application. If you want to reuse a form customization across several (or all) forms in your application, read on to the next section.

Method 2: Inside a Separate Template

You can also choose to put the customized integer_widget form block in a separate template entirely. The code and end-result are the same, but you can now re-use the form customization across many templates:
Listing 48-10

1 {# src/Acme/DemoBundle/Resources/views/Form/fields.html.twig #} 2 {% block integer_widget %} 3 <div class="integer_widget"> 4 {% set type = type|default('number') %} 5 {{ block('form_widget_simple') }} 6 </div> 7 {% endblock %}

Now that you've created the customized form block, you need to tell Symfony to use it. Inside the template where you're actually rendering your form, tell Symfony to use the template via the form_theme tag:
Listing 48-11

1 {% form_theme form 'AcmeDemoBundle:Form:fields.html.twig' %} 2 3 {{ form_widget(form.age) }}

When the form.age widget is rendered, Symfony will use the integer_widget block from the new template and the input tag will be wrapped in the div element specified in the customized block.

Child Forms
You can also apply a form theme to a specific child of your form:
Listing 48-12

1 {% form_theme form.child 'AcmeDemoBundle:Form:fields.html.twig' %}

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 160

This is useful when you want to have a custom theme for a nested form that's different than the one of your main form. Just specify both your themes:
Listing 48-13

1 {% form_theme form 'AcmeDemoBundle:Form:fields.html.twig' %} 2 3 {% form_theme form.child 'AcmeDemoBundle:Form:fields_child.html.twig' %}

Form Theming in PHP

When using PHP as a templating engine, the only method to customize a fragment is to create a new template file - this is similar to the second method used by Twig. The template file must be named after the fragment. You must create a integer_widget.html.php file in order to customize the integer_widget fragment.
Listing 48-14

1 <!-- src/Acme/DemoBundle/Resources/views/Form/integer_widget.html.php --> 2 <div class="integer_widget"> 3 <?php echo $view['form']->block($form, 'form_widget_simple', array('type' => 4 isset($type) ? $type : "number")) ?> </div>

Now that you've created the customized form template, you need to tell Symfony to use it. Inside the template where you're actually rendering your form, tell Symfony to use the theme via the setTheme helper method:
Listing 48-15

1 <?php $view['form']->setTheme($form, array('AcmeDemoBundle:Form')); ?> 2 3 <?php $view['form']->widget($form['age']) ?>

When the form.age widget is rendered, Symfony will use the customized integer_widget.html.php template and the input tag will be wrapped in the div element. If you want to apply a theme to a specific child form, pass it to the setTheme method:
Listing 48-16

1 <?php $view['form']->setTheme($form['child'], 'AcmeDemoBundle:Form/Child'); ?>

Referencing Base Form Blocks (Twig specific)

So far, to override a particular form block, the best method is to copy the default block from form_div_layout.html.twig3, paste it into a different template, and then customize it. In many cases, you can avoid doing this by referencing the base block when customizing it. This is easy to do, but varies slightly depending on if your form block customizations are in the same template as the form or a separate template.

Referencing Blocks from inside the same Template as the Form

Import the blocks by adding a use tag in the template where you're rendering the form:
Listing 48-17

1 {% use 'form_div_layout.html.twig' with integer_widget as base_integer_widget %}

3. https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 161

Now, when the blocks from form_div_layout.html.twig4 are imported, the integer_widget block is called base_integer_widget. This means that when you redefine the integer_widget block, you can reference the default markup via base_integer_widget:
Listing 48-18

1 {% block integer_widget %} 2 <div class="integer_widget"> 3 {{ block('base_integer_widget') }} 4 </div> 5 {% endblock %}

Referencing Base Blocks from an External Template

If your form customizations live inside an external template, you can reference the base block by using the parent() Twig function:
Listing 48-19

1 2 3 4 5 6 7 8

{# src/Acme/DemoBundle/Resources/views/Form/fields.html.twig #} {% extends 'form_div_layout.html.twig' %}

{% block integer_widget %} <div class="integer_widget"> {{ parent() }} </div> {% endblock %}

It is not possible to reference the base block when using PHP as the templating engine. You have to manually copy the content from the base block to your new template file.

Making Application-wide Customizations

If you'd like a certain form customization to be global to your application, you can accomplish this by making the form customizations in an external template and then importing it inside your application configuration.

Twig
By using the following configuration, any customized form blocks inside the AcmeDemoBundle:Form:fields.html.twig template will be used globally when a form is rendered.
Listing 48-20

1 # app/config/config.yml 2 twig: 3 form: 4 resources: 5 - 'AcmeDemoBundle:Form:fields.html.twig' 6 # ...

By default, Twig uses a div layout when rendering forms. Some people, however, may prefer to render forms in a table layout. Use the form_table_layout.html.twig resource to use such a layout:
Listing 48-21

4. https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 162

1 # app/config/config.yml 2 twig: 3 form: 4 resources: ['form_table_layout.html.twig'] 5 # ...

If you only want to make the change in one template, add the following line to your template file rather than adding the template as a resource:
Listing 48-22

1 {% form_theme form 'form_table_layout.html.twig' %}

Note that the form variable in the above code is the form view variable that you passed to your template.

PHP
By using the following configuration, any customized form fragments inside the src/Acme/DemoBundle/ Resources/views/Form folder will be used globally when a form is rendered.
Listing 48-23

1 # app/config/config.yml 2 framework: 3 templating: 4 form: 5 resources: 6 - 'AcmeDemoBundle:Form' 7 # ...

By default, the PHP engine uses a div layout when rendering forms. Some people, however, may prefer to render forms in a table layout. Use the FrameworkBundle:FormTable resource to use such a layout:
Listing 48-24

1 # app/config/config.yml 2 framework: 3 templating: 4 form: 5 resources: 6 - 'FrameworkBundle:FormTable'

If you only want to make the change in one template, add the following line to your template file rather than adding the template as a resource:
Listing 48-25

1 <?php $view['form']->setTheme($form, array('FrameworkBundle:FormTable')); ?>

Note that the $form variable in the above code is the form view variable that you passed to your template.

How to customize an Individual field

So far, you've seen the different ways you can customize the widget output of all text field types. You can also customize individual fields. For example, suppose you have two text fields in a product form - name and description - but you only want to customize one of the fields. This can be accomplished by customizing a fragment whose name is a combination of the field's id attribute and which part of the field is being customized. For example, to customize the name field only:
Listing 48-26

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 163

1 2 3 4 5 6 7 8 9

{% form_theme form _self %} {% block _product_name_widget %} <div class="text_widget"> {{ block('form_widget_simple') }} </div> {% endblock %} {{ form_widget(form.name) }}

Here, the _product_name_widget fragment defines the template to use for the field whose id is product_name (and name is product[name]).
The product portion of the field is the form name, which may be set manually or generated automatically based on your form type name (e.g. ProductType equates to product). If you're not sure what your form name is, just view the source of your generated form.

You can also override the markup for an entire field row using the same method:
Listing 48-27

1 2 3 4 5 6 7 8 9 10 11

{% form_theme form _self %} {% block _product_name_row %} <div class="name_row"> {{ form_label(form) }} {{ form_errors(form) }} {{ form_widget(form) }} </div> {% endblock %} {{ form_row(form.name) }}

Other Common Customizations

So far, this recipe has shown you several different ways to customize a single piece of how a form is rendered. The key is to customize a specific fragment that corresponds to the portion of the form you want to control (see naming form blocks). In the next sections, you'll see how you can make several common form customizations. To apply these customizations, use one of the methods described in the Form Theming section.

Customizing Error Output

The Form component only handles how the validation errors are rendered, and not the actual validation error messages. The error messages themselves are determined by the validation constraints you apply to your objects. For more information, see the chapter on validation.

There are many different ways to customize how errors are rendered when a form is submitted with errors. The error messages for a field are rendered when you use the form_errors helper:
Listing 48-28

1 {{ form_errors(form.age) }}

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 164

By default, the errors are rendered inside an unordered list:

Listing 48-29

1 <ul> 2 <li>This field is required</li> 3 </ul>

To override how errors are rendered for all fields, simply copy, paste and customize the form_errors fragment.
Listing 48-30

1 {# form_errors.html.twig #} 2 {% block form_errors %} 3 {% spaceless %} 4 {% if errors|length > 0 %} 5 <ul> 6 {% for error in errors %} 7 <li>{{ error.message }}</li> 8 {% endfor %} 9 </ul> 10 {% endif %} 11 {% endspaceless %} 12 {% endblock form_errors %}

See Form Theming for how to apply this customization.

You can also customize the error output for just one specific field type. For example, certain errors that are more global to your form (i.e. not specific to just one field) are rendered separately, usually at the top of your form:
Listing 48-31

1 {{ form_errors(form) }}

To customize only the markup used for these errors, follow the same directions as above, but now call the block form_errors (Twig) / the file form_errors.html.php (PHP). Now, when errors for the form type are rendered, your customized fragment will be used instead of the default form_errors.

Customizing the "Form Row"

When you can manage it, the easiest way to render a form field is via the form_row function, which renders the label, errors and HTML widget of a field. To customize the markup used for rendering all form field rows, override the form_row fragment. For example, suppose you want to add a class to the div element around each row:
Listing 48-32

1 {# form_row.html.twig #} 2 {% block form_row %} 3 <div class="form_row"> 4 {{ form_label(form) }} 5 {{ form_errors(form) }} 6 {{ form_widget(form) }} 7 </div> 8 {% endblock form_row %}

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 165

See Form Theming for how to apply this customization.

Adding a "Required" Asterisk to Field Labels

If you want to denote all of your required fields with a required asterisk (*), you can do this by customizing the form_label fragment. In Twig, if you're making the form customization inside the same template as your form, modify the use tag and add the following:
Listing 48-33

1 {% use 'form_div_layout.html.twig' with form_label as base_form_label %} 2 3 {% block form_label %} 4 {{ block('base_form_label') }} 5 6 {% if required %} 7 <span class="required" title="This field is required">*</span> 8 {% endif %} 9 {% endblock %}

In Twig, if you're making the form customization inside a separate template, use the following:
Listing 48-34

1 {% extends 'form_div_layout.html.twig' %} 2 3 {% block form_label %} 4 {{ parent() }} 5 6 {% if required %} 7 <span class="required" title="This field is required">*</span> 8 {% endif %} 9 {% endblock %}

When using PHP as a templating engine you have to copy the content from the original template:
Listing 48-35

1 2 3 4 5 6 7 8 9 10 11 12

<!-- form_label.html.php --> <!-- original content --> <?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?> <?php if (!$compound) { $label_attr['for'] = $id; } ?> <?php if (!$label) { $label = $view['form']->humanize($name); } ?> <label <?php foreach ($label_attr as $k => $v) { printf('%s="%s" ', $view->escape($k), $view->escape($v)); } ?>><?php echo $view->escape($view['translator']->trans($label, array(), $translation_domain)) ?></label> <!-- customization --> <?php if ($required) : ?> <span class="required" title="This field is required">*</span> <?php endif ?>

See Form Theming for how to apply this customization.

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 166

Using CSS only

By default, label tags of required fields are rendered with a required CSS class. Thus, you can also add an asterisk using CSS only:
Listing 48-36

1 label.required:before { 2 content: "* "; 3 }

Adding "help" messages

You can also customize your form widgets to have an optional "help" message. In Twig, if you're making the form customization inside the same template as your form, modify the use tag and add the following:
Listing 48-37

1 {% use 'form_div_layout.html.twig' with form_widget_simple as base_form_widget_simple %} 2 3 {% block form_widget_simple %} 4 {{ block('base_form_widget_simple') }} 5 6 {% if help is defined %} 7 <span class="help">{{ help }}</span> 8 {% endif %} 9 {% endblock %}

In Twig, if you're making the form customization inside a separate template, use the following:
Listing 48-38

1 {% extends 'form_div_layout.html.twig' %} 2 3 {% block form_widget_simple %} 4 {{ parent() }} 5 6 {% if help is defined %} 7 <span class="help">{{ help }}</span> 8 {% endif %} 9 {% endblock %}

When using PHP as a templating engine you have to copy the content from the original template:
Listing 48-39

1 2 3 4 5 6 7 8 9 10 11 12 13

<!-- form_widget_simple.html.php --> <!-- Original content --> <input type="<?php echo isset($type) ? $view->escape($type) : 'text' ?>" <?php if (!empty($value)): ?>value="<?php echo $view->escape($value) ?>"<?php endif ?> <?php echo $view['form']->block($form, 'widget_attributes') ?> /> <!-- Customization --> <?php if (isset($help)) : ?> <span class="help"><?php echo $view->escape($help) ?></span> <?php endif ?>

To render a help message below a field, pass in a help variable:

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 167

Listing 48-40

1 {{ form_widget(form.title, {'help': 'foobar'}) }}

See Form Theming for how to apply this customization.

Using Form Variables

Most of the functions available for rendering different parts of a form (e.g. the form widget, form label, form errors, etc.) also allow you to make certain customizations directly. Look at the following example:
Listing 48-41

1 {# render a widget, but add a "foo" class to it #} 2 {{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}

The array passed as the second argument contains form "variables". For more details about this concept in Twig, see More about Form Variables.

PDF brought to you by generated on February 10, 2014

Chapter 48: How to customize Form Rendering | 168

Chapter 49

How to use Data Transformers

You'll often find the need to transform the data the user entered in a form into something else for use in your program. You could easily do this manually in your controller, but what if you want to use this specific form in different places? Say you have a one-to-one relation of Task to Issue, e.g. a Task optionally has an issue linked to it. Adding a listbox with all possible issues can eventually lead to a really long listbox in which it is impossible to find something. You might want to add a textbox instead, where the user can simply enter the issue number. You could try to do this in your controller, but it's not the best solution. It would be better if this issue were automatically converted to an Issue object. This is where Data Transformers come into play.

Creating the Transformer

First, create an IssueToNumberTransformer class - this class will be responsible for converting to and from the issue number and the Issue object:
Listing 49-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

// src/Acme/TaskBundle/Form/DataTransformer/IssueToNumberTransformer.php namespace Acme\TaskBundle\Form\DataTransformer;

use use use use Symfony\Component\Form\DataTransformerInterface; Symfony\Component\Form\Exception\TransformationFailedException; Doctrine\Common\Persistence\ObjectManager; Acme\TaskBundle\Entity\Issue;

class IssueToNumberTransformer implements DataTransformerInterface { /** * @var ObjectManager */ private $om;

/** * @param ObjectManager $om */ public function __construct(ObjectManager $om)

PDF brought to you by generated on February 10, 2014

Chapter 49: How to use Data Transformers | 169

20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 }

{ $this->om = $om; }

/** * Transforms an object (issue) to a string (number). * * @param Issue|null $issue * @return string */ public function transform($issue) { if (null === $issue) { return ""; }
return $issue->getNumber(); }

/** * Transforms a string (number) to an object (issue). * * @param string $number * * @return Issue|null * * @throws TransformationFailedException if object (issue) is not found. */ public function reverseTransform($number) { if (!$number) { return null; }
$issue = $this->om ->getRepository('AcmeTaskBundle:Issue') ->findOneBy(array('number' => $number)) ; if (null === $issue) { throw new TransformationFailedException(sprintf( 'An issue with number "%s" does not exist!', $number )); } return $issue; }

If you want a new issue to be created when an unknown number is entered, you can instantiate it rather than throwing the TransformationFailedException.

PDF brought to you by generated on February 10, 2014

Chapter 49: How to use Data Transformers | 170

When null is passed to the transform() method, your transformer should return an equivalent value of the type it is transforming to (e.g. an empty string, 0 for integers or 0.0 for floats).

Using the Transformer

Now that you have the transformer built, you just need to add it to your issue field in some form. You can also use transformers without creating a new custom form type by calling addModelTransformer (or addViewTransformer - see Model and View Transformers) on any field builder:
Listing 49-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

use Symfony\Component\Form\FormBuilderInterface; use Acme\TaskBundle\Form\DataTransformer\IssueToNumberTransformer; class TaskType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { // ...

// this assumes that the entity manager was passed in as an option $entityManager = $options['em']; $transformer = new IssueToNumberTransformer($entityManager); // add a normal text field, but add your transformer to it $builder->add( $builder->create('issue', 'text') ->addModelTransformer($transformer) );
} public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver ->setDefaults(array( 'data_class' => 'Acme\TaskBundle\Entity\Task', )) ->setRequired(array( 'em', )) ->setAllowedTypes(array( 'em' => 'Doctrine\Common\Persistence\ObjectManager', ));

// ...
}

// ...
}

This example requires that you pass in the entity manager as an option when creating your form. Later, you'll learn how you could create a custom issue field type to avoid needing to do this in your controller:
Listing 49-3

PDF brought to you by generated on February 10, 2014

Chapter 49: How to use Data Transformers | 171

1 $taskForm = $this->createForm(new TaskType(), $task, array( 2 'em' => $this->getDoctrine()->getManager(), 3 ));

Cool, you're done! Your user will be able to enter an issue number into the text field and it will be transformed back into an Issue object. This means that, after a successful submission, the Form framework will pass a real Issue object to Task::setIssue() instead of the issue number. If the issue isn't found, a form error will be created for that field and its error message can be controlled with the invalid_message field option.
Notice that adding a transformer requires using a slightly more complicated syntax when adding the field. The following is wrong, as the transformer would be applied to the entire form, instead of just this field:
Listing 49-4

1 // THIS IS WRONG - TRANSFORMER WILL BE APPLIED TO THE ENTIRE FORM 2 // see above example for correct code 3 $builder->add('issue', 'text') 4 ->addModelTransformer($transformer);

Model and View Transformers

In the above example, the transformer was used as a "model" transformer. In fact, there are two different types of transformers and three different types of underlying data. ../../_images/DataTransformersTypes.png In any form, the 3 different types of data are: 1) Model data - This is the data in the format used in your application (e.g. an Issue object). If you call Form::getData or Form::setData, you're dealing with the "model" data. 2) Norm Data - This is a normalized version of your data, and is commonly the same as your "model" data (though not in our example). It's not commonly used directly. 3) View Data - This is the format that's used to fill in the form fields themselves. It's also the format in which the user will submit the data. When you call Form::submit($data), the $data is in the "view" data format. The 2 different types of transformers help convert to and from each of these types of data: Model transformers: transform: "model data" => "norm data" reverseTransform: "norm data" => "model data" View transformers: transform: "norm data" => "view data" reverseTransform: "view data" => "norm data" Which transformer you need depends on your situation. To use the view transformer, call addViewTransformer.

PDF brought to you by generated on February 10, 2014

Chapter 49: How to use Data Transformers | 172

So why use the model transformer?

In this example, the field is a text field, and a text field is always expected to be a simple, scalar format in the "norm" and "view" formats. For this reason, the most appropriate transformer was the "model" transformer (which converts to/from the norm format - string issue number - to the model format - Issue object). The difference between the transformers is subtle and you should always think about what the "norm" data for a field should really be. For example, the "norm" data for a text field is a string, but is a DateTime object for a date field.

Using Transformers in a custom field type

In the above example, you applied the transformer to a normal text field. This was easy, but has two downsides: 1) You need to always remember to apply the transformer whenever you're adding a field for issue numbers. 2) You need to worry about passing in the em option whenever you're creating a form that uses the transformer. Because of these, you may choose to create a custom field type. First, create the custom field type class:
Listing 49-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

// src/Acme/TaskBundle/Form/Type/IssueSelectorType.php namespace Acme\TaskBundle\Form\Type;

use use use use use Symfony\Component\Form\AbstractType; Symfony\Component\Form\FormBuilderInterface; Acme\TaskBundle\Form\DataTransformer\IssueToNumberTransformer; Doctrine\Common\Persistence\ObjectManager; Symfony\Component\OptionsResolver\OptionsResolverInterface;

class IssueSelectorType extends AbstractType { /** * @var ObjectManager */ private $om;

/** * @param ObjectManager $om */ public function __construct(ObjectManager $om) { $this->om = $om; }
public function buildForm(FormBuilderInterface $builder, array $options) { $transformer = new IssueToNumberTransformer($this->om); $builder->addModelTransformer($transformer); } public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'invalid_message' => 'The selected issue does not exist',

PDF brought to you by generated on February 10, 2014

Chapter 49: How to use Data Transformers | 173

35 36 37 38 39 40 41 42 43 44 45 46 47 }

)); } public function getParent() { return 'text'; } public function getName() { return 'issue_selector'; }

Next, register your type as a service and tag it with form.type so that it's recognized as a custom field type:
Listing 49-6

1 services: 2 acme_demo.type.issue_selector: 3 class: Acme\TaskBundle\Form\Type\IssueSelectorType 4 arguments: ["@doctrine.orm.entity_manager"] 5 tags: 6 - { name: form.type, alias: issue_selector }

Now, whenever you need to use your special issue_selector field type, it's quite easy:
Listing 49-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// src/Acme/TaskBundle/Form/Type/TaskType.php namespace Acme\TaskBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class TaskType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('task') ->add('dueDate', null, array('widget' => 'single_text')) ->add('issue', 'issue_selector'); } public function getName() { return 'task'; } }

PDF brought to you by generated on February 10, 2014

Chapter 49: How to use Data Transformers | 174

Chapter 50

How to Dynamically Modify Forms Using Form Events

Often times, a form can't be created statically. In this entry, you'll learn how to customize your form based on three common use-cases: 1. Customizing your Form based on the underlying Data Example: you have a "Product" form and need to modify/add/remove a field based on the data on the underlying Product being edited. 2. How to Dynamically Generate Forms based on user Data Example: you create a "Friend Message" form and need to build a drop-down that contains only users that are friends with the current authenticated user. 3. Dynamic generation for submitted Forms Example: on a registration form, you have a "country" field and a "state" field which should populate dynamically based on the value in the "country" field.

Customizing your Form based on the underlying Data

Before jumping right into dynamic form generation, hold on and recall what a bare form class looks like:
Listing 50-1

1 2 3 4 5 6 7 8 9 10 11 12 13

// src/Acme/DemoBundle/Form/Type/ProductType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class ProductType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('name'); $builder->add('price');

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 175

14 15 16 17 18 19 20 21 22 23 24 25 26 27 }

} public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'data_class' => 'Acme\DemoBundle\Entity\Product' )); } public function getName() { return 'product'; }

If this particular section of code isn't already familiar to you, you probably need to take a step back and first review the Forms chapter before proceeding.

Assume for a moment that this form utilizes an imaginary "Product" class that has only two properties ("name" and "price"). The form generated from this class will look the exact same regardless if a new Product is being created or if an existing product is being edited (e.g. a product fetched from the database). Suppose now, that you don't want the user to be able to change the name value once the object has been created. To do this, you can rely on Symfony's EventDispatcher system to analyze the data on the object and modify the form based on the Product object's data. In this entry, you'll learn how to add this level of flexibility to your forms.

Adding an Event Listener to a Form Class

So, instead of directly adding that name widget, the responsibility of creating that particular field is delegated to an event listener:
Listing 50-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

// src/Acme/DemoBundle/Form/Type/ProductType.php namespace Acme\DemoBundle\Form\Type; // ... use Symfony\Component\Form\FormEvent; use Symfony\Component\Form\FormEvents;

class ProductType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('price'); $builder->addEventListener(FormEvents::PRE_SET_DATA, function(FormEvent $event) { // ... adding the name field if needed }); }

// ...
}

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 176

The goal is to create a name field only if the underlying Product object is new (e.g. hasn't been persisted to the database). Based on that, the event listener might look like the following:
Listing 50-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

// ... public function buildForm(FormBuilderInterface $builder, array $options) { // ... $builder->addEventListener(FormEvents::PRE_SET_DATA, function(FormEvent $event){ $product = $event->getData(); $form = $event->getForm(); // // // if
} }); }

check if the Product object is "new" If no data is passed to the form, the data is "null". This should be considered a new "Product" (!$product || null !== $product->getId()) { $form->add('name', 'text');

New in version 2.2: The ability to pass a string into FormInterface::add1 was added in Symfony 2.2.

You can of course use any callback type instead of a closure, e.g. a method call on the ProductType object itself for better readability:
Listing 50-4

1 2 3 4 5 6 7 8 9 10 11 12 13

// ... class ProductType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { // ... $builder->addEventListener(FormEvents::PRE_SET_DATA, array($this, 'onPreSetData')); }
public function onPreSetData(FormEvent $event){ // ... } }

The FormEvents::PRE_SET_DATA line actually resolves to the string form.pre_set_data. FormEvents2 serves an organizational purpose. It is a centralized location in which you can find all of the various form events available. You can view the full list of form events via the FormEvents3 class.

1. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#add() 2. http://api.symfony.com/2.4/Symfony/Component/Form/FormEvents.html 3. http://api.symfony.com/2.4/Symfony/Component/Form/FormEvents.html

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 177

Adding an Event Subscriber to a Form Class

For better reusability or if there is some heavy logic in your event listener, you can also move the logic for creating the name field to an event subscriber:
Listing 50-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/DemoBundle/Form/Type/ProductType.php namespace Acme\DemoBundle\Form\Type; // ... use Acme\DemoBundle\Form\EventListener\AddNameFieldSubscriber;

class ProductType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('price'); $builder->addEventSubscriber(new AddNameFieldSubscriber()); }

// ...
}

Now the logic for creating the name field resides in it own subscriber class:
Listing 50-6

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

// src/Acme/DemoBundle/Form/EventListener/AddNameFieldSubscriber.php namespace Acme\DemoBundle\Form\EventListener;

use Symfony\Component\Form\FormEvent; use Symfony\Component\Form\FormEvents; use Symfony\Component\EventDispatcher\EventSubscriberInterface; class AddNameFieldSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents() { // Tells the dispatcher that you want to listen on the form.pre_set_data // event and that the preSetData method should be called. return array(FormEvents::PRE_SET_DATA => 'preSetData'); } public function preSetData(FormEvent $event) { $product = $event->getData(); $form = $event->getForm(); if (!$product || null !== $product->getId()) { $form->add('name', 'text'); } } }

How to Dynamically Generate Forms based on user Data

Sometimes you want a form to be generated dynamically based not only on data from the form but also on something else - like some data from the current user. Suppose you have a social website where a

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 178

user can only message people marked as friends on the website. In this case, a "choice list" of whom to message should only contain users that are the current user's friends.

Creating the Form Type

Using an event listener, your form might look like this:
Listing 50-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

// src/Acme/DemoBundle/Form/Type/FriendMessageFormType.php namespace Acme\DemoBundle\Form\Type;

use use use use use use Symfony\Component\Form\AbstractType; Symfony\Component\Form\FormBuilderInterface; Symfony\Component\Form\FormEvents; Symfony\Component\Form\FormEvent; Symfony\Component\Security\Core\SecurityContext; Symfony\Component\OptionsResolver\OptionsResolverInterface;

class FriendMessageFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('subject', 'text') ->add('body', 'textarea') ; $builder->addEventListener(FormEvents::PRE_SET_DATA, function(FormEvent $event){ // ... add a choice list of friends of the current application user }); } public function getName() { return 'acme_friend_message'; } public function setDefaultOptions(OptionsResolverInterface $resolver) { } }

The problem is now to get the current user and create a choice field that contains only this user's friends. Luckily it is pretty easy to inject a service inside of the form. This can be done in the constructor:
Listing 50-8

1 2 3 4 5 6

private $securityContext; public function __construct(SecurityContext $securityContext) { $this->securityContext = $securityContext; }

You might wonder, now that you have access to the User (through the security context), why not just use it directly in buildForm and omit the event listener? This is because doing so in the buildForm method would result in the whole form type being modified and not just this one form instance. This may not usually be a problem, but technically a single form type could be used on a single request to create many forms or fields.

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 179

Customizing the Form Type

Now that you have all the basics in place you can take advantage of the SecurityContext and fill in the listener logic:
Listing 50-9

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55

// src/Acme/DemoBundle/FormType/FriendMessageFormType.php
use Symfony\Component\Security\Core\SecurityContext; use Doctrine\ORM\EntityRepository; // ... class FriendMessageFormType extends AbstractType { private $securityContext; public function __construct(SecurityContext $securityContext) { $this->securityContext = $securityContext; } public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('subject', 'text') ->add('body', 'textarea') ;

// grab the user, do a quick sanity check that one exists $user = $this->securityContext->getToken()->getUser(); if (!$user) { throw new \LogicException( 'The FriendMessageFormType cannot be used without an authenticated user!' ); }
$builder->addEventListener( FormEvents::PRE_SET_DATA, function(FormEvent $event) use ($user) { $form = $event->getForm(); $formOptions = array( 'class' => 'Acme\DemoBundle\Entity\User', 'property' => 'fullName', 'query_builder' => function(EntityRepository $er) use ($user) { // build a custom query // return $er->createQueryBuilder('u')->addOrderBy('fullName',

'DESC'); // or call a method on your repository that returns the query builder // the $er is an instance of your UserRepository // return $er->createOrderByFullNameQueryBuilder();
}, );

// create the field, this is similar the $builder->add() // field name, field type, data, options $form->add('friend', 'entity', $formOptions);
} );

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 180

56 57 }

// ...

The multiple and expanded form options will default to false because the type of the friend field is entity.

Using the Form

Our form is now ready to use and there are two possible ways to use it inside of a controller: 1. create it manually and remember to pass the security context to it; or 2. define it as a service.

a) Creating the Form manually

This is very simple, and is probably the better approach unless you're using your new form type in many places or embedding it into other forms:
Listing 50-10

1 class FriendMessageController extends Controller 2 { 3 public function newAction(Request $request) 4 { 5 $securityContext = $this->container->get('security.context'); 6 $form = $this->createForm( 7 new FriendMessageFormType($securityContext) 8 ); 9 10 // ... 11 } 12 }

b) Defining the Form as a Service

To define your form as a service, just create a normal service and then tag it with form.type.
Listing 50-11

1 # app/config/config.yml 2 services: 3 acme.form.friend_message: 4 class: Acme\DemoBundle\Form\Type\FriendMessageFormType 5 arguments: ["@security.context"] 6 tags: 7 - { name: form.type, alias: acme_friend_message }

If you wish to create it from within a controller or any other service that has access to the form factory, you then use:
Listing 50-12

1 use Symfony\Component\DependencyInjection\ContainerAware; 2 3 class FriendMessageController extends ContainerAware

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 181

4 { 5 6 7 8 9 10 11 }

public function newAction(Request $request) { $form = $this->get('form.factory')->create('acme_friend_message');

// ...
}

If you extend the Symfony\Bundle\FrameworkBundle\Controller\Controller class, you can simply call:

Listing 50-13

1 $form = $this->createForm('acme_friend_message');

You can also easily embed the form type into another form:
Listing 50-14

1 2 3 4 5

// inside some other "form type" class public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('message', 'acme_friend_message'); }

Dynamic generation for submitted Forms

Another case that can appear is that you want to customize the form specific to the data that was submitted by the user. For example, imagine you have a registration form for sports gatherings. Some events will allow you to specify your preferred position on the field. This would be a choice field for example. However the possible choices will depend on each sport. Football will have attack, defense, goalkeeper etc... Baseball will have a pitcher but will not have a goalkeeper. You will need the correct options in order for validation to pass. The meetup is passed as an entity field to the form. So we can access each sport like this:
Listing 50-15

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// src/Acme/DemoBundle/Form/Type/SportMeetupType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\Form\FormEvent; use Symfony\Component\Form\FormEvents; // ... class SportMeetupType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('sport', 'entity', array(...)) ; $builder->addEventListener( FormEvents::PRE_SET_DATA, function(FormEvent $event) { $form = $event->getForm();

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 182

22 23 24 25 26 27 28 29 30 31 }

// this would be your entity, i.e. SportMeetup $data = $event->getData();

$positions = $data->getSport()->getAvailablePositions(); $form->add('position', 'entity', array('choices' => $positions)); } ); }

When you're building this form to display to the user for the first time, then this example works perfectly. However, things get more difficult when you handle the form submission. This is because the PRE_SET_DATA event tells us the data that you're starting with (e.g. an empty SportMeetup object), not the submitted data. On a form, we can usually listen to the following events: PRE_SET_DATA POST_SET_DATA PRE_SUBMIT SUBMIT POST_SUBMIT
New in version 2.3: The events PRE_SUBMIT, SUBMIT and POST_SUBMIT were added in Symfony 2.3. Before, they were named PRE_BIND, BIND and POST_BIND.

New in version 2.2.6: The behavior of the POST_SUBMIT event changed slightly in 2.2.6, which the below example uses.

The key is to add a POST_SUBMIT listener to the field that your new field depends on. If you add a POST_SUBMIT listener to a form child (e.g. sport), and add new children to the parent form, the Form component will detect the new field automatically and map it to the submitted client data. The type would now look like:
Listing 50-16

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/DemoBundle/Form/Type/SportMeetupType.php namespace Acme\DemoBundle\Form\Type; // ... use Acme\DemoBundle\Entity\Sport; use Symfony\Component\Form\FormInterface;

class SportMeetupType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('sport', 'entity', array(...)) ; $formModifier = function(FormInterface $form, Sport $sport) { $positions = $sport->getAvailablePositions();

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 183

18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 }

$form->add('position', 'entity', array('choices' => $positions)); }; $builder->addEventListener( FormEvents::PRE_SET_DATA, function(FormEvent $event) use ($formModifier) { // this would be your entity, i.e. SportMeetup $data = $event->getData(); $formModifier($event->getForm(), $data->getSport()); } ); $builder->get('sport')->addEventListener( FormEvents::POST_SUBMIT, function(FormEvent $event) use ($formModifier) { // It's important here to fetch $event->getForm()->getData(), as // $event->getData() will get you the client data (that is, the ID) $sport = $event->getForm()->getData();

// since we've added the listener to the child, we'll have to pass on // the parent to the callback functions! $formModifier($event->getForm()->getParent(), $sport);
} ); }

You can see that you need to listen on these two events and have different callbacks only because in two different scenarios, the data that you can use is available in different events. Other than that, the listeners always perform exactly the same things on a given form. One piece that may still be missing is the client-side updating of your form after the sport is selected. This should be handled by making an AJAX call back to your application. In that controller, you can submit your form, but instead of processing it, simply use the submitted form to render the updated fields. The response from the AJAX call can then be used to update the view.

Suppressing Form Validation

To suppress form validation you can use the POST_SUBMIT event and prevent the ValidationListener4 from being called. The reason for needing to do this is that even if you set group_validation to false there are still some integrity checks executed. For example an uploaded file will still be checked to see if it is too large and the form will still check to see if non-existing fields were submitted. To disable all of this, use a listener:
Listing 50-17

1 2 3 4 5 6 7

use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\Form\FormEvents; public function buildForm(FormBuilderInterface $builder, array $options) { $builder->addEventListener(FormEvents::POST_SUBMIT, function($event) { $event->stopPropagation();

4. http://api.symfony.com/2.4/Symfony/Component/Form/Extension/Validator/EventListener/ValidationListener.html

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 184

8 9 10 11 }

}, 900); // Always set a higher priority than ValidationListener

// ...

By doing this, you may accidentally disable something more than just form validation, since the POST_SUBMIT event may have other listeners.

PDF brought to you by generated on February 10, 2014

Chapter 50: How to Dynamically Modify Forms Using Form Events | 185

Chapter 51

How to Embed a Collection of Forms

In this entry, you'll learn how to create a form that embeds a collection of many other forms. This could be useful, for example, if you had a Task class and you wanted to edit/create/remove many Tag objects related to that Task, right inside the same form.
In this entry, it's loosely assumed that you're using Doctrine as your database store. But if you're not using Doctrine (e.g. Propel or just a database connection), it's all very similar. There are only a few parts of this tutorial that really care about "persistence". If you are using Doctrine, you'll need to add the Doctrine metadata, including the ManyToMany association mapping definition on the Task's tags property.

First, suppose that each Task belongs to multiple Tag objects. Start by creating a simple Task class:
Listing 51-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

// src/Acme/TaskBundle/Entity/Task.php namespace Acme\TaskBundle\Entity;

use Doctrine\Common\Collections\ArrayCollection; class Task { protected $description; protected $tags; public function __construct() { $this->tags = new ArrayCollection(); } public function getDescription() { return $this->description; } public function setDescription($description)

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 186

23 24 25 26 27 28 29 30 31 }

{ $this->description = $description; } public function getTags() { return $this->tags; }

The ArrayCollection is specific to Doctrine and is basically the same as using an array (but it must be an ArrayCollection if you're using Doctrine).

Now, create a Tag class. As you saw above, a Task can have many Tag objects:
Listing 51-2

1 2 3 4 5 6 7

// src/Acme/TaskBundle/Entity/Tag.php namespace Acme\TaskBundle\Entity;

class Tag { public $name; }

The name property is public here, but it can just as easily be protected or private (but then it would need getName and setName methods).

Then, create a form class so that a Tag object can be modified by the user:
Listing 51-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

// src/Acme/TaskBundle/Form/Type/TagType.php namespace Acme\TaskBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class TagType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('name'); } public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'data_class' => 'Acme\TaskBundle\Entity\Tag', )); } public function getName() { return 'tag';

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 187

25 26 }

With this, you have enough to render a tag form by itself. But since the end goal is to allow the tags of a Task to be modified right inside the task form itself, create a form for the Task class. Notice that you embed a collection of TagType forms using the collection field type:
Listing 51-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

// src/Acme/TaskBundle/Form/Type/TaskType.php namespace Acme\TaskBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class TaskType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('description'); $builder->add('tags', 'collection', array('type' => new TagType())); } public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'data_class' => 'Acme\TaskBundle\Entity\Task', )); } public function getName() { return 'task'; } }

In your controller, you'll now initialize a new instance of TaskType:

Listing 51-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

// src/Acme/TaskBundle/Controller/TaskController.php namespace Acme\TaskBundle\Controller;

use use use use use Acme\TaskBundle\Entity\Task; Acme\TaskBundle\Entity\Tag; Acme\TaskBundle\Form\Type\TaskType; Symfony\Component\HttpFoundation\Request; Symfony\Bundle\FrameworkBundle\Controller\Controller;

class TaskController extends Controller { public function newAction(Request $request) { $task = new Task();

// dummy code - this is here just so that the Task has some tags // otherwise, this isn't an interesting example $tag1 = new Tag(); $tag1->name = 'tag1';

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 188

20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 }

$task->getTags()->add($tag1); $tag2 = new Tag(); $tag2->name = 'tag2'; $task->getTags()->add($tag2); // end dummy code $form = $this->createForm(new TaskType(), $task); $form->handleRequest($request); if ($form->isValid()) { // ... maybe do some form processing, like saving the Task and Tag objects } return $this->render('AcmeTaskBundle:Task:new.html.twig', array( 'form' => $form->createView(), )); }

The corresponding template is now able to render both the description field for the task form as well as all the TagType forms for any tags that are already related to this Task. In the above controller, I added some dummy code so that you can see this in action (since a Task has zero tags when first created).
Listing 51-6

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

{# src/Acme/TaskBundle/Resources/views/Task/new.html.twig #} {# ... #}
{{ form_start(form) }} {# render the task's only field: description #} {{ form_row(form.description) }} <h3>Tags</h3> <ul class="tags"> {# iterate over each existing tag and render its only field: name #} {% for tag in form.tags %} <li>{{ form_row(tag.name) }}</li> {% endfor %} </ul> {{ form_end(form) }}

{# ... #}

When the user submits the form, the submitted data for the tags field are used to construct an ArrayCollection of Tag objects, which is then set on the tag field of the Task instance. The tags collection is accessible naturally via $task->getTags() and can be persisted to the database or used however you need. So far, this works great, but this doesn't allow you to dynamically add new tags or delete existing tags. So, while editing existing tags will work great, your user can't actually add any new tags yet.

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 189

In this entry, you embed only one collection, but you are not limited to this. You can also embed nested collection as many level down as you like. But if you use Xdebug in your development setup, you may receive a Maximum function nesting level of '100' reached, aborting! error. This is due to the xdebug.max_nesting_level PHP setting, which defaults to 100. This directive limits recursion to 100 calls which may not be enough for rendering the form in the template if you render the whole form at once (e.g form_widget(form)). To fix this you can set this directive to a higher value (either via a php.ini file or via ini_set1, for example in app/ autoload.php) or render each form field by hand using form_row.

Allowing "new" tags with the "prototype"

Allowing the user to dynamically add new tags means that you'll need to use some JavaScript. Previously you added two tags to your form in the controller. Now let the user add as many tag forms as they need directly in the browser. This will be done through a bit of JavaScript. The first thing you need to do is to let the form collection know that it will receive an unknown number of tags. So far you've added two tags and the form type expects to receive exactly two, otherwise an error will be thrown: This form should not contain extra fields. To make this flexible, add the allow_add option to your collection field:
Listing 51-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// src/Acme/TaskBundle/Form/Type/TaskType.php // ... use Symfony\Component\Form\FormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('description'); $builder->add('tags', 'collection', array( 'type' => new TagType(), 'allow_add' => true, )); }

In addition to telling the field to accept any number of submitted objects, the allow_add also makes a "prototype" variable available to you. This "prototype" is a little "template" that contains all the HTML to be able to render any new "tag" forms. To render it, make the following change to your template:
Listing 51-8

1 <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e }}"> 2 ... 3 </ul>

If you render your whole "tags" sub-form at once (e.g. form_row(form.tags)), then the prototype is automatically available on the outer div as the data-prototype attribute, similar to what you see above.

1. http://php.net/manual/en/function.ini-set.php

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 190

The form.tags.vars.prototype is a form element that looks and feels just like the individual form_widget(tag) elements inside your for loop. This means that you can call form_widget, form_row or form_label on it. You could even choose to render only one of its fields (e.g. the name field):
Listing 51-9

1 {{ form_widget(form.tags.vars.prototype.name)|e }}

On the rendered page, the result will look something like this:
Listing 51-10

1 <ul class="tags" data-prototype="&lt;div&gt;&lt;label class=&quot; required&quot;&gt;__name__&lt;/label&gt;&lt;div id=&quot;task_tags___name__&quot;&gt;&lt;div&gt;&lt;label for=&quot;task_tags___name___name&quot; class=&quot; required&quot;&gt;Name&lt;/ label&gt;&lt;input type=&quot;text&quot; id=&quot;task_tags___name___name&quot; name=&quot;task[tags][__name__][name]&quot; required=&quot;required&quot; maxlength=&quot;255&quot; /&gt;&lt;/div&gt;&lt;/div&gt;&lt;/div&gt;">

The goal of this section will be to use JavaScript to read this attribute and dynamically add new tag forms when the user clicks a "Add a tag" link. To make things simple, this example uses jQuery and assumes you have it included somewhere on your page. Add a script tag somewhere on your page so you can start writing some JavaScript. First, add a link to the bottom of the "tags" list via JavaScript. Second, bind to the "click" event of that link so you can add a new tag form (addTagForm will be show next):
Listing 51-11

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

var $collectionHolder;

// setup an "add a tag" link var $addTagLink = $('<a href="#" class="add_tag_link">Add a tag</a>'); var $newLinkLi = $('<li></li>').append($addTagLink);
jQuery(document).ready(function() { // Get the ul that holds the collection of tags $collectionHolder = $('ul.tags');

// add the "add a tag" anchor and li to the tags ul $collectionHolder.append($newLinkLi); // count the current form inputs we have (e.g. 2), use that as the new // index when inserting a new item (e.g. 2) $collectionHolder.data('index', $collectionHolder.find(':input').length);
$addTagLink.on('click', function(e) { // prevent the link from creating a "#" on the URL e.preventDefault();

// add a new tag form (see next code block) addTagForm($collectionHolder, $newLinkLi);
}); });

The addTagForm function's job will be to use the data-prototype attribute to dynamically add a new form when this link is clicked. The data-prototype HTML contains the tag text input element with a name of task[tags][__name__][name] and id of task_tags___name___name. The __name__ is a little "placeholder", which you'll replace with a unique, incrementing number (e.g. task[tags][3][name]).

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 191

The actual code needed to make this all work can vary quite a bit, but here's one example:
Listing 51-12

1 function addTagForm($collectionHolder, $newLinkLi) { 2 // Get the data-prototype explained earlier 3 var prototype = $collectionHolder.data('prototype'); 4 5 // get the new index 6 var index = $collectionHolder.data('index'); 7 8 // Replace '__name__' in the prototype's HTML to 9 // instead be a number based on how many items we have 10 var newForm = prototype.replace(/__name__/g, index); 11 12 // increase the index with one for the next item 13 $collectionHolder.data('index', index + 1); 14 15 // Display the form in the page in an li, before the "Add a tag" link li 16 var $newFormLi = $('<li></li>').append(newForm); 17 $newLinkLi.before($newFormLi); 18 }

It is better to separate your JavaScript in real JavaScript files than to write it inside the HTML as is done here.

Now, each time a user clicks the Add a tag link, a new sub form will appear on the page. When the form is submitted, any new tag forms will be converted into new Tag objects and added to the tags property of the Task object. To make handling these new tags easier, add an "adder" and a "remover" method for the tags in the Task class:
Listing 51-13

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

// src/Acme/TaskBundle/Entity/Task.php namespace Acme\TaskBundle\Entity; // ... class Task { // ...

public function addTag(Tag $tag) { $this->tags->add($tag); } public function removeTag(Tag $tag) { // ... } }

Next, add a by_reference option to the tags field and set it to false:
Listing 51-14

1 // src/Acme/TaskBundle/Form/Type/TaskType.php 2 3 // ... 4 public function buildForm(FormBuilderInterface $builder, array $options)

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 192

5 { 6 7 8 9 10 11 12 }

// ...
$builder->add('tags', 'collection', array( // ... 'by_reference' => false, ));

With these two changes, when the form is submitted, each new Tag object is added to the Task class by calling the addTag method. Before this change, they were added internally by the form by calling $task>getTags()->add($tag). That was just fine, but forcing the use of the "adder" method makes handling these new Tag objects easier (especially if you're using Doctrine, which we talk about next!).
If no addTag and removeTag method is found, the form will still use setTag even if by_reference is false. You'll learn more about the removeTag method later in this article.

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 193

Doctrine: Cascading Relations and saving the "Inverse" side

To save the new tags with Doctrine, you need to consider a couple more things. First, unless you iterate over all of the new Tag objects and call $em->persist($tag) on each, you'll receive an error from Doctrine: A new entity was found through the relationship Acme\TaskBundle\Entity\Task#tags that was not configured to cascade persist operations for entity... To fix this, you may choose to "cascade" the persist operation automatically from the Task object to any related tags. To do this, add the cascade option to your ManyToMany metadata:
Listing 51-15

1 2 3 4 5 6 7 8

// src/Acme/TaskBundle/Entity/Task.php // ... /** * @ORM\ManyToMany(targetEntity="Tag", cascade={"persist"}) */ protected $tags;

A second potential issue deals with the Owning Side and Inverse Side2 of Doctrine relationships. In this example, if the "owning" side of the relationship is "Task", then persistence will work fine as the tags are properly added to the Task. However, if the owning side is on "Tag", then you'll need to do a little bit more work to ensure that the correct side of the relationship is modified. The trick is to make sure that the single "Task" is set on each "Tag". One easy way to do this is to add some extra logic to addTag(), which is called by the form type since by_reference is set to false:
Listing 51-16

1 2 3 4 5 6 7 8 9

// src/Acme/TaskBundle/Entity/Task.php // ... public function addTag(Tag $tag) { $tag->addTask($this);

$this->tags->add($tag); }

Inside Tag, just make sure you have an addTask method:

Listing 51-17

1 2 3 4 5 6 7 8 9

// src/Acme/TaskBundle/Entity/Tag.php // ... public function addTask(Task $task) { if (!$this->tasks->contains($task)) { $this->tasks->add($task); } }

If you have a one-to-many relationship, then the workaround is similar, except that you can simply call setTask from inside addTag.

2. http://docs.doctrine-project.org/en/latest/reference/unitofwork-associations.html

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 194

Allowing tags to be removed

The next step is to allow the deletion of a particular item in the collection. The solution is similar to allowing tags to be added. Start by adding the allow_delete option in the form Type:
Listing 51-18

1 2 3 4 5 6 7 8 9 10 11 12

// src/Acme/TaskBundle/Form/Type/TaskType.php // ... public function buildForm(FormBuilderInterface $builder, array $options) { // ...

$builder->add('tags', 'collection', array( // ... 'allow_delete' => true, )); }

Now, you need to put some code into the removeTag method of Task:
Listing 51-19

1 2 3 4 5 6 7 8 9 10 11 12

// src/Acme/TaskBundle/Entity/Task.php // ... class Task { // ...

public function removeTag(Tag $tag) { $this->tags->removeElement($tag); } }

Templates Modifications
The allow_delete option has one consequence: if an item of a collection isn't sent on submission, the related data is removed from the collection on the server. The solution is thus to remove the form element from the DOM. First, add a "delete this tag" link to each tag form:
Listing 51-20

1 jQuery(document).ready(function() { 2 // Get the ul that holds the collection of tags 3 $collectionHolder = $('ul.tags'); 4 5 // add a delete link to all of the existing tag form li elements 6 $collectionHolder.find('li').each(function() { 7 addTagFormDeleteLink($(this)); 8 }); 9 10 // ... the rest of the block from above 11 }); 12 13 function addTagForm() { 14 // ...

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 195

15 16 17 18 }

// add a delete link to the new form addTagFormDeleteLink($newFormLi);

The addTagFormDeleteLink function will look something like this:

Listing 51-21

1 function addTagFormDeleteLink($tagFormLi) { 2 var $removeFormA = $('<a href="#">delete this tag</a>'); 3 $tagFormLi.append($removeFormA); 4 5 $removeFormA.on('click', function(e) { 6 // prevent the link from creating a "#" on the URL 7 e.preventDefault(); 8 9 // remove the li for the tag form 10 $tagFormLi.remove(); 11 }); 12 }

When a tag form is removed from the DOM and submitted, the removed Tag object will not be included in the collection passed to setTags. Depending on your persistence layer, this may or may not be enough to actually remove the relationship between the removed Tag and Task object.

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 196

Doctrine: Ensuring the database persistence

When removing objects in this way, you may need to do a little bit more work to ensure that the relationship between the Task and the removed Tag is properly removed. In Doctrine, you have two side of the relationship: the owning side and the inverse side. Normally in this case you'll have a many-to-many relation and the deleted tags will disappear and persist correctly (adding new tags also works effortlessly). But if you have an one-to-many relation or a many-to-many with a mappedBy on the Task entity (meaning Task is the "inverse" side), you'll need to do more work for the removed tags to persist correctly. In this case, you can modify the controller to remove the relationship on the removed tag. This assumes that you have some editAction which is handling the "update" of your Task:
Listing 51-22

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45

// src/Acme/TaskBundle/Controller/TaskController.php
use Doctrine\Common\Collections\ArrayCollection;

// ... public function editAction($id, Request $request) { $em = $this->getDoctrine()->getManager(); $task = $em->getRepository('AcmeTaskBundle:Task')->find($id);
if (!$task) { throw $this->createNotFoundException('No task found for is '.$id); } $originalTags = new ArrayCollection();

// Create an ArrayCollection of the current Tag objects in the database foreach ($task->getTags() as $tag) { $originalTags->add($tag); }
$editForm = $this->createForm(new TaskType(), $task); $editForm->handleRequest($request); if ($editForm->isValid()) {

// remove the relationship between the tag and the Task foreach ($originalTags as $tag) { if (false === $task->getTags()->contains($tag)) { // remove the Task from the Tag $tag->getTasks()->removeElement($task); // if it was a many-to-one relationship, remove the relationship like this // $tag->setTask(null);
$em->persist($tag);

// if you wanted to delete the Tag entirely, you can also do that // $em->remove($tag);
} } $em->persist($task);

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 197

46 47 48 49 50 51 52 }

$em->flush();

// redirect back to some edit page return $this->redirect($this->generateUrl('task_edit', array('id' => $id)));
}

// render some form template

As you can see, adding and removing the elements correctly can be tricky. Unless you have a manyto-many relationship where Task is the "owning" side, you'll need to do extra work to make sure that the relationship is properly updated (whether you're adding new tags or removing existing tags) on each Tag object itself.

PDF brought to you by generated on February 10, 2014

Chapter 51: How to Embed a Collection of Forms | 198

Chapter 52

How to Create a Custom Form Field Type

Symfony comes with a bunch of core field types available for building forms. However there are situations where you may want to create a custom form field type for a specific purpose. This recipe assumes you need a field definition that holds a person's gender, based on the existing choice field. This section explains how the field is defined, how you can customize its layout and finally, how you can register it for use in your application.

Defining the Field Type

In order to create the custom field type, first you have to create the class representing the field. In this situation the class holding the field type will be called GenderType and the file will be stored in the default location for form fields, which is <BundleName>\Form\Type. Make sure the field extends AbstractType1:
Listing 52-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

// src/Acme/DemoBundle/Form/Type/GenderType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class GenderType extends AbstractType { public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'choices' => array( 'm' => 'Male', 'f' => 'Female', ) )); } public function getParent() {

1. http://api.symfony.com/2.4/Symfony/Component/Form/AbstractType.html

PDF brought to you by generated on February 10, 2014

Chapter 52: How to Create a Custom Form Field Type | 199

21 22 23 24 25 26 27 28 }

return 'choice'; } public function getName() { return 'gender'; }

The location of this file is not important - the Form\Type directory is just a convention.

Here, the return value of the getParent function indicates that you're extending the choice field type. This means that, by default, you inherit all of the logic and rendering of that field type. To see some of the logic, check out the ChoiceType2 class. There are three methods that are particularly important: buildForm() - Each field type has a buildForm method, which is where you configure and build any field(s). Notice that this is the same method you use to setup your forms, and it works the same here. buildView() - This method is used to set any extra variables you'll need when rendering your field in a template. For example, in ChoiceType3, a multiple variable is set and used in the template to set (or not set) the multiple attribute on the select field. See Creating a Template for the Field for more details. setDefaultOptions() - This defines options for your form type that can be used in buildForm() and buildView(). There are a lot of options common to all fields (see form Field Type), but you can create any others that you need here.
If you're creating a field that consists of many fields, then be sure to set your "parent" type as form or something that extends form. Also, if you need to modify the "view" of any of your child types from your parent type, use the finishView() method.

The getName() method returns an identifier which should be unique in your application. This is used in various places, such as when customizing how your form type will be rendered. The goal of this field was to extend the choice type to enable selection of a gender. This is achieved by fixing the choices to a list of possible genders.

Creating a Template for the Field

Each field type is rendered by a template fragment, which is determined in part by the value of your getName() method. For more information, see What are Form Themes?. In this case, since the parent field is choice, you don't need to do any work as the custom field type will automatically be rendered like a choice type. But for the sake of this example, suppose that when your field is "expanded" (i.e. radio buttons or checkboxes, instead of a select field), you want to always render it in a ul element. In your form theme template (see above link for details), create a gender_widget block to handle this:
Listing 52-2

2. https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php 3. https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php

PDF brought to you by generated on February 10, 2014

Chapter 52: How to Create a Custom Form Field Type | 200

1 {# src/Acme/DemoBundle/Resources/views/Form/fields.html.twig #} 2 {% block gender_widget %} 3 {% spaceless %} 4 {% if expanded %} 5 <ul {{ block('widget_container_attributes') }}> 6 {% for child in form %} 7 <li> 8 {{ form_widget(child) }} 9 {{ form_label(child) }} 10 </li> 11 {% endfor %} 12 </ul> 13 {% else %} 14 {# just let the choice widget render the select tag #} 15 {{ block('choice_widget') }} 16 {% endif %} 17 {% endspaceless %} 18 {% endblock %}

Make sure the correct widget prefix is used. In this example the name should be gender_widget, according to the value returned by getName. Further, the main config file should point to the custom form template so that it's used when rendering all forms.
Listing 52-3

1 # app/config/config.yml 2 twig: 3 form: 4 resources: 5 - 'AcmeDemoBundle:Form:fields.html.twig'

Using the Field Type

You can now use your custom field type immediately, simply by creating a new instance of the type in one of your forms:
Listing 52-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

// src/Acme/DemoBundle/Form/Type/AuthorType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class AuthorType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('gender_code', new GenderType(), array( 'empty_value' => 'Choose a gender', )); } }

But this only works because the GenderType() is very simple. What if the gender codes were stored in configuration or in a database? The next section explains how more complex field types solve this problem.
PDF brought to you by generated on February 10, 2014 Chapter 52: How to Create a Custom Form Field Type | 201

Creating your Field Type as a Service

So far, this entry has assumed that you have a very simple custom field type. But if you need access to configuration, a database connection, or some other service, then you'll want to register your custom type as a service. For example, suppose that you're storing the gender parameters in configuration:
Listing 52-5

1 # app/config/config.yml 2 parameters: 3 genders: 4 m: Male 5 f: Female

To use the parameter, define your custom field type as a service, injecting the genders parameter value as the first argument to its to-be-created __construct function:
Listing 52-6

1 # src/Acme/DemoBundle/Resources/config/services.yml 2 services: 3 acme_demo.form.type.gender: 4 class: Acme\DemoBundle\Form\Type\GenderType 5 arguments: 6 - "%genders%" 7 tags: 8 - { name: form.type, alias: gender }

Make sure the services file is being imported. See Importing Configuration with imports for details.

Be sure that the alias attribute of the tag corresponds with the value returned by the getName method defined earlier. You'll see the importance of this in a moment when you use the custom field type. But first, add a __construct method to GenderType, which receives the gender configuration:
Listing 52-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// src/Acme/DemoBundle/Form/Type/GenderType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\OptionsResolver\OptionsResolverInterface;

// ... // ... class GenderType extends AbstractType { private $genderChoices;

public function __construct(array $genderChoices) { $this->genderChoices = $genderChoices; } public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'choices' => $this->genderChoices, )); }

PDF brought to you by generated on February 10, 2014

Chapter 52: How to Create a Custom Form Field Type | 202

24 25 26 }

// ...

Great! The GenderType is now fueled by the configuration parameters and registered as a service. Additionally, because you used the form.type alias in its configuration, using the field is now much easier:
Listing 52-8

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

// src/Acme/DemoBundle/Form/Type/AuthorType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\FormBuilderInterface;

// ...
class AuthorType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('gender_code', 'gender', array( 'empty_value' => 'Choose a gender', )); } }

Notice that instead of instantiating a new instance, you can just refer to it by the alias used in your service configuration, gender. Have fun!

PDF brought to you by generated on February 10, 2014

Chapter 52: How to Create a Custom Form Field Type | 203

Chapter 53

How to Create a Form Type Extension

Custom form field types are great when you need field types with a specific purpose, such as a gender selector, or a VAT number input. But sometimes, you don't really need to add new field types - you want to add features on top of existing types. This is where form type extensions come in. Form type extensions have 2 main use-cases: 1. You want to add a generic feature to several types (such as adding a "help" text to every field type); 2. You want to add a specific feature to a single type (such as adding a "download" feature to the "file" field type). In both those cases, it might be possible to achieve your goal with custom form rendering, or custom form field types. But using form type extensions can be cleaner (by limiting the amount of business logic in templates) and more flexible (you can add several type extensions to a single form type). Form type extensions can achieve most of what custom field types can do, but instead of being field types of their own, they plug into existing types. Imagine that you manage a Media entity, and that each media is associated to a file. Your Media form uses a file type, but when editing the entity, you would like to see its image automatically rendered next to the file input. You could of course do this by customizing how this field is rendered in a template. But field type extensions allow you to do this in a nice DRY fashion.

Defining the Form Type Extension

Your first task will be to create the form type extension class (called ImageTypeExtension in this article). By standard, form extensions usually live in the Form\Extension directory of one of your bundles. When creating a form type extension, you can either implement the FormTypeExtensionInterface1 interface or extend the AbstractTypeExtension2 class. In most cases, it's easier to extend the abstract class:
1. http://api.symfony.com/2.4/Symfony/Component/Form/FormTypeExtensionInterface.html 2. http://api.symfony.com/2.4/Symfony/Component/Form/AbstractTypeExtension.html

PDF brought to you by generated on February 10, 2014

Chapter 53: How to Create a Form Type Extension | 204

Listing 53-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/DemoBundle/Form/Extension/ImageTypeExtension.php namespace Acme\DemoBundle\Form\Extension;

use Symfony\Component\Form\AbstractTypeExtension; class ImageTypeExtension extends AbstractTypeExtension { /** * Returns the name of the type being extended. * * @return string The name of the type being extended */ public function getExtendedType() { return 'file'; } }

The only method you must implement is the getExtendedType function. It is used to indicate the name of the form type that will be extended by your extension.
The value you return in the getExtendedType method corresponds to the value returned by the getName method in the form type class you wish to extend.

In addition to the getExtendedType function, you will probably want to override one of the following methods: buildForm() buildView() setDefaultOptions() finishView()

For more information on what those methods do, you can refer to the Creating Custom Field Types cookbook article.

Registering your Form Type Extension as a Service

The next step is to make Symfony aware of your extension. All you need to do is to declare it as a service by using the form.type_extension tag:
Listing 53-2

1 services: 2 acme_demo_bundle.image_type_extension: 3 class: Acme\DemoBundle\Form\Extension\ImageTypeExtension 4 tags: 5 - { name: form.type_extension, alias: file }

The alias key of the tag is the type of field that this extension should be applied to. In your case, as you want to extend the file field type, you will use file as an alias.

PDF brought to you by generated on February 10, 2014

Chapter 53: How to Create a Form Type Extension | 205

Adding the extension Business Logic

The goal of your extension is to display nice images next to file inputs (when the underlying model contains images). For that purpose, suppose that you use an approach similar to the one described in How to handle File Uploads with Doctrine: you have a Media model with a file property (corresponding to the file field in the form) and a path property (corresponding to the image path in the database):
Listing 53-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

// src/Acme/DemoBundle/Entity/Media.php namespace Acme\DemoBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert; class Media { // ...

/** * @var string The path - typically stored in the database */ private $path; /** * @var \Symfony\Component\HttpFoundation\File\UploadedFile * @Assert\File(maxSize="2M") */ public $file; // ... /** * Get the image URL * * @return null|string */ public function getWebPath() { // ... $webPath being the full image URL, to be used in templates
return $webPath; } }

Your form type extension class will need to do two things in order to extend the file form type: 1. Override the setDefaultOptions method in order to add an image_path option; 2. Override the buildForm and buildView methods in order to pass the image URL to the view. The logic is the following: when adding a form field of type file, you will be able to specify a new option: image_path. This option will tell the file field how to get the actual image URL in order to display it in the view:
Listing 53-4

1 2 3 4 5 6 7 8

// src/Acme/DemoBundle/Form/Extension/ImageTypeExtension.php namespace Acme\DemoBundle\Form\Extension;

use use use use use Symfony\Component\Form\AbstractTypeExtension; Symfony\Component\Form\FormView; Symfony\Component\Form\FormInterface; Symfony\Component\PropertyAccess\PropertyAccess; Symfony\Component\OptionsResolver\OptionsResolverInterface;

PDF brought to you by generated on February 10, 2014

Chapter 53: How to Create a Form Type Extension | 206

9 10 class ImageTypeExtension extends AbstractTypeExtension 11 { 12 /** 13 * Returns the name of the type being extended. 14 * 15 * @return string The name of the type being extended 16 */ 17 public function getExtendedType() 18 { 19 return 'file'; 20 } 21 22 /** 23 * Add the image_path option 24 * 25 * @param OptionsResolverInterface $resolver 26 */ 27 public function setDefaultOptions(OptionsResolverInterface $resolver) 28 { 29 $resolver->setOptional(array('image_path')); 30 } 31 32 /** 33 * Pass the image URL to the view 34 * 35 * @param FormView $view 36 * @param FormInterface $form 37 * @param array $options 38 */ 39 public function buildView(FormView $view, FormInterface $form, array $options) 40 { 41 if (array_key_exists('image_path', $options)) { 42 $parentData = $form->getParent()->getData(); 43 44 if (null !== $parentData) { 45 $accessor = PropertyAccess::createPropertyAccessor(); 46 $imageUrl = $accessor->getValue($parentData, $options['image_path']); 47 } else { 48 $imageUrl = null; 49 } 50 51 // set an "image_url" variable that will be available when rendering this field 52 $view->vars['image_url'] = $imageUrl; 53 } 54 } 55 56 }

Override the File Widget Template Fragment

Each field type is rendered by a template fragment. Those template fragments can be overridden in order to customize form rendering. For more information, you can refer to the What are Form Themes? article. In your extension class, you have added a new variable (image_url), but you still need to take advantage of this new variable in your templates. Specifically, you need to override the file_widget block:

PDF brought to you by generated on February 10, 2014

Chapter 53: How to Create a Form Type Extension | 207

Listing 53-5

1 2 3 4 5 6 7 8 9 10 11 12 13

{# src/Acme/DemoBundle/Resources/views/Form/fields.html.twig #} {% extends 'form_div_layout.html.twig' %}

{% block file_widget %} {% spaceless %} {{ block('form_widget') }} {% if image_url is not null %} <img src="{{ asset(image_url) }}"/> {% endif %} {% endspaceless %} {% endblock %}

You will need to change your config file or explicitly specify how you want your form to be themed in order for Symfony to use your overridden block. See What are Form Themes? for more information.

Using the Form Type Extension

From now on, when adding a field of type file in your form, you can specify an image_path option that will be used to display an image next to the file field. For example:
Listing 53-6

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

// src/Acme/DemoBundle/Form/Type/MediaType.php namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MediaType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'text') ->add('file', 'file', array('image_path' => 'webPath')); } public function getName() { return 'media'; } }

When displaying the form, if the underlying model has already been associated with an image, you will see it displayed next to the file input.

PDF brought to you by generated on February 10, 2014

Chapter 53: How to Create a Form Type Extension | 208

Chapter 54

How to Reduce Code Duplication with "inherit_data"

New in version 2.3: This inherit_data option was known as virtual before Symfony 2.3.

The inherit_data form field option can be very useful when you have some duplicated fields in different entities. For example, imagine you have two entities, a Company and a Customer:
Listing 54-1

1 2 3 4 5 6 7 8 9 10 11 12 13

// src/Acme/HelloBundle/Entity/Company.php namespace Acme\HelloBundle\Entity;

class Company { private $name; private $website; private private private private } $address; $zipcode; $city; $country;

Listing 54-2

1 2 3 4 5 6 7 8

// src/Acme/HelloBundle/Entity/Customer.php namespace Acme\HelloBundle\Entity;

class Customer { private $firstName; private $lastName;

PDF brought to you by generated on February 10, 2014

Chapter 54: How to Reduce Code Duplication with "inherit_data" | 209

9 10 11 12 13 }

private private private private

$address; $zipcode; $city; $country;

As you can see, each entity shares a few of the same fields: address, zipcode, city, country. Start with building two forms for these entities, CompanyType and CustomerType:
Listing 54-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

// src/Acme/HelloBundle/Form/Type/CompanyType.php namespace Acme\HelloBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class CompanyType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'text') ->add('website', 'text'); } }

Listing 54-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

// src/Acme/HelloBundle/Form/Type/CustomerType.php namespace Acme\HelloBundle\Form\Type;

use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\Form\AbstractType; class CustomerType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('firstName', 'text') ->add('lastName', 'text'); } }

Instead of including the duplicated fields address, zipcode, city and country in both of these forms, create a third form called LocationType for that:
Listing 54-5

1 2 3 4 5 6 7 8 9 10 11 12

// src/Acme/HelloBundle/Form/Type/LocationType.php namespace Acme\HelloBundle\Form\Type;

use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class LocationType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder

PDF brought to you by generated on February 10, 2014

Chapter 54: How to Reduce Code Duplication with "inherit_data" | 210

13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 }

->add('address', 'textarea') ->add('zipcode', 'text') ->add('city', 'text') ->add('country', 'text'); } public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'inherit_data' => true )); } public function getName() { return 'location'; }

The location form has an interesting option set, namely inherit_data. This option lets the form inherit its data from its parent form. If embedded in the company form, the fields of the location form will access the properties of the Company instance. If embedded in the customer form, the fields will access the properties of the Customer instance instead. Easy, eh?
Instead of setting the inherit_data option inside LocationType, you can also (just like with any option) pass it in the third argument of $builder->add().

Finally, make this work by adding the location form to your two original forms:
Listing 54-6

1 2 3 4 5 6 7 8 9

// src/Acme/HelloBundle/Form/Type/CompanyType.php public function buildForm(FormBuilderInterface $builder, array $options) { // ...

$builder->add('foo', new LocationType(), array( 'data_class' => 'Acme\HelloBundle\Entity\Company' )); }

Listing 54-7

1 2 3 4 5 6 7 8 9

// src/Acme/HelloBundle/Form/Type/CustomerType.php public function buildForm(FormBuilderInterface $builder, array $options) { // ...

$builder->add('bar', new LocationType(), array( 'data_class' => 'Acme\HelloBundle\Entity\Customer' )); }

That's it! You have extracted duplicated field definitions to a separate location form that you can reuse wherever you need it.

PDF brought to you by generated on February 10, 2014

Chapter 54: How to Reduce Code Duplication with "inherit_data" | 211

Chapter 55

How to Unit Test your Forms

The Form component consists of 3 core objects: a form type (implementing FormTypeInterface1), the Form2 and the FormView3. The only class that is usually manipulated by programmers is the form type class which serves as a form blueprint. It is used to generate the Form and the FormView. You could test it directly by mocking its interactions with the factory but it would be complex. It is better to pass it to FormFactory like it is done in a real application. It is simple to bootstrap and you can trust the Symfony components enough to use them as a testing base. There is already a class that you can benefit from for simple FormTypes testing: TypeTestCase4. It is used to test the core types and you can use it to test your types too.
New in version 2.3: The TypeTestCase has moved to the Symfony\Component\Form\Test namespace in 2.3. Previously, the class was located in Symfony\Component\Form\Tests\Extension\Core\Type.

Depending on the way you installed your Symfony or Symfony Form component the tests may not be downloaded. Use the --prefer-source option with Composer if this is the case.

The Basics
The simplest TypeTestCase implementation looks like the following:
Listing 55-1

1 // src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php 2 namespace Acme\TestBundle\Tests\Form\Type;

1. http://api.symfony.com/2.4/Symfony/Component/Form/FormTypeInterface.html 2. http://api.symfony.com/2.4/Symfony/Component/Form/Form.html 3. http://api.symfony.com/2.4/Symfony/Component/Form/FormView.html 4. http://api.symfony.com/2.4/Symfony/Component/Form/Test/TypeTestCase.html

PDF brought to you by generated on February 10, 2014

Chapter 55: How to Unit Test your Forms | 212

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

use Acme\TestBundle\Form\Type\TestedType; use Acme\TestBundle\Model\TestObject; use Symfony\Component\Form\Test\TypeTestCase; class TestedTypeTest extends TypeTestCase { public function testSubmitValidData() { $formData = array( 'test' => 'test', 'test2' => 'test2', ); $type = new TestedType(); $form = $this->factory->create($type); $object = new TestObject(); $object->fromArray($formData);

// submit the data to the form directly $form->submit($formData);

$this->assertTrue($form->isSynchronized()); $this->assertEquals($object, $form->getData()); $view = $form->createView(); $children = $view->children; foreach (array_keys($formData) as $key) { $this->assertArrayHasKey($key, $children); } } }

So, what does it test? Here comes a detailed explanation. First you verify if the FormType compiles. This includes basic class inheritance, the buildForm function and options resolution. This should be the first test you write:
Listing 55-2

1 $type = new TestedType(); 2 $form = $this->factory->create($type);

This test checks that none of your data transformers used by the form failed. The isSynchronized()5 method is only set to false if a data transformer throws an exception:
Listing 55-3

1 $form->submit($formData); 2 $this->assertTrue($form->isSynchronized());

Don't test the validation: it is applied by a listener that is not active in the test case and it relies on validation configuration. Instead, unit test your custom constraints directly.

5. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#isSynchronized()

PDF brought to you by generated on February 10, 2014

Chapter 55: How to Unit Test your Forms | 213

Next, verify the submission and mapping of the form. The test below checks if all the fields are correctly specified:
Listing 55-4

1 $this->assertEquals($object, $form->getData());

Finally, check the creation of the FormView. You should check if all widgets you want to display are available in the children property:
Listing 55-5

1 2 3 4 5 6

$view = $form->createView(); $children = $view->children; foreach (array_keys($formData) as $key) { $this->assertArrayHasKey($key, $children); }

Adding a Type your Form depends on

Your form may depend on other types that are defined as services. It might look like this:
Listing 55-6

1 // src/Acme/TestBundle/Form/Type/TestedType.php 2 3 // ... the buildForm method 4 $builder->add('acme_test_child_type');

To create your form correctly, you need to make the type available to the form factory in your test. The easiest way is to register it manually before creating the parent form using the PreloadedExtension class:
Listing 55-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

// src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php namespace Acme\TestBundle\Tests\Form\Type;

use use use use Acme\TestBundle\Form\Type\TestedType; Acme\TestBundle\Model\TestObject; Symfony\Component\Form\Test\TypeTestCase; Symfony\Component\Form\PreloadedExtension;

class TestedTypeTest extends TypeTestCase { protected function getExtensions() { $childType = new TestChildType(); return array(new PreloadedExtension(array( $childType->getName() => $childType, ), array())); } public function testSubmitValidData() { $type = new TestedType(); $form = $this->factory->create($type);

// ... your test

} }

PDF brought to you by generated on February 10, 2014

Chapter 55: How to Unit Test your Forms | 214

Make sure the child type you add is well tested. Otherwise you may be getting errors that are not related to the form you are currently testing but to its children.

Adding custom Extensions

It often happens that you use some options that are added by form extensions. One of the cases may be the ValidatorExtension with its invalid_message option. The TypeTestCase loads only the core form extension so an "Invalid option" exception will be raised if you try to use it for testing a class that depends on other extensions. You need add those extensions to the factory object:
Listing 55-8

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

// src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php namespace Acme\TestBundle\Tests\Form\Type;

use use use use use use Acme\TestBundle\Form\Type\TestedType; Acme\TestBundle\Model\TestObject; Symfony\Component\Form\Test\TypeTestCase; Symfony\Component\Form\Forms; Symfony\Component\Form\FormBuilder; Symfony\Component\Form\Extension\Validator\Type\FormTypeValidatorExtension;

class TestedTypeTest extends TypeTestCase { protected function setUp() { parent::setUp(); $this->factory = Forms::createFormFactoryBuilder() ->addExtensions($this->getExtensions()) ->addTypeExtension( new FormTypeValidatorExtension( $this->getMock('Symfony\Component\Validator\ValidatorInterface') ) ) ->addTypeGuesser( $this->getMockBuilder( 'Symfony\Component\Form\Extension\Validator\ValidatorTypeGuesser' ) ->disableOriginalConstructor() ->getMock() ) ->getFormFactory(); $this->dispatcher = $this->getMock('Symfony\Component\EventDispatcher\EventDispatcherInterface'); $this->builder = new FormBuilder(null, null, $this->dispatcher, $this->factory); }

// ... your tests

}

Testing against different Sets of Data

If you are not familiar yet with PHPUnit's data providers6, this might be a good opportunity to use them:
PDF brought to you by generated on February 10, 2014 Chapter 55: How to Unit Test your Forms | 215

Listing 55-9

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

// src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php namespace Acme\TestBundle\Tests\Form\Type;

use Acme\TestBundle\Form\Type\TestedType; use Acme\TestBundle\Model\TestObject; use Symfony\Component\Form\Test\TypeTestCase; class TestedTypeTest extends TypeTestCase {

/** * @dataProvider getValidTestData */ public function testForm($data) { // ... your test }

public function getValidTestData() { return array( array( 'data' => array( 'test' => 'test', 'test2' => 'test2', ), ), array( 'data' => array(), ), array( 'data' => array( 'test' => null, 'test2' => null, ), ), ); } }

The code above will run your test three times with 3 different sets of data. This allows for decoupling the test fixtures from the tests and easily testing against multiple sets of data. You can also pass another argument, such as a boolean if the form has to be synchronized with the given set of data or not etc.

6. http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers

PDF brought to you by generated on February 10, 2014

Chapter 55: How to Unit Test your Forms | 216

Chapter 56

How to configure Empty Data for a Form Class

The empty_data option allows you to specify an empty data set for your form class. This empty data set would be used if you submit your form, but haven't called setData() on your form or passed in data when you created your form. For example:
Listing 56-1

1 public function indexAction() 2 { 3 $blog = ...; 4 5 // $blog is passed in as the data, so the empty_data option is not needed 6 $form = $this->createForm(new BlogType(), $blog); 7 8 // no data is passed in, so empty_data is used to get the "starting data" 9 $form = $this->createForm(new BlogType()); 10 }

By default, empty_data is set to null. Or, if you have specified a data_class option for your form class, it will default to a new instance of that class. That instance will be created by calling the constructor with no arguments. If you want to override this default behavior, there are two ways to do this.

Option 1: Instantiate a new Class

One reason you might use this option is if you want to use a constructor that takes arguments. Remember, the default data_class option calls that constructor with no arguments:
Listing 56-2

1 2 3 4 5 6 7

// src/Acme/DemoBundle/Form/Type/BlogType.php // ... use Symfony\Component\Form\AbstractType; use Acme\DemoBundle\Entity\Blog; use Symfony\Component\OptionsResolver\OptionsResolverInterface;

PDF brought to you by generated on February 10, 2014

Chapter 56: How to configure Empty Data for a Form Class | 217

8 class BlogType extends AbstractType 9 { 10 private $someDependency; 11 12 public function __construct($someDependency) 13 { 14 $this->someDependency = $someDependency; 15 } 16 // ... 17 18 public function setDefaultOptions(OptionsResolverInterface $resolver) 19 { 20 $resolver->setDefaults(array( 21 'empty_data' => new Blog($this->someDependency), 22 )); 23 } 24 }

You can instantiate your class however you want. In this example, we pass some dependency into the BlogType when we instantiate it, then use that to instantiate the Blog class. The point is, you can set empty_data to the exact "new" object that you want to use.

Option 2: Provide a Closure

Using a closure is the preferred method, since it will only create the object if it is needed. The closure must accept a FormInterface instance as the first argument:
Listing 56-3

1 2 3 4 5 6 7 8 9 10 11 12

use Symfony\Component\OptionsResolver\OptionsResolverInterface; use Symfony\Component\Form\FormInterface; // ... public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'empty_data' => function (FormInterface $form) { return new Blog($form->get('title')->getData()); }, )); }

PDF brought to you by generated on February 10, 2014

Chapter 56: How to configure Empty Data for a Form Class | 218

Chapter 57

How to use the submit() Function to handle Form Submissions

New in version 2.3: The handleRequest()1 method was added in Symfony 2.3.

With the handleRequest() method, it is really easy to handle form submissions:

Listing 57-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

use Symfony\Component\HttpFoundation\Request; // ... public function newAction(Request $request) { $form = $this->createFormBuilder() // ... ->getForm(); $form->handleRequest($request); if ($form->isValid()) { // perform some action... return $this->redirect($this->generateUrl('task_success')); } return $this->render('AcmeTaskBundle:Default:new.html.twig', array( 'form' => $form->createView(), )); }

1. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#handleRequest()

PDF brought to you by generated on February 10, 2014

Chapter 57: How to use the submit() Function to handle Form Submissions | 219

To see more about this method, read Handling Form Submissions.

Calling Form::submit() manually

New in version 2.3: Before Symfony 2.3, the submit() method was known as bind().

In some cases, you want better control over when exactly your form is submitted and what data is passed to it. Instead of using the handleRequest()2 method, pass the submitted data directly to submit()3:
Listing 57-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

use Symfony\Component\HttpFoundation\Request; // ... public function newAction(Request $request) { $form = $this->createFormBuilder() // ... ->getForm(); if ($request->isMethod('POST')) { $form->submit($request->request->get($form->getName())); if ($form->isValid()) { // perform some action... return $this->redirect($this->generateUrl('task_success')); } } return $this->render('AcmeTaskBundle:Default:new.html.twig', array( 'form' => $form->createView(), )); }

Forms consisting of nested fields expect an array in submit()4. You can also submit individual fields by calling submit()5 directly on the field:
Listing 57-3

1 $form->get('firstName')->submit('Fabien');

2. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#handleRequest() 3. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#submit() 4. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#submit() 5. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#submit()

PDF brought to you by generated on February 10, 2014

Chapter 57: How to use the submit() Function to handle Form Submissions | 220

Passing a Request to Form::submit() (deprecated)

New in version 2.3: Before Symfony 2.3, the submit method was known as bind.

Before Symfony 2.3, the submit()6 method accepted a Request7 object as a convenient shortcut to the previous example:
Listing 57-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

use Symfony\Component\HttpFoundation\Request; // ... public function newAction(Request $request) { $form = $this->createFormBuilder() // ... ->getForm(); if ($request->isMethod('POST')) { $form->submit($request); if ($form->isValid()) { // perform some action... return $this->redirect($this->generateUrl('task_success')); } } return $this->render('AcmeTaskBundle:Default:new.html.twig', array( 'form' => $form->createView(), )); }

Passing the Request8 directly to submit()9 still works, but is deprecated and will be removed in Symfony 3.0. You should use the method handleRequest()10 instead.

6. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#submit() 7. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/Request.html 8. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/Request.html 9. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#submit() 10. http://api.symfony.com/2.4/Symfony/Component/Form/FormInterface.html#handleRequest()

PDF brought to you by generated on February 10, 2014

Chapter 57: How to use the submit() Function to handle Form Submissions | 221

Chapter 58

How to use the Virtual Form Field Option

As of Symfony 2.3, the virtual option is renamed to inherit_data. You can read everything about the new option in "How to Reduce Code Duplication with "inherit_data"".

PDF brought to you by generated on February 10, 2014

Chapter 58: How to use the Virtual Form Field Option | 222

Chapter 59

How to use Monolog to write Logs

Monolog1 is a logging library for PHP 5.3 used by Symfony2. It is inspired by the Python LogBook library.

Usage
To log a message simply get the logger service from the container in your controller:
Listing 59-1

1 public function indexAction() 2 { 3 $logger = $this->get('logger'); 4 $logger->info('I just got the logger'); 5 $logger->error('An error occurred'); 6 7 // ... 8 }

The logger service has different methods for different logging levels. See LoggerInterface2 for details on which methods are available.

Handlers and Channels: Writing logs to different Locations

In Monolog each logger defines a logging channel, which organizes your log messages into different "categories". Then, each channel has a stack of handlers to write the logs (the handlers can be shared).
When injecting the logger in a service you can use a custom channel control which "channel" the logger will log to.

1. https://github.com/Seldaek/monolog 2. https://github.com/php-fig/log/blob/master/Psr/Log/LoggerInterface.php

PDF brought to you by generated on February 10, 2014

Chapter 59: How to use Monolog to write Logs | 223

The basic handler is the StreamHandler which writes logs in a stream (by default in the app/logs/ prod.log in the prod environment and app/logs/dev.log in the dev environment). Monolog comes also with a powerful built-in handler for the logging in prod environment: FingersCrossedHandler. It allows you to store the messages in a buffer and to log them only if a message reaches the action level (error in the configuration provided in the Standard Edition) by forwarding the messages to another handler.

Using several handlers

The logger uses a stack of handlers which are called successively. This allows you to log the messages in several ways easily.
Listing 59-2

1 # app/config/config.yml 2 monolog: 3 handlers: 4 applog: 5 type: stream 6 path: /var/log/symfony.log 7 level: error 8 main: 9 type: fingers_crossed 10 action_level: warning 11 handler: file 12 file: 13 type: stream 14 level: debug 15 syslog: 16 type: syslog 17 level: error

The above configuration defines a stack of handlers which will be called in the order where they are defined.
The handler named "file" will not be included in the stack itself as it is used as a nested handler of the fingers_crossed handler.

If you want to change the config of MonologBundle in another config file you need to redefine the whole stack. It cannot be merged because the order matters and a merge does not allow to control the order.

Changing the formatter

The handler uses a Formatter to format the record before logging it. All Monolog handlers use an instance of Monolog\Formatter\LineFormatter by default but you can replace it easily. Your formatter must implement Monolog\Formatter\FormatterInterface.
Listing 59-3

1 # app/config/config.yml 2 services: 3 my_formatter: 4 class: Monolog\Formatter\JsonFormatter 5 monolog: 6 handlers:

PDF brought to you by generated on February 10, 2014

Chapter 59: How to use Monolog to write Logs | 224

7 8 9 10

file: type: stream level: debug formatter: my_formatter

Adding some extra data in the log messages

Monolog allows to process the record before logging it to add some extra data. A processor can be applied for the whole handler stack or only for a specific handler. A processor is simply a callable receiving the record as its first argument. Processors are configured using the monolog.processor DIC tag. See the reference about it.

Adding a Session/Request Token

Sometimes it is hard to tell which entries in the log belong to which session and/or request. The following example will add a unique token for each request using a processor.
Listing 59-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

namespace Acme\MyBundle; use Symfony\Component\HttpFoundation\Session\Session; class SessionRequestProcessor { private $session; private $token; public function __construct(Session $session) { $this->session = $session; } public function processRecord(array $record) { if (null === $this->token) { try { $this->token = substr($this->session->getId(), 0, 8); } catch (\RuntimeException $e) { $this->token = '????????'; } $this->token .= '-' . substr(uniqid(), -8); } $record['extra']['token'] = $this->token; return $record; } }

Listing 59-5

1 # app/config/config.yml 2 services: 3 monolog.formatter.session_request: 4 class: Monolog\Formatter\LineFormatter 5 arguments: 6 - "[%%datetime%%] [%%extra.token%%] %%channel%%.%%level_name%%: %%message%%\n"

PDF brought to you by generated on February 10, 2014

Chapter 59: How to use Monolog to write Logs | 225

7 8 monolog.processor.session_request: 9 class: Acme\MyBundle\SessionRequestProcessor 10 arguments: ["@session"] 11 tags: 12 - { name: monolog.processor, method: processRecord } 13 14 monolog: 15 handlers: 16 main: 17 type: stream 18 path: "%kernel.logs_dir%/%kernel.environment%.log" 19 level: debug 20 formatter: monolog.formatter.session_request

If you use several handlers, you can also register the processor at the handler level instead of globally.

PDF brought to you by generated on February 10, 2014

Chapter 59: How to use Monolog to write Logs | 226

Chapter 60

How to Configure Monolog to Email Errors

Monolog1 can be configured to send an email when an error occurs with an application. The configuration for this requires a few nested handlers in order to avoid receiving too many emails. This configuration looks complicated at first but each handler is fairly straight forward when it is broken down.
Listing 60-1

1 # app/config/config_prod.yml 2 monolog: 3 handlers: 4 mail: 5 type: fingers_crossed 6 action_level: critical 7 handler: buffered 8 buffered: 9 type: buffer 10 handler: swift 11 swift: 12 type: swift_mailer 13 from_email: [email protected] 14 to_email: [email protected] 15 subject: An Error Occurred! 16 level: debug

The mail handler is a fingers_crossed handler which means that it is only triggered when the action level, in this case critical is reached. It then logs everything including messages below the action level. The critical level is only triggered for 5xx HTTP code errors. The handler setting means that the output is then passed onto the buffered handler.
If you want both 400 level and 500 level errors to trigger an email, set the action_level to error instead of critical.

The buffered handler simply keeps all the messages for a request and then passes them onto the nested handler in one go. If you do not use this handler then each message will be emailed separately. This is
1. https://github.com/Seldaek/monolog

PDF brought to you by generated on February 10, 2014

Chapter 60: How to Configure Monolog to Email Errors | 227

then passed to the swift handler. This is the handler that actually deals with emailing you the error. The settings for this are straightforward, the to and from addresses and the subject. You can combine these handlers with other handlers so that the errors still get logged on the server as well as the emails being sent:
Listing 60-2

1 # app/config/config_prod.yml 2 monolog: 3 handlers: 4 main: 5 type: fingers_crossed 6 action_level: critical 7 handler: grouped 8 grouped: 9 type: group 10 members: [streamed, buffered] 11 streamed: 12 type: stream 13 path: "%kernel.logs_dir%/%kernel.environment%.log" 14 level: debug 15 buffered: 16 type: buffer 17 handler: swift 18 swift: 19 type: swift_mailer 20 from_email: [email protected] 21 to_email: [email protected] 22 subject: An Error Occurred! 23 level: debug

This uses the group handler to send the messages to the two group members, the buffered and the stream handlers. The messages will now be both written to the log file and emailed.

PDF brought to you by generated on February 10, 2014

Chapter 60: How to Configure Monolog to Email Errors | 228

Chapter 61

How to Configure Monolog to Display Console Messages

New in version 2.4: This feature was introduced to the MonologBridge in Symfony 2.4.

It is possible to use the console to print messages for certain verbosity levels using the OutputInterface1 instance that is passed when a command gets executed. When a lot of logging has to happen, it's cumbersome to print information depending on the verbosity settings (-v, -vv, -vvv) because the calls need to be wrapped in conditions. The code quickly gets verbose or dirty. For example:
Listing 61-1

1 2 3 4 5 6 7 8 9 10 11 12 13

use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; protected function execute(InputInterface $input, OutputInterface $output) { if ($output->getVerbosity() >= OutputInterface::VERBOSITY_DEBUG) { $output->writeln('Some info'); } if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) { $output->writeln('Some more info'); } }

1. http://api.symfony.com/2.4/Symfony/Component/Console/Output/OutputInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 61: How to Configure Monolog to Display Console Messages | 229

Instead of using these semantic methods to test for each of the verbosity levels, the MonologBridge2 provides a ConsoleHandler3 that listens to console events and writes log messages to the console output depending on the current log level and the console verbosity. The example above could then be rewritten as:
Listing 61-2

1 2 3 4 5 6 7 8 9 10 11

use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; protected function execute(InputInterface $input, OutputInterface $output) { // assuming the Command extends ContainerAwareCommand... $logger = $this->getContainer()->get('logger'); $logger->debug('Some info'); $logger->notice('Some more info'); }

Depending on the verbosity level that the command is run in and the user's configuration (see below), these messages may or may not be displayed to the console. If they are displayed, they are timestamped and colored appropriately. Additionally, error logs are written to the error output (php://stderr). There is no need to conditionally handle the verbosity settings anymore. The Monolog console handler is enabled in the Monolog configuration. This is the default in Symfony Standard Edition 2.4 too.
Listing 61-3

1 # app/config/config.yml 2 monolog: 3 handlers: 4 console: 5 type: console

With the verbosity_levels option you can adapt the mapping between verbosity and log level. In the given example it will also show notices in normal verbosity mode (instead of warnings only). Additionally, it will only use messages logged with the custom my_channel channel and it changes the display style via a custom formatter (see the MonologBundle reference for more information):
Listing 61-4

1 # app/config/config.yml 2 monolog: 3 handlers: 4 console: 5 type: console 6 verbosity_levels: 7 VERBOSITY_NORMAL: NOTICE 8 channels: my_channel 9 formatter: my_formatter

Listing 61-5

1 # app/config/services.yml 2 services: 3 my_formatter: 4 class: Symfony\Bridge\Monolog\Formatter\ConsoleFormatter 5 arguments: 6 - "[%%datetime%%] %%start_tag%%%%message%%%%end_tag%% (%%level_name%%) %%context%% %%extra%%\n"

2. https://github.com/symfony/MonologBridge 3. https://github.com/symfony/MonologBridge/blob/master/Handler/ConsoleHandler.php

PDF brought to you by generated on February 10, 2014

Chapter 61: How to Configure Monolog to Display Console Messages | 230

Chapter 62

How to Configure Monolog to Exclude 404 Errors from the Log

New in version 2.4: This feature was introduced to the MonologBundle in version 2.4, which was first packaged with Symfony at version 2.4.

Sometimes your logs become flooded with unwanted 404 HTTP errors, for example, when an attacker scans your app for some well-known application paths (e.g. /phpmyadmin). When using a fingers_crossed handler, you can exclude logging these 404 errors based on a regular expression in the MonologBundle configuration:
Listing 62-1

1 # app/config/config.yml 2 monolog: 3 handlers: 4 main: 5 # ... 6 type: fingers_crossed 7 handler: ... 8 excluded_404s: 9 - ^/phpmyadmin

PDF brought to you by generated on February 10, 2014

Chapter 62: How to Configure Monolog to Exclude 404 Errors from the Log | 231

Chapter 63

How to log Messages to different Files

The Symfony Standard Edition contains a bunch of channels for logging: doctrine, event, security and request. Each channel corresponds to a logger service (monolog.logger.XXX) in the container and is injected to the concerned service. The purpose of channels is to be able to organize different types of log messages. By default, Symfony2 logs every messages into a single file (regardless of the channel).

Switching a Channel to a different Handler

Now, suppose you want to log the doctrine channel to a different file. To do so, just create a new handler and configure it like this:
Listing 63-1

1 # app/config/config.yml 2 monolog: 3 handlers: 4 main: 5 type: stream 6 path: /var/log/symfony.log 7 channels: ["!doctrine"] 8 doctrine: 9 type: stream 10 path: /var/log/doctrine.log 11 channels: [doctrine]

YAML specification
You can specify the configuration by many forms:
Listing 63-2

1 channels: ~ 2 3 channels: foo

# Include all the channels # Include only channel "foo"

PDF brought to you by generated on February 10, 2014

Chapter 63: How to log Messages to different Files | 232

4 channels: "!foo" # Include all channels, except "foo" 5 6 channels: [foo, bar] # Include only channels "foo" and "bar" 7 channels: ["!foo", "!bar"] # Include all channels, except "foo" and "bar"

Creating your own Channel

You can change the channel monolog logs to one service at a time. This is done either via the configuration below or by tagging your service with monolog.logger and specifying which channel the service should log to. With the tag, the logger that is injected into that service is preconfigured to use the channel you've specified.

Configure Additional Channels without Tagged Services

New in version 2.3: This feature was introduced to the MonologBundle in version 2.4, which was first packaged with Symfony at version 2.4.

With MonologBundle 2.4 you can configure additional channels without the need to tag your services:
Listing 63-3

1 # app/config/config.yml 2 monolog: 3 channels: ["foo", "bar"]

With this, you can now send log messages to the foo channel by using the automatically registered logger service monolog.logger.foo.

Learn more from the Cookbook

How to use Monolog to write Logs

PDF brought to you by generated on February 10, 2014

Chapter 63: How to log Messages to different Files | 233

Chapter 64

How to create a custom Data Collector

The Symfony2 Profiler delegates data collecting to data collectors. Symfony2 comes bundled with a few of them, but you can easily create your own.

Creating a Custom Data Collector

Creating a custom data collector is as simple as implementing the DataCollectorInterface1:
Listing 64-1

1 interface DataCollectorInterface 2 { 3 /** 4 * Collects data for the given Request and Response. 5 * 6 * @param Request $request A Request instance 7 * @param Response $response A Response instance 8 * @param \Exception $exception An Exception instance 9 */ 10 function collect(Request $request, Response $response, \Exception $exception = null); 11 12 /** 13 * Returns the name of the collector. 14 * 15 * @return string The collector name 16 */ 17 function getName(); 18 }

The getName() method must return a unique name. This is used to access the information later on (see How to use the Profiler in a Functional Test for instance). The collect() method is responsible for storing the data it wants to give access to in local properties.

1. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/DataCollector/DataCollectorInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 64: How to create a custom Data Collector | 234

As the profiler serializes data collector instances, you should not store objects that cannot be serialized (like PDO objects), or you need to provide your own serialize() method.

Most of the time, it is convenient to extend DataCollector2 and populate the $this->data property (it takes care of serializing the $this->data property):
Listing 64-2

1 class MemoryDataCollector extends DataCollector 2 { 3 public function collect(Request $request, Response $response, \Exception $exception = 4 null) 5 { 6 $this->data = array( 7 'memory' => memory_get_peak_usage(true), 8 ); 9 } 10 11 public function getMemory() 12 { 13 return $this->data['memory']; 14 } 15 16 public function getName() 17 { 18 return 'memory'; 19 } }

Enabling Custom Data Collectors

To enable a data collector, add it as a regular service in one of your configuration, and tag it with data_collector:
Listing 64-3

1 services: 2 data_collector.your_collector_name: 3 class: Fully\Qualified\Collector\Class\Name 4 tags: 5 - { name: data_collector }

Adding Web Profiler Templates

When you want to display the data collected by your data collector in the web debug toolbar or the web profiler, create a Twig template following this skeleton:
Listing 64-4

1 {% extends 'WebProfilerBundle:Profiler:layout.html.twig' %} 2 3 {% block toolbar %} 4 {# the web debug toolbar content #} 5 {% endblock %}

2. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/DataCollector/DataCollector.html

PDF brought to you by generated on February 10, 2014

Chapter 64: How to create a custom Data Collector | 235

6 7 8 9 10 11 12 13 14 15 16 17

{% block head %} {# if the web profiler panel needs some specific JS or CSS files #} {% endblock %} {% block menu %} {# the menu content #} {% endblock %} {% block panel %} {# the panel content #} {% endblock %}

Each block is optional. The toolbar block is used for the web debug toolbar and menu and panel are used to add a panel to the web profiler. All blocks have access to the collector object.
Built-in templates use a base64 encoded image for the toolbar:
Listing 64-5

1 <img src="data:image/png;base64,..." />

You can easily calculate the base64 value for an image with this little script:
Listing 64-6

1 #!/usr/bin/env php 2 <?php 3 echo base64_encode(file_get_contents($_SERVER['argv'][1]));

To enable the template, add a template attribute to the data_collector tag in your configuration. For example, assuming your template is in some AcmeDebugBundle:
Listing 64-7

1 services: 2 data_collector.your_collector_name: 3 class: Acme\DebugBundle\Collector\Class\Name 4 tags: 5 - { name: data_collector, template: "AcmeDebugBundle:Collector:templatename", id: "your_collector_name" }

PDF brought to you by generated on February 10, 2014

Chapter 64: How to create a custom Data Collector | 236

Chapter 65

How to use Matchers to enable the Profiler Conditionally

By default, the profiler is only activated in the development environment. But it's imaginable that a developer may want to see the profiler even in production. Another situation may be that you want to show the profiler only when an admin has logged in. You can enable the profiler in these situations by using matchers.

Using the built-in Matcher

Symfony2 provides a built-in matcher1 which can match paths and IPs. For example, if you want to only show the profiler when accessing the page with the 168.0.0.1 IP, then you can use this configuration:
Listing 65-1

1 # app/config/config.yml 2 framework: 3 # ... 4 profiler: 5 matcher: 6 ip: 168.0.0.1

You can also set a path option to define the path on which the profiler should be enabled. For instance, setting it to ^/admin/ will enable the profiler only for the /admin/ URLs.

Creating a Custom Matcher

You can also create a custom matcher. This is a service that checks whether the profiler should be enabled or not. To create that service, create a class which implements RequestMatcherInterface2. This

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/RequestMatcher.html 2. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/RequestMatcherInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 65: How to use Matchers to enable the Profiler Conditionally | 237

interface requires one method: matches()3. This method returns false to disable the profiler and true to enable the profiler. To enable the profiler when a ROLE_SUPER_ADMIN is logged in, you can use something like:
Listing 65-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// src/Acme/DemoBundle/Profiler/SuperAdminMatcher.php namespace Acme\DemoBundle\Profiler;

use Symfony\Component\Security\Core\SecurityContext; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\RequestMatcherInterface; class SuperAdminMatcher implements RequestMatcherInterface { protected $securityContext; public function __construct(SecurityContext $securityContext) { $this->securityContext = $securityContext; } public function matches(Request $request) { return $this->securityContext->isGranted('ROLE_SUPER_ADMIN'); } }

Then, you need to configure the service:

Listing 65-3

1 parameters: 2 acme_demo.profiler.matcher.super_admin.class: Acme\DemoBundle\Profiler\SuperAdminMatcher 3 4 services: 5 acme_demo.profiler.matcher.super_admin: 6 class: "%acme_demo.profiler.matcher.super_admin.class%" 7 arguments: ["@security.context"]

Now the service is registered, the only thing left to do is configure the profiler to use this service as the matcher:
Listing 65-4

1 # app/config/config.yml 2 framework: 3 # ... 4 profiler: 5 matcher: 6 service: acme_demo.profiler.matcher.super_admin

3. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/RequestMatcherInterface.html#matches()

PDF brought to you by generated on February 10, 2014

Chapter 65: How to use Matchers to enable the Profiler Conditionally | 238

Chapter 66

Switching the Profiler Storage

By default the profile stores the collected data in files in the cache directory. You can control the storage being used through the dsn, username, password and lifetime options. For example, the following configuration uses MySQL as the storage for the profiler with a lifetime of one hour:
Listing 66-1

1 # app/config/config.yml 2 framework: 3 profiler: 4 dsn: "mysql:host=localhost;dbname=%database_name%" 5 username: "%database_user%" 6 password: "%database_password%" 7 lifetime: 3600

The HttpKernel component currently supports the following profiler storage implementations:

FileProfilerStorage1 MemcachedProfilerStorage2 MemcacheProfilerStorage3 MongoDbProfilerStorage4 MysqlProfilerStorage5 RedisProfilerStorage6 SqliteProfilerStorage7

1. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/FileProfilerStorage.html 2. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/MemcachedProfilerStorage.html 3. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/MemcacheProfilerStorage.html 4. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/MongoDbProfilerStorage.html 5. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/MysqlProfilerStorage.html 6. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/RedisProfilerStorage.html 7. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Profiler/SqliteProfilerStorage.html

PDF brought to you by generated on February 10, 2014

Chapter 66: Switching the Profiler Storage | 239

Chapter 67

How to register a new Request Format and Mime Type

Every Request has a "format" (e.g. html, json), which is used to determine what type of content to return in the Response. In fact, the request format, accessible via getRequestFormat()1, is used to set the MIME type of the Content-Type header on the Response object. Internally, Symfony contains a map of the most common formats (e.g. html, json) and their associated MIME types (e.g. text/ html, application/json). Of course, additional format-MIME type entries can easily be added. This document will show how you can add the jsonp format and corresponding MIME type.

Create a kernel.request Listener

The key to defining a new MIME type is to create a class that will "listen" to the kernel.request event dispatched by the Symfony kernel. The kernel.request event is dispatched early in Symfony's request handling process and allows you to modify the request object. Create the following class, replacing the path with a path to a bundle in your project:
Listing 67-1

1 2 3 4 5 6 7 8 9 10 11 12 13

// src/Acme/DemoBundle/RequestListener.php namespace Acme\DemoBundle;

use Symfony\Component\HttpKernel\HttpKernelInterface; use Symfony\Component\HttpKernel\Event\GetResponseEvent; class RequestListener { public function onKernelRequest(GetResponseEvent $event) { $event->getRequest()->setFormat('jsonp', 'application/javascript'); } }

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/Request.html#getRequestFormat()

PDF brought to you by generated on February 10, 2014

Chapter 67: How to register a new Request Format and Mime Type | 240

Registering your Listener

As with any other listener, you need to add it in one of your configuration files and register it as a listener by adding the kernel.event_listener tag:
Listing 67-2

1 # app/config/config.yml 2 services: 3 acme.demobundle.listener.request: 4 class: Acme\DemoBundle\RequestListener 5 tags: 6 - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }

At this point, the acme.demobundle.listener.request service has been configured and will be notified when the Symfony kernel dispatches the kernel.request event.
You can also register the listener in a configuration extension class (see Importing Configuration via Container Extensions for more information).

PDF brought to you by generated on February 10, 2014

Chapter 67: How to register a new Request Format and Mime Type | 241

Chapter 68

How to force routes to always use HTTPS or HTTP

Sometimes, you want to secure some routes and be sure that they are always accessed via the HTTPS protocol. The Routing component allows you to enforce the URI scheme via schemes:
Listing 68-1

1 secure: 2 path: /secure 3 defaults: { _controller: AcmeDemoBundle:Main:secure } 4 schemes: [https]

The above configuration forces the secure route to always use HTTPS. When generating the secure URL, and if the current scheme is HTTP, Symfony will automatically generate an absolute URL with HTTPS as the scheme:
Listing 68-2

1 2 3 4 5 6 7

{# If the current scheme is HTTPS #} {{ path('secure') }} {# generates /secure #} {# If the current scheme is HTTP #} {{ path('secure') }} {# generates https://example.com/secure #}

The requirement is also enforced for incoming requests. If you try to access the /secure path with HTTP, you will automatically be redirected to the same URL, but with the HTTPS scheme. The above example uses https for the scheme, but you can also force a URL to always use http.
The Security component provides another way to enforce HTTP or HTTPS via the requires_channel setting. This alternative method is better suited to secure an "area" of your website (all URLs under /admin) or when you want to secure URLs defined in a third party bundle.

PDF brought to you by generated on February 10, 2014

Chapter 68: How to force routes to always use HTTPS or HTTP | 242

Chapter 69

How to allow a "/" character in a route parameter

Sometimes, you need to compose URLs with parameters that can contain a slash /. For example, take the classic /hello/{name} route. By default, /hello/Fabien will match this route but not /hello/Fabien/ Kris. This is because Symfony uses this character as separator between route parts. This guide covers how you can modify a route so that /hello/Fabien/Kris matches the /hello/{name} route, where {name} equals Fabien/Kris.

Configure the Route

By default, the Symfony Routing component requires that the parameters match the following regex path: [^/]+. This means that all characters are allowed except /. You must explicitly allow / to be part of your parameter by specifying a more permissive regex path.
Listing 69-1

1 _hello: 2 path: /hello/{name} 3 defaults: { _controller: AcmeDemoBundle:Demo:hello } 4 requirements: 5 name: .+

That's it! Now, the {name} parameter can contain the / character.

PDF brought to you by generated on February 10, 2014

Chapter 69: How to allow a "/" character in a route parameter | 243

Chapter 70

How to Configure a Redirect without a Custom Controller

Sometimes, a URL needs to redirect to another URL. You can do that by creating a new controller action whose only task is to redirect, but using the RedirectController1 of the FrameworkBundle is even easier. You can redirect to a specific path (e.g. /about) or to a specific route using its name (e.g. homepage).

Redirecting Using a Path

Assume there is no default controller for the / path of your application and you want to redirect these requests to /app. You will need to use the urlRedirect()2 action to redirect to this new url:
Listing 70-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

# app/config/routing.yml # load some routes - one should ultimately have the path "/app" AppBundle: resource: "@AcmeAppBundle/Controller/" type: annotation prefix: /app # redirecting the root root: path: / defaults: _controller: FrameworkBundle:Redirect:urlRedirect path: /app permanent: true

1. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Controller/RedirectController.html 2. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Controller/RedirectController.html#urlRedirect()

PDF brought to you by generated on February 10, 2014

Chapter 70: How to Configure a Redirect without a Custom Controller | 244

In this example, you configured a route for the / path and let the RedirectController redirect it to /app. The permanent switch tells the action to issue a 301 HTTP status code instead of the default 302 HTTP status code.

Redirecting Using a Route

Assume you are migrating your website from WordPress to Symfony, you want to redirect /wp-admin to the route sonata_admin_dashboard. You don't know the path, only the route name. This can be achieved using the redirect()3 action:
Listing 70-2

1 2 3 4 5 6 7 8 9 10 11

# app/config/routing.yml # ... # redirecting the admin home root: path: /wp-admin defaults: _controller: FrameworkBundle:Redirect:redirect route: sonata_admin_dashboard permanent: true

Because you are redirecting to a route instead of a path, the required option is called route in the redirect action, instead of path in the urlRedirect action.

3. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Controller/RedirectController.html#redirect()

PDF brought to you by generated on February 10, 2014

Chapter 70: How to Configure a Redirect without a Custom Controller | 245

Chapter 71

How to use HTTP Methods beyond GET and POST in Routes

The HTTP method of a request is one of the requirements that can be checked when seeing if it matches a route. This is introduced in the routing chapter of the book "Routing" with examples using GET and POST. You can also use other HTTP verbs in this way. For example, if you have a blog post entry then you could use the same URL path to show it, make changes to it and delete it by matching on GET, PUT and DELETE.
Listing 71-1

1 blog_show: 2 path: 3 defaults: 4 methods: 5 6 blog_update: 7 path: 8 defaults: 9 methods: 10 11 blog_delete: 12 path: 13 defaults: 14 methods:

/blog/{slug} { _controller: AcmeDemoBundle:Blog:show } [GET] /blog/{slug} { _controller: AcmeDemoBundle:Blog:update } [PUT] /blog/{slug} { _controller: AcmeDemoBundle:Blog:delete } [DELETE]

Faking the Method with _method

The _method functionality shown here is disabled by default in Symfony 2.2 and enabled by default in Symfony 2.3. To control it in Symfony 2.2, you must call Request::enableHttpMethodParameterOverride1 before you handle the request (e.g. in your front controller). In Symfony 2.3, use the http_method_override option.

PDF brought to you by generated on February 10, 2014

Chapter 71: How to use HTTP Methods beyond GET and POST in Routes | 246

Unfortunately, life isn't quite this simple, since most browsers do not support sending PUT and DELETE requests. Fortunately Symfony2 provides you with a simple way of working around this limitation. By including a _method parameter in the query string or parameters of an HTTP request, Symfony2 will use this as the method when matching routes. Forms automatically include a hidden field for this parameter if their submission method is not GET or POST. See the related chapter in the forms documentation for more information.

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/Request.html#enableHttpMethodParameterOverride()

PDF brought to you by generated on February 10, 2014

Chapter 71: How to use HTTP Methods beyond GET and POST in Routes | 247

Chapter 72

How to use Service Container Parameters in your Routes

Sometimes you may find it useful to make some parts of your routes globally configurable. For instance, if you build an internationalized site, you'll probably start with one or two locales. Surely you'll add a requirement to your routes to prevent a user from matching a locale other than the locales your support. You could hardcode your _locale requirement in all your routes. But a better solution is to use a configurable service container parameter right inside your routing configuration:
Listing 72-1

1 # app/config/routing.yml 2 contact: 3 path: /{_locale}/contact 4 defaults: { _controller: AcmeDemoBundle:Main:contact } 5 requirements: 6 _locale: "%acme_demo.locales%"

You can now control and set the acme_demo.locales parameter somewhere in your container:
Listing 72-2

1 # app/config/config.yml 2 parameters: 3 acme_demo.locales: en|es

You can also use a parameter to define your route path (or part of your path):
Listing 72-3

1 # app/config/routing.yml 2 some_route: 3 path: /%acme_demo.route_prefix%/contact 4 defaults: { _controller: AcmeDemoBundle:Main:contact }

PDF brought to you by generated on February 10, 2014

Chapter 72: How to use Service Container Parameters in your Routes | 248

Just like in normal service container configuration files, if you actually need a % in your route, you can escape the percent sign by doubling it, e.g. /score-50%%, which would resolve to /score-50%. However, as the % characters included in any URL are automatically encoded, the resulting URL of this example would be /score-50%25 (%25 is the result of encoding the % character).

PDF brought to you by generated on February 10, 2014

Chapter 72: How to use Service Container Parameters in your Routes | 249

Chapter 73

How to create a custom Route Loader

A custom route loader allows you to add routes to an application without including them, for example, in a YAML file. This comes in handy when you have a bundle but don't want to manually add the routes for the bundle to app/config/routing.yml. This may be especially important when you want to make the bundle reusable, or when you have open-sourced it as this would slow down the installation process and make it error-prone. Alternatively, you could also use a custom route loader when you want your routes to be automatically generated or located based on some convention or pattern. One example is the FOSRestBundle1 where routing is generated based off the names of the action methods in a controller.
There are many bundles out there that use their own route loaders to accomplish cases like those described above, for instance FOSRestBundle2, KnpRadBundle3 and SonataAdminBundle4.

Loading Routes
The routes in a Symfony application are loaded by the DelegatingLoader5. This loader uses several other loaders (delegates) to load resources of different types, for instance YAML files or @Route and @Method annotations in controller files. The specialized loaders implement LoaderInterface6 and therefore have two important methods: supports()7 and load()8. Take these lines from the routing.yml in the AcmeDemoBundle of the Standard Edition:
Listing 73-1

1. 2. 3. 4. 5.

https://github.com/FriendsOfSymfony/FOSRestBundle https://github.com/FriendsOfSymfony/FOSRestBundle https://github.com/KnpLabs/KnpRadBundle https://github.com/sonata-project/SonataAdminBundle http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Routing/DelegatingLoader.html

6. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html 7. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html#supports() 8. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html#load()

PDF brought to you by generated on February 10, 2014

Chapter 73: How to create a custom Route Loader | 250

1 # src/Acme/DemoBundle/Resources/config/routing.yml 2 _demo: 3 resource: "@AcmeDemoBundle/Controller/DemoController.php" 4 type: annotation 5 prefix: /demo

When the main loader parses this, it tries all the delegate loaders and calls their supports()9 method with the given resource (@AcmeDemoBundle/Controller/DemoController.php) and type (annotation) as arguments. When one of the loader returns true, its load()10 method will be called, which should return a RouteCollection11 containing Route12 objects.

Creating a Custom Loader

To load routes from some custom source (i.e. from something other than annotations, YAML or XML files), you need to create a custom route loader. This loader should implement LoaderInterface13. The sample loader below supports loading routing resources with a type of extra. The type extra isn't important - you can just invent any resource type you want. The resource name itself is not actually used in the example:
Listing 73-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

namespace Acme\DemoBundle\Routing; use use use use Symfony\Component\Config\Loader\LoaderInterface; Symfony\Component\Config\Loader\LoaderResolverInterface; Symfony\Component\Routing\Route; Symfony\Component\Routing\RouteCollection;

class ExtraLoader implements LoaderInterface { private $loaded = false; public function load($resource, $type = null) { if (true === $this->loaded) { throw new \RuntimeException('Do not add the "extra" loader twice'); } $routes = new RouteCollection();

// prepare a new route $pattern = '/extra/{parameter}'; $defaults = array( '_controller' => 'AcmeDemoBundle:Demo:extra', ); $requirements = array( 'parameter' => '\d+', ); $route = new Route($pattern, $defaults, $requirements); // add the new route to the route collection:

9. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html#supports() 10. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html#load() 11. http://api.symfony.com/2.4/Symfony/Component/Routing/RouteCollection.html 12. http://api.symfony.com/2.4/Symfony/Component/Routing/Route.html 13. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 73: How to create a custom Route Loader | 251

31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 }

$routeName = 'extraRoute'; $routes->add($routeName, $route); $this->loaded = true; return $routes; } public function supports($resource, $type = null) { return 'extra' === $type; } public function getResolver() { // needed, but can be blank, unless you want to load other resources // and if you do, using the Loader base class is easier (see below) } public function setResolver(LoaderResolverInterface $resolver) { // same as above }

Make sure the controller you specify really exists.

Now define a service for the ExtraLoader:

Listing 73-3

1 services: 2 acme_demo.routing_loader: 3 class: Acme\DemoBundle\Routing\ExtraLoader 4 tags: 5 - { name: routing.loader }

Notice the tag routing.loader. All services with this tag will be marked as potential route loaders and added as specialized routers to the DelegatingLoader14.

Using the Custom Loader

If you did nothing else, your custom routing loader would not be called. Instead, you only need to add a few extra lines to the routing configuration:
Listing 73-4

1 # app/config/routing.yml 2 AcmeDemoBundle_Extra: 3 resource: . 4 type: extra

The important part here is the type key. Its value should be "extra". This is the type which the ExtraLoader supports and this will make sure its load() method gets called. The resource key is insignificant for the ExtraLoader, so it is set to ".".
14. http://api.symfony.com/2.4/Symfony/Bundle/FrameworkBundle/Routing/DelegatingLoader.html

PDF brought to you by generated on February 10, 2014

Chapter 73: How to create a custom Route Loader | 252

The routes defined using custom route loaders will be automatically cached by the framework. So whenever you change something in the loader class itself, don't forget to clear the cache.

More Advanced Loaders

In most cases it's better not to implement LoaderInterface15 yourself, but extend from Loader16. This class knows how to use a LoaderResolver17 to load secondary routing resources. Of course you still need to implement supports()18 and load()19. Whenever you want to load another resource - for instance a YAML routing configuration file - you can call the import()20 method:
Listing 73-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

namespace Acme\DemoBundle\Routing; use Symfony\Component\Config\Loader\Loader; use Symfony\Component\Routing\RouteCollection; class AdvancedLoader extends Loader { public function load($resource, $type = null) { $collection = new RouteCollection(); $resource = '@AcmeDemoBundle/Resources/config/import_routing.yml'; $type = 'yaml'; $importedRoutes = $this->import($resource, $type); $collection->addCollection($importedRoutes); return $collection; } public function supports($resource, $type = null) { return $type === 'advanced_extra'; } }

The resource name and type of the imported routing configuration can be anything that would normally be supported by the routing configuration loader (YAML, XML, PHP, annotation, etc.).

15. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html 16. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/Loader.html 17. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderResolver.html 18. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html#supports() 19. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/LoaderInterface.html#load() 20. http://api.symfony.com/2.4/Symfony/Component/Config/Loader/Loader.html#import()

PDF brought to you by generated on February 10, 2014

Chapter 73: How to create a custom Route Loader | 253

Chapter 74

Redirect URLs with a Trailing Slash

The goal of this cookbook is to demonstrate how to redirect URLs with a trailing slash to the same URL without a trailing slash (for example /en/blog/ to /en/blog). Create a controller that will match any URL with a trailing slash, remove the trailing slash (keeping query parameters if any) and redirect to the new URL with a 301 response status code:
Listing 74-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

// src/Acme/DemoBundle/Controller/RedirectingController.php namespace Acme\DemoBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\HttpFoundation\Request; class RedirectingController extends Controller { public function removeTrailingSlashAction(Request $request) { $pathInfo = $request->getPathInfo(); $requestUri = $request->getRequestUri(); $url = str_replace($pathInfo, rtrim($pathInfo, ' /'), $requestUri); return $this->redirect($url, 301); } }

After that, create a route to this controller that's matched whenever a URL with a trailing slash is requested. Be sure to put this route last in your system, as explained below:
Listing 74-2

1 remove_trailing_slash: 2 path: /{url} 3 defaults: { _controller: AcmeDemoBundle:Redirecting:removeTrailingSlash } 4 requirements: 5 url: .*/$ 6 _method: GET

PDF brought to you by generated on February 10, 2014

Chapter 74: Redirect URLs with a Trailing Slash | 254

Redirecting a POST request does not work well in old browsers. A 302 on a POST request would send a GET request after the redirection for legacy reasons. For that reason, the route here only matches GET requests.

Make sure to include this route in your routing configuration at the very end of your route listing. Otherwise, you risk redirecting real routes (including Symfony2 core routes) that actually do have a trailing slash in their path.

PDF brought to you by generated on February 10, 2014

Chapter 74: Redirect URLs with a Trailing Slash | 255

Chapter 75

How to load Security Users from the Database (the Entity Provider)
The security layer is one of the smartest tools of Symfony. It handles two things: the authentication and the authorization processes. Although it may seem difficult to understand how it works internally, the security system is very flexible and allows you to integrate your application with any authentication backend, like Active Directory, an OAuth server or a database.

Introduction
This article focuses on how to authenticate users against a database table managed by a Doctrine entity class. The content of this cookbook entry is split in three parts. The first part is about designing a Doctrine User entity class and making it usable in the security layer of Symfony. The second part describes how to easily authenticate a user with the Doctrine EntityUserProvider1 object bundled with the framework and some configuration. Finally, the tutorial will demonstrate how to create a custom EntityUserProvider2 object to retrieve users from a database with custom conditions. This tutorial assumes there is a bootstrapped and loaded Acme\UserBundle bundle in the application kernel.

The Data Model

For the purpose of this cookbook, the AcmeUserBundle bundle contains a User entity class with the following fields: id, username, password, email and isActive. The isActive field tells whether or not the user account is active. To make it shorter, the getter and setter methods for each have been removed to focus on the most important methods that come from the UserInterface3.

1. http://api.symfony.com/2.4/Symfony/Bridge/Doctrine/Security/User/EntityUserProvider.html 2. http://api.symfony.com/2.4/Symfony/Bridge/Doctrine/Security/User/EntityUserProvider.html 3. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 256

You can generate the missing getter and setters by running:

Listing 75-1

1 $ php app/console doctrine:generate:entities Acme/UserBundle/Entity/User

Listing 75-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

// src/Acme/UserBundle/Entity/User.php namespace Acme\UserBundle\Entity;

use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Security\Core\User\UserInterface;

/** * Acme\UserBundle\Entity\User * * @ORM\Table(name="acme_users") * @ORM\Entity(repositoryClass="Acme\UserBundle\Entity\UserRepository") */ class User implements UserInterface, \Serializable { /** * @ORM\Column(type="integer") * @ORM\Id * @ORM\GeneratedValue(strategy="AUTO") */ private $id; /** * @ORM\Column(type="string", length=25, unique=true) */ private $username; /** * @ORM\Column(type="string", length=64) */ private $password; /** * @ORM\Column(type="string", length=60, unique=true) */ private $email; /** * @ORM\Column(name="is_active", type="boolean") */ private $isActive;
public function __construct() { $this->isActive = true; // may not be needed, see section on salt below // $this->salt = md5(uniqid(null, true)); }

/** * @inheritDoc */ public function getUsername()

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 257

53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111

{ return $this->username; }

/** * @inheritDoc */ public function getSalt() { // you *may* need a real salt depending on your encoder // see section on salt below return null; } /** * @inheritDoc */ public function getPassword() { return $this->password; } /** * @inheritDoc */ public function getRoles() { return array('ROLE_USER'); } /** * @inheritDoc */ public function eraseCredentials() { } /** * @see \Serializable::serialize() */ public function serialize() { return serialize(array( $this->id, $this->username, $this->password, // see section on salt below // $this->salt, )); } /** * @see \Serializable::unserialize() */ public function unserialize($serialized) { list ( $this->id, $this->username,

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 258

112 113 114 115 116 117 }

$this->password, // see section on salt below // $this->salt ) = unserialize($serialized); }

If you choose to implement EquatableInterface4, you determine yourself which properties need to be compared to distinguish your user objects.

Generate the database table for your User entity by running:

Listing 75-3

1 $ php app/console doctrine:schema:update --force

In order to use an instance of the AcmeUserBundle:User class in the Symfony security layer, the entity class must implement the UserInterface5. This interface forces the class to implement the five following methods: getRoles(), getPassword(), getSalt(), getUsername(), eraseCredentials()

For more details on each of these, see UserInterface6.

What is the importance of serialize and unserialize?

The Serializable7 interface and its serialize and unserialize methods have been added to allow the User class to be serialized to the session. This may or may not be needed depending on your setup, but it's probably a good idea. The id is the most important value that needs to be serialized because the refreshUser()8 method reloads the user on each request by using the id. In practice, this means that the User object is reloaded from the database on each request using the id from the serialized object. This makes sure all of the User's data is fresh. Symfony also uses the username, salt, and password to verify that the User has not changed between requests. Failing to serialize these may cause you to be logged out on each request. If your User implements EquatableInterface9, then instead of these properties being checked, your isEqualTo method is simply called, and you can check whatever properties you want. Unless you understand this, you probably won't need to implement this interface or worry about it.

Below is an export of the User table from MySQL with user admin and password admin (which has been encoded). For details on how to create user records and encode their password, see Encoding the User's Password.
4. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/EquatableInterface.html 5. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html 6. 7. 8. 9. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html http://php.net/manual/en/class.serializable.php http://api.symfony.com/2.4/Symfony/Bridge/Doctrine/Security/User/EntityUserProvider.html#refreshUser() http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/EquatableInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 259

Listing 75-4

1 2 3 4 5 6

$ mysql> select * from acme_users; +----+----------+------------------------------------------+--------------------+-----------+ | id | username | password | email | is_active | +----+----------+------------------------------------------+--------------------+-----------+ | 1 | admin | d033e22ae348aeb5660fc2140aec35850c4da997 | [email protected] | 1 | +----+----------+------------------------------------------+--------------------+-----------+

The next part will focus on how to authenticate one of these users thanks to the Doctrine entity user provider and a couple of lines of configuration.

Do you need to use a Salt?

Yes. Hashing a password with a salt is a necessary step so that encoded passwords can't be decoded. However, some encoders - like Bcrypt - have a built-in salt mechanism. If you configure bcrypt as your encoder in security.yml (see the next section), then getSalt() should return null, so that Bcrypt generates the salt itself. However, if you use an encoder that does not have a built-in salting ability (e.g. sha512), you must (from a security perspective) generate your own, random salt, store it on a salt property that is saved to the database, and return it from getSalt(). Some of the code needed is commented out in the above example.

Authenticating Someone against a Database

Authenticating a Doctrine user against the database with the Symfony security layer is a piece of cake. Everything resides in the configuration of the SecurityBundle stored in the app/config/security.yml file. Below is an example of configuration where the user will enter their username and password via HTTP basic authentication. That information will then be checked against your User entity records in the database:
Listing 75-5

1 # app/config/security.yml 2 security: 3 encoders: 4 Acme\UserBundle\Entity\User: 5 algorithm: bcrypt 6 7 role_hierarchy: 8 ROLE_ADMIN: ROLE_USER 9 ROLE_SUPER_ADMIN: [ ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH ] 10 11 providers: 12 administrators: 13 entity: { class: AcmeUserBundle:User, property: username } 14 15 firewalls: 16 admin_area: 17 pattern: ^/admin 18 http_basic: ~ 19 20 access_control: 21 - { path: ^/admin, roles: ROLE_ADMIN }

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 260

The encoders section associates the bcrypt password encoder to the entity class. This means that Symfony will expect the password that's stored in the database to be encoded using this encoder. For details on how to create a new User object with a properly encoded password, see the Encoding the User's Password section of the security chapter.
If you're using PHP 5.4 or lower, you'll need to install the ircmaxell/password-compat library via Composer in order to be able to use the bcrypt encoder:
Listing 75-6

{ "require": { ... "ircmaxell/password-compat": "~1.0.3" } }

The providers section defines an administrators user provider. A user provider is a "source" of where users are loaded during authentication. In this case, the entity keyword means that Symfony will use the Doctrine entity user provider to load User entity objects from the database by using the username unique field. In other words, this tells Symfony how to fetch the user from the database before checking the password validity.

Forbid Inactive Users

If a User's isActive property is set to false (i.e. is_active is 0 in the database), the user will still be able to login access the site normally. To prevent "inactive" users from logging in, you'll need to do a little more work. The easiest way to exclude inactive users is to implement the AdvancedUserInterface10 interface that takes care of checking the user's account status. The AdvancedUserInterface11 extends the UserInterface12 interface, so you just need to switch to the new interface in the AcmeUserBundle:User entity class to benefit from simple and advanced authentication behaviors. The AdvancedUserInterface13 interface adds four extra methods to validate the account status: isAccountNonExpired() checks whether the user's account has expired, isAccountNonLocked() checks whether the user is locked, isCredentialsNonExpired() checks whether the user's credentials (password) has expired, isEnabled() checks whether the user is enabled.

For this example, the first three methods will return true whereas the isEnabled() method will return the boolean value in the isActive field.
Listing 75-7

1 2 3 4 5 6 7 8

// src/Acme/UserBundle/Entity/User.php namespace Acme\UserBundle\Entity;

use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Security\Core\User\AdvancedUserInterface; class User implements AdvancedUserInterface, \Serializable {

10. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/AdvancedUserInterface.html 11. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/AdvancedUserInterface.html 12. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html 13. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/AdvancedUserInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 261

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 }

// ...
public function isAccountNonExpired() { return true; } public function isAccountNonLocked() { return true; } public function isCredentialsNonExpired() { return true; } public function isEnabled() { return $this->isActive; }

Now, if you try to authenticate as a user who's is_active database field is set to 0, you won't be allowed.
When using the AdvancedUserInterface, you should also add any of the properties used by these methods (like isActive()) to the serialize() method. If you don't do this, your user may not be deserialized correctly from the session on each request.

The next session will focus on how to write a custom entity provider to authenticate a user with their username or email address.

Authenticating Someone with a Custom Entity Provider

The next step is to allow a user to authenticate with their username or email address as they are both unique in the database. Unfortunately, the native entity provider is only able to handle a single property to fetch the user from the database. To accomplish this, create a custom entity provider that looks for a user whose username or email field matches the submitted login username. The good news is that a Doctrine repository object can act as an entity user provider if it implements the UserProviderInterface14. This interface comes with three methods to implement: loadUserByUsername($username), refreshUser(UserInterface $user), and supportsClass($class). For more details, see UserProviderInterface15. The code below shows the implementation of the UserProviderInterface16 in the UserRepository class:
Listing 75-8

1 // src/Acme/UserBundle/Entity/UserRepository.php 2 namespace Acme\UserBundle\Entity; 3 4 use Symfony\Component\Security\Core\User\UserInterface;

14. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserProviderInterface.html 15. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserProviderInterface.html 16. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserProviderInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 262

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57

use use use use use

Symfony\Component\Security\Core\User\UserProviderInterface; Symfony\Component\Security\Core\Exception\UsernameNotFoundException; Symfony\Component\Security\Core\Exception\UnsupportedUserException; Doctrine\ORM\EntityRepository; Doctrine\ORM\NoResultException;

class UserRepository extends EntityRepository implements UserProviderInterface { public function loadUserByUsername($username) { $q = $this ->createQueryBuilder('u') ->where('u.username = :username OR u.email = :email') ->setParameter('username', $username) ->setParameter('email', $username) ->getQuery(); try { // The Query::getSingleResult() method throws an exception // if there is no record matching the criteria. $user = $q->getSingleResult(); } catch (NoResultException $e) { $message = sprintf( 'Unable to find an active admin AcmeUserBundle:User object identified by "%s".', $username ); throw new UsernameNotFoundException($message, 0, $e); } return $user; } public function refreshUser(UserInterface $user) { $class = get_class($user); if (!$this->supportsClass($class)) { throw new UnsupportedUserException( sprintf( 'Instances of "%s" are not supported.', $class ) ); } return $this->find($user->getId()); } public function supportsClass($class) { return $this->getEntityName() === $class || is_subclass_of($class, $this->getEntityName()); } }

To finish the implementation, the configuration of the security layer must be changed to tell Symfony to use the new custom entity provider instead of the generic Doctrine entity provider. It's trivial to achieve by removing the property field in the security.providers.administrators.entity section of the security.yml file.
PDF brought to you by generated on February 10, 2014 Chapter 75: How to load Security Users from the Database (the Entity Provider) | 263

Listing 75-9

1 # app/config/security.yml 2 security: 3 # ... 4 providers: 5 administrators: 6 entity: { class: AcmeUserBundle:User } 7 # ...

By doing this, the security layer will use an instance of UserRepository and call its loadUserByUsername() method to fetch a user from the database whether they filled in their username or email address.

Managing Roles in the Database

The end of this tutorial focuses on how to store and retrieve a list of roles from the database. As mentioned previously, when your user is loaded, its getRoles() method returns the array of security roles that should be assigned to the user. You can load this data from anywhere - a hardcoded list used for all users (e.g. array('ROLE_USER')), a Doctrine array property called roles, or via a Doctrine relationship, as you'll learn about in this section.
In a typical setup, you should always return at least 1 role from the getRoles() method. By convention, a role called ROLE_USER is usually returned. If you fail to return any roles, it may appear as if your user isn't authenticated at all.

In this example, the AcmeUserBundle:User entity class defines a many-to-many relationship with a AcmeUserBundle:Role entity class. A user can be related to several roles and a role can be composed of one or more users. The previous getRoles() method now returns the list of related roles. Notice that __construct() and getRoles() methods have changed:
Listing 75-10

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

// src/Acme/UserBundle/Entity/User.php namespace Acme\UserBundle\Entity;

use Doctrine\Common\Collections\ArrayCollection; // ... class User implements AdvancedUserInterface, \Serializable { // ...

/** * @ORM\ManyToMany(targetEntity="Role", inversedBy="users") * */ private $roles;

public function __construct() { $this->roles = new ArrayCollection(); } public function getRoles() { return $this->roles->toArray();

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 264

25 26 27 28 29 }

// ...

The AcmeUserBundle:Role entity class defines three fields (id, name and role). The unique role field contains the role name (e.g. ROLE_ADMIN) used by the Symfony security layer to secure parts of the application:
Listing 75-11

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48

// src/Acme/Bundle/UserBundle/Entity/Role.php namespace Acme\UserBundle\Entity;

use Symfony\Component\Security\Core\Role\RoleInterface; use Doctrine\Common\Collections\ArrayCollection; use Doctrine\ORM\Mapping as ORM;

/** * @ORM\Table(name="acme_roles") * @ORM\Entity() */ class Role implements RoleInterface { /** * @ORM\Column(name="id", type="integer") * @ORM\Id() * @ORM\GeneratedValue(strategy="AUTO") */ private $id; /** * @ORM\Column(name="name", type="string", length=30) */ private $name; /** * @ORM\Column(name="role", type="string", length=20, unique=true) */ private $role; /** * @ORM\ManyToMany(targetEntity="User", mappedBy="roles") */ private $users;
public function __construct() { $this->users = new ArrayCollection(); }

/** * @see RoleInterface */ public function getRole() { return $this->role; }

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 265

49 50 }

// ... getters and setters for each property

For brevity, the getter and setter methods are hidden, but you can generate them:
Listing 75-12

1 $ php app/console doctrine:generate:entities Acme/UserBundle/Entity/User

Don't forget also to update your database schema:

Listing 75-13

1 $ php app/console doctrine:schema:update --force

This will create the acme_role table and a user_role that stores the many-to-many relationship between acme_user and acme_role. If you had one user linked to one role, your database might look something like this:
Listing 75-14

1 2 3 4 5 6 7 8 9 10 11 12 13

$ mysql> SELECT * FROM acme_role; +----+-------+------------+ | id | name | role | +----+-------+------------+ | 1 | admin | ROLE_ADMIN | +----+-------+------------+ $ mysql> SELECT * FROM user_role; +---------+---------+ | user_id | role_id | +---------+---------+ | 1 | 1 | +---------+---------+

And that's it! When the user logs in, Symfony security system will call the User::getRoles method. This will return an array of Role objects that Symfony will use to determine if the user should have access to certain parts of the system.

What's the purpose of the RoleInterface?

Notice that the Role class implements RoleInterface17. This is because Symfony's security system requires that the User::getRoles method returns an array of either role strings or objects that implement this interface. If Role didn't implement this interface, then User::getRoles would need to iterate over all the Role objects, call getRole on each, and create an array of strings to return. Both approaches are valid and equivalent.

Improving Performance with a Join

To improve performance and avoid lazy loading of roles when retrieving a user from the custom entity provider, you can use a Doctrine join to the roles relationship in the UserRepository::loadUserByUsername() method. This will fetch the user and their associated roles with a single query:
Listing 75-15

1 // src/Acme/UserBundle/Entity/UserRepository.php 2 namespace Acme\UserBundle\Entity;

17. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Role/RoleInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 266

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// ...
class UserRepository extends EntityRepository implements UserProviderInterface { public function loadUserByUsername($username) { $q = $this ->createQueryBuilder('u') ->select('u, r') ->leftJoin('u.roles', 'r') ->where('u.username = :username OR u.email = :email') ->setParameter('username', $username) ->setParameter('email', $username) ->getQuery();

// ...
}

// ...
}

The QueryBuilder::leftJoin() method joins and fetches related roles from the AcmeUserBundle:User model class when a user is retrieved by their email address or username.

Understanding serialize and how a User is Saved in the Session

If you're curious about the importance of the serialize() method inside the User class or how the User object is serialized or deserialized, then this section is for you. If not, feel free to skip this. Once the user is logged in, the entire User object is serialized into the session. On the next request, the User object is deserialized. Then, value of the id property is used to re-query for a fresh User object from the database. Finally, the fresh User object is compared in some way to the deserialized User object to make sure that they represent the same user. For example, if the username on the 2 User objects doesn't match for some reason, then the user will be logged out for security reasons. Even though this all happens automatically, there are a few important side-effects. First, the Serializable18 interface and its serialize and unserialize methods have been added to allow the User class to be serialized to the session. This may or may not be needed depending on your setup, but it's probably a good idea. In theory, only the id needs to be serialized, because the refreshUser()19 method refreshes the user on each request by using the id (as explained above). However in practice, this means that the User object is reloaded from the database on each request using the id from the serialized object. This makes sure all of the User's data is fresh. Symfony also uses the username, salt, and password to verify that the User has not changed between requests. Failing to serialize these may cause you to be logged out on each request. If your User implements the EquatableInterface20, then instead of these properties being checked, your isEqualTo method is simply called, and you can check whatever properties you want. Unless you understand this, you probably won't need to implement this interface or worry about it.

18. http://php.net/manual/en/class.serializable.php 19. http://api.symfony.com/2.4/Symfony/Bridge/Doctrine/Security/User/EntityUserProvider.html#refreshUser() 20. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/EquatableInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 267

New in version 2.1: In Symfony 2.1, the equals method was removed from UserInterface and the EquatableInterface was added in its place.

PDF brought to you by generated on February 10, 2014

Chapter 75: How to load Security Users from the Database (the Entity Provider) | 268

Chapter 76

How to add "Remember Me" Login Functionality

Once a user is authenticated, their credentials are typically stored in the session. This means that when the session ends they will be logged out and have to provide their login details again next time they wish to access the application. You can allow users to choose to stay logged in for longer than the session lasts using a cookie with the remember_me firewall option. The firewall needs to have a secret key configured, which is used to encrypt the cookie's content. It also has several options with default values which are shown here:
Listing 76-1

1 # app/config/security.yml 2 firewalls: 3 main: 4 remember_me: 5 key: "%secret%" 6 lifetime: 31536000 # 365 days in seconds 7 path: / 8 domain: ~ # Defaults to the current domain from $_SERVER

It's a good idea to provide the user with the option to use or not use the remember me functionality, as it will not always be appropriate. The usual way of doing this is to add a checkbox to the login form. By giving the checkbox the name _remember_me, the cookie will automatically be set when the checkbox is checked and the user successfully logs in. So, your specific login form might ultimately looks like this:
Listing 76-2

1 2 3 4 5 6 7 8 9 10

{# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #} {% if error %} <div>{{ error.message }}</div> {% endif %}

<form action="{{ path('login_check') }}" method="post"> <label for="username">Username:</label> <input type="text" id="username" name="_username" value="{{ last_username }}" /> <label for="password">Password:</label>

PDF brought to you by generated on February 10, 2014

Chapter 76: How to add "Remember Me" Login Functionality | 269

11 <input 12 13 <input 14 <label 15 16 <input 17 </form>

type="password" id="password" name="_password" /> type="checkbox" id="remember_me" name="_remember_me" checked /> for="remember_me">Keep me logged in</label> type="submit" name="login" />

The user will then automatically be logged in on subsequent visits while the cookie remains valid.

Forcing the User to Re-authenticate before accessing certain Resources

When the user returns to your site, they are authenticated automatically based on the information stored in the remember me cookie. This allows the user to access protected resources as if the user had actually authenticated upon visiting the site. In some cases, however, you may want to force the user to actually re-authenticate before accessing certain resources. For example, you might allow "remember me" users to see basic account information, but then require them to actually re-authenticate before modifying that information. The Security component provides an easy way to do this. In addition to roles explicitly assigned to them, users are automatically given one of the following roles depending on how they are authenticated: IS_AUTHENTICATED_ANONYMOUSLY - automatically assigned to a user who is in a firewall protected part of the site but who has not actually logged in. This is only possible if anonymous access has been allowed. IS_AUTHENTICATED_REMEMBERED - automatically assigned to a user who was authenticated via a remember me cookie. IS_AUTHENTICATED_FULLY - automatically assigned to a user that has provided their login details during the current session. You can use these to control access beyond the explicitly assigned roles.
If you have the IS_AUTHENTICATED_REMEMBERED role, then you also have the IS_AUTHENTICATED_ANONYMOUSLY role. If you have the IS_AUTHENTICATED_FULLY role, then you also have the other two roles. In other words, these roles represent three levels of increasing "strength" of authentication.

You can use these additional roles for finer grained control over access to parts of a site. For example, you may want your user to be able to view their account at /account when authenticated by cookie but to have to provide their login details to be able to edit the account details. You can do this by securing specific controller actions using these roles. The edit action in the controller could be secured using the service context. In the following example, the action is only allowed if the user has the IS_AUTHENTICATED_FULLY role.
Listing 76-3

1 2 3 4 5 6 7 8 9

// ... use Symfony\Component\Security\Core\Exception\AccessDeniedException

public function editAction() { if (false === $this->get('security.context')->isGranted( 'IS_AUTHENTICATED_FULLY' )) { throw new AccessDeniedException();

PDF brought to you by generated on February 10, 2014

Chapter 76: How to add "Remember Me" Login Functionality | 270

10 11 12 13 }

// ...

You can also choose to install and use the optional JMSSecurityExtraBundle1, which can secure your controller using annotations:
Listing 76-4

1 2 3 4 5 6 7 8 9

use JMS\SecurityExtraBundle\Annotation\Secure;

/** * @Secure(roles="IS_AUTHENTICATED_FULLY") */ public function editAction($name) { // ... }

If you also had an access control in your security configuration that required the user to have a ROLE_USER role in order to access any of the account area, then you'd have the following situation: If a non-authenticated (or anonymously authenticated user) tries to access the account area, the user will be asked to authenticate. Once the user has entered their username and password, assuming the user receives the ROLE_USER role per your configuration, the user will have the IS_AUTHENTICATED_FULLY role and be able to access any page in the account section, including the editAction controller. If the user's session ends, when the user returns to the site, they will be able to access every account page - except for the edit page - without being forced to re-authenticate. However, when they try to access the editAction controller, they will be forced to reauthenticate, since they are not, yet, fully authenticated.

For more information on securing services or methods in this way, see How to secure any Service or Method in your Application.

1. https://github.com/schmittjoh/JMSSecurityExtraBundle

PDF brought to you by generated on February 10, 2014

Chapter 76: How to add "Remember Me" Login Functionality | 271

Chapter 77

How to Impersonate a User

Sometimes, it's useful to be able to switch from one user to another without having to log out and log in again (for instance when you are debugging or trying to understand a bug a user sees that you can't reproduce). This can be easily done by activating the switch_user firewall listener:
Listing 77-1

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 # ... 6 switch_user: true

To switch to another user, just add a query string with the _switch_user parameter and the username as the value to the current URL:
Listing 77-2

1 http://example.com/somewhere?_switch_user=thomas

To switch back to the original user, use the special _exit username:
Listing 77-3

1 http://example.com/somewhere?_switch_user=_exit

During impersonation, the user is provided with a special role called ROLE_PREVIOUS_ADMIN. In a template, for instance, this role can be used to show a link to exit impersonation:
Listing 77-4

1 {% if is_granted('ROLE_PREVIOUS_ADMIN') %} 2 <a href="{{ path('homepage', {'_switch_user': '_exit'}) }}">Exit impersonation</a> 3 {% endif %}

Of course, this feature needs to be made available to a small group of users. By default, access is restricted to users having the ROLE_ALLOWED_TO_SWITCH role. The name of this role can be modified via the role setting. For extra security, you can also change the query parameter name via the parameter setting:
Listing 77-5

PDF brought to you by generated on February 10, 2014

Chapter 77: How to Impersonate a User | 272

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 # ... 6 switch_user: { role: ROLE_ADMIN, parameter: _want_to_be_this_user }

PDF brought to you by generated on February 10, 2014

Chapter 77: How to Impersonate a User | 273

Chapter 78

How to implement your own Voter to blacklist IP Addresses

The Symfony2 Security component provides several layers to authorize users. One of the layers is called a "voter". A voter is a dedicated class that checks if the user has the rights to connect to the application or access a specific resource/URL. For instance, Symfony2 provides a layer that checks if the user is fully authorized or if it has some expected roles. It is sometimes useful to create a custom voter to handle a specific case not handled by the framework. In this section, you'll learn how to create a voter that will allow you to blacklist users by their IP.

The Voter Interface

A custom voter must implement VoterInterface1, which requires the following three methods:
Listing 78-1

1 interface VoterInterface 2 { 3 public function supportsAttribute($attribute); 4 public function supportsClass($class); 5 public function vote(TokenInterface $token, $object, array $attributes); 6 }

The supportsAttribute() method is used to check if the voter supports the given user attribute (i.e: a role, an ACL, etc.). The supportsClass() method is used to check if the voter supports the class of the object whose access is being checked (doesn't apply to this entry). The vote() method must implement the business logic that verifies whether or not the user is granted access. This method must return one of the following values: VoterInterface::ACCESS_GRANTED: The authorization will be granted by this voter;

1. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authorization/Voter/VoterInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 78: How to implement your own Voter to blacklist IP Addresses | 274

 VoterInterface::ACCESS_ABSTAIN: The voter cannot decide if authorization should be granted; VoterInterface::ACCESS_DENIED: The authorization will be denied by this voter. In this example, you'll check if the user's IP address matches against a list of blacklisted addresses and "something" will be the application. If the user's IP is blacklisted, you'll return VoterInterface::ACCESS_DENIED, otherwise you'll return VoterInterface::ACCESS_ABSTAIN as this voter's purpose is only to deny access, not to grant access.

Creating a Custom Voter

To blacklist a user based on its IP, you can use the request service and compare the IP address against a set of blacklisted IP addresses:
Listing 78-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

// src/Acme/DemoBundle/Security/Authorization/Voter/ClientIpVoter.php namespace Acme\DemoBundle\Security\Authorization\Voter;

use Symfony\Component\HttpFoundation\RequestStack; use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface; use Symfony\Component\Security\Core\Authentication\Token\TokenInterface; class ClientIpVoter implements VoterInterface { protected $requestStack; private $blacklistedIp; public function __construct(RequestStack $requestStack, array $blacklistedIp = array()) { $this->requestStack = $requestStack; $this->blacklistedIp = $blacklistedIp; } public function supportsAttribute($attribute) { // you won't check against a user attribute, so return true return true; } public function supportsClass($class) { // your voter supports all type of token classes, so return true return true; } public function vote(TokenInterface $token, $object, array $attributes) { $request = $this->requestStack->getCurrentRequest(); if (in_array($request->getClientIp(), $this->blacklistedIp)) { return VoterInterface::ACCESS_DENIED; } return VoterInterface::ACCESS_ABSTAIN; } }

That's it! The voter is done. The next step is to inject the voter into the security layer. This can be done easily through the service container.

PDF brought to you by generated on February 10, 2014

Chapter 78: How to implement your own Voter to blacklist IP Addresses | 275

Your implementation of the methods supportsAttribute()2 and supportsClass()3 are not being called internally by the framework. Once you have registered your voter the vote() method will always be called, regardless of whether or not these two methods return true. Therefore you need to call those methods in your implementation of the vote() method and return ACCESS_ABSTAIN if your voter does not support the class or attribute.

Declaring the Voter as a Service

To inject the voter into the security layer, you must declare it as a service, and tag it as a security.voter:
Listing 78-3

1 # src/Acme/AcmeBundle/Resources/config/services.yml 2 services: 3 security.access.blacklist_voter: 4 class: Acme\DemoBundle\Security\Authorization\Voter\ClientIpVoter 5 arguments: ["@request_stack", [123.123.123.123, 171.171.171.171]] 6 public: false 7 tags: 8 - { name: security.voter }

Be sure to import this configuration file from your main application configuration file (e.g. app/ config/config.yml). For more information see Importing Configuration with imports. To read more about defining services in general, see the Service Container chapter.

Changing the Access Decision Strategy

In order for the new voter to take effect, you need to change the default access decision strategy, which, by default, grants access if any voter grants access. In this case, choose the unanimous strategy. Unlike the affirmative strategy (the default), with the unanimous strategy, if only one voter denies access (e.g. the ClientIpVoter), access is not granted to the end user. To do that, override the default access_decision_manager section of your application configuration file with the following code.
Listing 78-4

1 # app/config/security.yml 2 security: 3 access_decision_manager: 4 # strategy can be: affirmative, unanimous or consensus 5 strategy: unanimous

That's it! Now, when deciding whether or not a user should have access, the new voter will deny access to any user in the list of blacklisted IPs.
For a more advanced usage see Access Decision Manager.

2. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authorization/Voter/VoterInterface.html#supportsAttribute() 3. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authorization/Voter/VoterInterface.html#supportsClass()

PDF brought to you by generated on February 10, 2014

Chapter 78: How to implement your own Voter to blacklist IP Addresses | 276

Chapter 79

How to use Access Control Lists (ACLs)

In complex applications, you will often face the problem that access decisions cannot only be based on the person (Token) who is requesting access, but also involve a domain object that access is being requested for. This is where the ACL system comes in.

Alternatives to ACLs
Using ACL's isn't trivial, and for simpler use cases, it may be overkill. If your permission logic could be described by just writing some code (e.g. to check if a Blog is owned by the current User), then consider using voters. A voter is passed the object being voted on, which you can use to make complex decisions and effectively implement your own ACL. Enforcing authorization (e.g. the isGranted part) will look similar to what you see in this entry, but your voter class will handle the logic behind the scenes, instead of the ACL system.

Imagine you are designing a blog system where your users can comment on your posts. Now, you want a user to be able to edit their own comments, but not those of other users; besides, you yourself want to be able to edit all comments. In this scenario, Comment would be the domain object that you want to restrict access to. You could take several approaches to accomplish this using Symfony2, two basic approaches are (non-exhaustive): Enforce security in your business methods: Basically, that means keeping a reference inside each Comment to all users who have access, and then compare these users to the provided Token. Enforce security with roles: In this approach, you would add a role for each Comment object, i.e. ROLE_COMMENT_1, ROLE_COMMENT_2, etc. Both approaches are perfectly valid. However, they couple your authorization logic to your business code which makes it less reusable elsewhere, and also increases the difficulty of unit testing. Besides, you could run into performance issues if many users would have access to a single domain object. Fortunately, there is a better way, which you will find out about now.

PDF brought to you by generated on February 10, 2014

Chapter 79: How to use Access Control Lists (ACLs) | 277

Bootstrapping
Now, before you can finally get into action, you need to do some bootstrapping. First, you need to configure the connection the ACL system is supposed to use:
Listing 79-1

1 # app/config/security.yml 2 security: 3 acl: 4 connection: default

The ACL system requires a connection from either Doctrine DBAL (usable by default) or Doctrine MongoDB (usable with MongoDBAclBundle1). However, that does not mean that you have to use Doctrine ORM or ODM for mapping your domain objects. You can use whatever mapper you like for your objects, be it Doctrine ORM, MongoDB ODM, Propel, raw SQL, etc. The choice is yours.

After the connection is configured, you have to import the database structure. Fortunately, there is a task for this. Simply run the following command:
Listing 79-2

1 $ php app/console init:acl

Getting Started
Coming back to the small example from the beginning, you can now implement ACL for it.

Creating an ACL, and adding an ACE

Listing 79-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// src/Acme/DemoBundle/Controller/BlogController.php namespace Acme\DemoBundle\Controller;

use use use use use Symfony\Bundle\FrameworkBundle\Controller\Controller; Symfony\Component\Security\Core\Exception\AccessDeniedException; Symfony\Component\Security\Acl\Domain\ObjectIdentity; Symfony\Component\Security\Acl\Domain\UserSecurityIdentity; Symfony\Component\Security\Acl\Permission\MaskBuilder;

class BlogController { // ... public function addCommentAction(Post $post) { $comment = new Comment();

// ... setup $form, and submit data

if ($form->isValid()) { $entityManager = $this->getDoctrine()->getManager(); $entityManager->persist($comment); $entityManager->flush();

1. https://github.com/IamPersistent/MongoDBAclBundle

PDF brought to you by generated on February 10, 2014

Chapter 79: How to use Access Control Lists (ACLs) | 278

24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 }

// creating the ACL $aclProvider = $this->get('security.acl.provider'); $objectIdentity = ObjectIdentity::fromDomainObject($comment); $acl = $aclProvider->createAcl($objectIdentity); // retrieving the security identity of the currently logged-in user $securityContext = $this->get('security.context'); $user = $securityContext->getToken()->getUser(); $securityIdentity = UserSecurityIdentity::fromAccount($user); // grant owner access $acl->insertObjectAce($securityIdentity, MaskBuilder::MASK_OWNER); $aclProvider->updateAcl($acl);
} }

There are a couple of important implementation decisions in this code snippet. For now, I only want to highlight two: First, you may have noticed that ->createAcl() does not accept domain objects directly, but only implementations of the ObjectIdentityInterface. This additional step of indirection allows you to work with ACLs even when you have no actual domain object instance at hand. This will be extremely helpful if you want to check permissions for a large number of objects without actually hydrating these objects. The other interesting part is the ->insertObjectAce() call. In the example, you are granting the user who is currently logged in owner access to the Comment. The MaskBuilder::MASK_OWNER is a predefined integer bitmask; don't worry the mask builder will abstract away most of the technical details, but using this technique you can store many different permissions in one database row which gives a considerable boost in performance.
The order in which ACEs are checked is significant. As a general rule, you should place more specific entries at the beginning.

Checking Access
Listing 79-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

// src/Acme/DemoBundle/Controller/BlogController.php // ...
class BlogController { // ... public function editCommentAction(Comment $comment) { $securityContext = $this->get('security.context');

// check for edit access if (false === $securityContext->isGranted('EDIT', $comment)) { throw new AccessDeniedException(); }

PDF brought to you by generated on February 10, 2014

Chapter 79: How to use Access Control Lists (ACLs) | 279

17 18 19 20 }

// ... retrieve actual comment object, and do your editing here

}

In this example, you check whether the user has the EDIT permission. Internally, Symfony2 maps the permission to several integer bitmasks, and checks whether the user has any of them.
You can define up to 32 base permissions (depending on your OS PHP might vary between 30 to 32). In addition, you can also define cumulative permissions.

Cumulative Permissions
In the first example above, you only granted the user the OWNER base permission. While this effectively also allows the user to perform any operation such as view, edit, etc. on the domain object, there are cases where you may want to grant these permissions explicitly. The MaskBuilder can be used for creating bit masks easily by combining several base permissions:
Listing 79-5

1 2 3 4 5 6 7 8

$builder = new MaskBuilder(); $builder ->add('view') ->add('edit') ->add('delete') ->add('undelete') ; $mask = $builder->get(); // int(29)

This integer bitmask can then be used to grant a user the base permissions you added above:
Listing 79-6

1 $identity = new UserSecurityIdentity('johannes', 'Acme\UserBundle\Entity\User'); 2 $acl->insertObjectAce($identity, $mask);

The user is now allowed to view, edit, delete, and un-delete objects.

PDF brought to you by generated on February 10, 2014

Chapter 79: How to use Access Control Lists (ACLs) | 280

Chapter 80

How to use Advanced ACL Concepts

The aim of this chapter is to give a more in-depth view of the ACL system, and also explain some of the design decisions behind it.

Design Concepts
Symfony2's object instance security capabilities are based on the concept of an Access Control List. Every domain object instance has its own ACL. The ACL instance holds a detailed list of Access Control Entries (ACEs) which are used to make access decisions. Symfony2's ACL system focuses on two main objectives: providing a way to efficiently retrieve a large amount of ACLs/ACEs for your domain objects, and to modify them; providing a way to easily make decisions of whether a person is allowed to perform an action on a domain object or not. As indicated by the first point, one of the main capabilities of Symfony2's ACL system is a highperformance way of retrieving ACLs/ACEs. This is extremely important since each ACL might have several ACEs, and inherit from another ACL in a tree-like fashion. Therefore, no ORM is leveraged, instead the default implementation interacts with your connection directly using Doctrine's DBAL.

Object Identities
The ACL system is completely decoupled from your domain objects. They don't even have to be stored in the same database, or on the same server. In order to achieve this decoupling, in the ACL system your objects are represented through object identity objects. Every time you want to retrieve the ACL for a domain object, the ACL system will first create an object identity from your domain object, and then pass this object identity to the ACL provider for further processing.

Security Identities
This is analog to the object identity, but represents a user, or a role in your application. Each role, or user has its own security identity.

PDF brought to you by generated on February 10, 2014

Chapter 80: How to use Advanced ACL Concepts | 281

Database Table Structure

The default implementation uses five database tables as listed below. The tables are ordered from least rows to most rows in a typical application: acl_security_identities: This table records all security identities (SID) which hold ACEs. The default implementation ships with two security identities: RoleSecurityIdentity1 and UserSecurityIdentity2. acl_classes: This table maps class names to a unique ID which can be referenced from other tables. acl_object_identities: Each row in this table represents a single domain object instance. acl_object_identity_ancestors: This table allows all the ancestors of an ACL to be determined in a very efficient way. acl_entries: This table contains all ACEs. This is typically the table with the most rows. It can contain tens of millions without significantly impacting performance.

Scope of Access Control Entries

Access control entries can have different scopes in which they apply. In Symfony2, there are basically two different scopes: Class-Scope: These entries apply to all objects with the same class. Object-Scope: This was the scope solely used in the previous chapter, and it only applies to one specific object. Sometimes, you will find the need to apply an ACE only to a specific field of the object. Suppose you want the ID only to be viewable by an administrator, but not by your customer service. To solve this common problem, two more sub-scopes have been added: Class-Field-Scope: These entries apply to all objects with the same class, but only to a specific field of the objects. Object-Field-Scope: These entries apply to a specific object, and only to a specific field of that object.

Pre-Authorization Decisions
For pre-authorization decisions, that is decisions made before any secure method (or secure action) is invoked, the proven AccessDecisionManager service is used. The AccessDecisionManager is also used for reaching authorization decisions based on roles. Just like roles, the ACL system adds several new attributes which may be used to check for different permissions.

Built-in Permission Map

Attribute VIEW EDIT Intended Meaning Whether someone is allowed to view the domain object. Integer Bitmasks VIEW, EDIT, OPERATOR, MASTER, or OWNER

Whether someone is allowed to EDIT, OPERATOR, MASTER, or make changes to the domain object. OWNER

1. http://api.symfony.com/2.4/Symfony/Component/Security/Acl/Domain/RoleSecurityIdentity.html 2. http://api.symfony.com/2.4/Symfony/Component/Security/Acl/Domain/UserSecurityIdentity.html

PDF brought to you by generated on February 10, 2014

Chapter 80: How to use Advanced ACL Concepts | 282

Attribute CREATE DELETE UNDELETE

Intended Meaning Whether someone is allowed to create the domain object. Whether someone is allowed to delete the domain object. Whether someone is allowed to restore a previously deleted domain object. Whether someone is allowed to perform all of the above actions. Whether someone is allowed to perform all of the above actions, and in addition is allowed to grant any of the above permissions to others. Whether someone owns the domain object. An owner can perform any of the above actions and grant master and owner permissions.

Integer Bitmasks CREATE, OPERATOR, MASTER, or OWNER DELETE, OPERATOR, MASTER, or OWNER UNDELETE, OPERATOR, MASTER, or OWNER OPERATOR, MASTER, or OWNER MASTER, or OWNER

OPERATOR MASTER

OWNER

OWNER

Permission Attributes vs. Permission Bitmasks

Attributes are used by the AccessDecisionManager, just like roles. Often, these attributes represent in fact an aggregate of integer bitmasks. Integer bitmasks on the other hand, are used by the ACL system internally to efficiently store your users' permissions in the database, and perform access checks using extremely fast bitmask operations.

Extensibility
The above permission map is by no means static, and theoretically could be completely replaced at will. However, it should cover most problems you encounter, and for interoperability with other bundles, you are encouraged to stick to the meaning envisaged for them.

Post Authorization Decisions

Post authorization decisions are made after a secure method has been invoked, and typically involve the domain object which is returned by such a method. After invocation providers also allow to modify, or filter the domain object before it is returned. Due to current limitations of the PHP language, there are no post-authorization capabilities build into the core Security component. However, there is an experimental JMSSecurityExtraBundle3 which adds these capabilities. See its documentation for further information on how this is accomplished.

3. https://github.com/schmittjoh/JMSSecurityExtraBundle

PDF brought to you by generated on February 10, 2014

Chapter 80: How to use Advanced ACL Concepts | 283

Process for Reaching Authorization Decisions

The ACL class provides two methods for determining whether a security identity has the required bitmasks, isGranted and isFieldGranted. When the ACL receives an authorization request through one of these methods, it delegates this request to an implementation of PermissionGrantingStrategy4. This allows you to replace the way access decisions are reached without actually modifying the ACL class itself. The PermissionGrantingStrategy first checks all your object-scope ACEs. If none is applicable, the class-scope ACEs will be checked. If none is applicable, then the process will be repeated with the ACEs of the parent ACL. If no parent ACL exists, an exception will be thrown.

4. http://api.symfony.com/2.4/Symfony/Component/Security/Acl/Domain/PermissionGrantingStrategy.html

PDF brought to you by generated on February 10, 2014

Chapter 80: How to use Advanced ACL Concepts | 284

Chapter 81

How to force HTTPS or HTTP for Different URLs

You can force areas of your site to use the HTTPS protocol in the security config. This is done through the access_control rules using the requires_channel option. For example, if you want to force all URLs starting with /secure to use HTTPS then you could use the following configuration:
Listing 81-1

1 access_control: 2 - { path: ^/secure, roles: ROLE_ADMIN, requires_channel: https }

The login form itself needs to allow anonymous access, otherwise users will be unable to authenticate. To force it to use HTTPS you can still use access_control rules by using the IS_AUTHENTICATED_ANONYMOUSLY role:
Listing 81-2

1 access_control: 2 - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channel: https }

It is also possible to specify using HTTPS in the routing configuration, see How to force routes to always use HTTPS or HTTP for more details.

PDF brought to you by generated on February 10, 2014

Chapter 81: How to force HTTPS or HTTP for Different URLs | 285

Chapter 82

How to Restrict Firewalls to a Specific Host

New in version 2.4: Support for restricting security firewalls to a specific host was introduced in Symfony 2.4.

When using the Security component, you can create firewalls that match certain URL patterns and therefore are activated for all pages whose URL matches that pattern. Additionally, you can restrict the initialization of a firewall to a host using the host key:
Listing 82-1

1 # app/config/security.yml 2 3 # ... 4 5 security: 6 firewalls: 7 secured_area: 8 pattern: ^/ 9 host: ^admin\.example\.com$ 10 http_basic: true

The host (like the pattern) is a regular expression. In this example, the firewall will only be activated if the host is equal exactly (due to the ^ and $ regex characters) to the hostname admin.example.com. If the hostname does not match this pattern, the firewall will not be activated and subsequent firewalls will have the opportunity to be matched for this request.

PDF brought to you by generated on February 10, 2014

Chapter 82: How to Restrict Firewalls to a Specific Host | 286

Chapter 83

How to customize your Form Login

Using a form login for authentication is a common, and flexible, method for handling authentication in Symfony2. Pretty much every aspect of the form login can be customized. The full, default configuration is shown in the next section.

Form Login Configuration Reference

To see the full form login configuration reference, see SecurityBundle Configuration ("security"). Some of the more interesting options are explained below.

Redirecting after Success

You can change where the login form redirects after a successful login using the various config options. By default the form will redirect to the URL the user requested (i.e. the URL which triggered the login form being shown). For example, if the user requested http://www.example.com/admin/post/18/edit, then after they successfully log in, they will eventually be sent back to http://www.example.com/admin/ post/18/edit. This is done by storing the requested URL in the session. If no URL is present in the session (perhaps the user went directly to the login page), then the user is redirected to the default page, which is / (i.e. the homepage) by default. You can change this behavior in several ways.
As mentioned, by default the user is redirected back to the page originally requested. Sometimes, this can cause problems, like if a background Ajax request "appears" to be the last visited URL, causing the user to be redirected there. For information on controlling this behavior, see How to change the Default Target Path Behavior.

Changing the Default Page

First, the default page can be set (i.e. the page the user is redirected to if no previous page was stored in the session). To set it to the default_security_target route use the following config:
Listing 83-1

PDF brought to you by generated on February 10, 2014

Chapter 83: How to customize your Form Login | 287

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 form_login: 6 # ... 7 default_target_path: default_security_target

Now, when no URL is set in the session, users will be sent to the default_security_target route.

Always Redirect to the Default Page

You can make it so that users are always redirected to the default page regardless of what URL they had requested previously by setting the always_use_default_target_path option to true:
Listing 83-2

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 form_login: 6 # ... 7 always_use_default_target_path: true

Using the Referring URL

In case no previous URL was stored in the session, you may wish to try using the HTTP_REFERER instead, as this will often be the same. You can do this by setting use_referer to true (it defaults to false):
Listing 83-3

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 form_login: 6 # ... 7 use_referer:

true

Control the Redirect URL from inside the Form

You can also override where the user is redirected to via the form itself by including a hidden field with the name _target_path. For example, to redirect to the URL defined by some account route, use the following:
Listing 83-4

1 2 3 4 5 6 7 8 9 10 11

{# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #} {% if error %} <div>{{ error.message }}</div> {% endif %}

<form action="{{ path('login_check') }}" method="post"> <label for="username">Username:</label> <input type="text" id="username" name="_username" value="{{ last_username }}" /> <label for="password">Password:</label> <input type="password" id="password" name="_password" />

PDF brought to you by generated on February 10, 2014

Chapter 83: How to customize your Form Login | 288

12 13 <input type="hidden" name="_target_path" value="account" /> 14 15 <input type="submit" name="login" /> 16 </form>

Now, the user will be redirected to the value of the hidden form field. The value attribute can be a relative path, absolute URL, or a route name. You can even change the name of the hidden form field by changing the target_path_parameter option to another value.
Listing 83-5

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 form_login: 6 target_path_parameter: redirect_url

Redirecting on Login Failure

In addition to redirecting the user after a successful login, you can also set the URL that the user should be redirected to after a failed login (e.g. an invalid username or password was submitted). By default, the user is redirected back to the login form itself. You can set this to a different route (e.g. login_failure) with the following config:
Listing 83-6

1 # app/config/security.yml 2 security: 3 firewalls: 4 main: 5 form_login: 6 # ... 7 failure_path: login_failure

PDF brought to you by generated on February 10, 2014

Chapter 83: How to customize your Form Login | 289

Chapter 84

How to secure any Service or Method in your Application

In the security chapter, you can see how to secure a controller by requesting the security.context service from the Service Container and checking the current user's role:
Listing 84-1

1 2 3 4 5 6 7 8 9 10 11

// ... use Symfony\Component\Security\Core\Exception\AccessDeniedException;

public function helloAction($name) { if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) { throw new AccessDeniedException(); }

// ...
}

You can also secure any service in a similar way by injecting the security.context service into it. For a general introduction to injecting dependencies into services see the Service Container chapter of the book. For example, suppose you have a NewsletterManager class that sends out emails and you want to restrict its use to only users who have some ROLE_NEWSLETTER_ADMIN role. Before you add security, the class looks something like this:
Listing 84-2

1 2 3 4 5 6 7 8 9 10

// src/Acme/HelloBundle/Newsletter/NewsletterManager.php namespace Acme\HelloBundle\Newsletter;

class NewsletterManager { public function sendNewsletter() { // ... where you actually do the work }

PDF brought to you by generated on February 10, 2014

Chapter 84: How to secure any Service or Method in your Application | 290

11 12 13 }

// ...

Your goal is to check the user's role when the sendNewsletter() method is called. The first step towards this is to inject the security.context service into the object. Since it won't make sense not to perform the security check, this is an ideal candidate for constructor injection, which guarantees that the security context object will be available inside the NewsletterManager class:
Listing 84-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

namespace Acme\HelloBundle\Newsletter; use Symfony\Component\Security\Core\SecurityContextInterface; class NewsletterManager { protected $securityContext; public function __construct(SecurityContextInterface $securityContext) { $this->securityContext = $securityContext; }

// ...
}

Then in your service configuration, you can inject the service:

Listing 84-4

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 parameters: 3 newsletter_manager.class: Acme\HelloBundle\Newsletter\NewsletterManager 4 5 services: 6 newsletter_manager: 7 class: "%newsletter_manager.class%" 8 arguments: ["@security.context"]

The injected service can then be used to perform the security check when the sendNewsletter() method is called:
Listing 84-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

namespace Acme\HelloBundle\Newsletter; use Symfony\Component\Security\Core\Exception\AccessDeniedException; use Symfony\Component\Security\Core\SecurityContextInterface; // ... class NewsletterManager { protected $securityContext; public function __construct(SecurityContextInterface $securityContext) { $this->securityContext = $securityContext; } public function sendNewsletter() {

PDF brought to you by generated on February 10, 2014

Chapter 84: How to secure any Service or Method in your Application | 291

18 19 20 21 22 23 24 25 26 }

if (false === $this->securityContext->isGranted('ROLE_NEWSLETTER_ADMIN')) { throw new AccessDeniedException(); }

// ...
}

// ...

If the current user does not have the ROLE_NEWSLETTER_ADMIN, they will be prompted to log in.

Securing Methods Using Annotations

You can also secure method calls in any service with annotations by using the optional JMSSecurityExtraBundle1 bundle. This bundle is not included in the Symfony2 Standard Distribution, but you can choose to install it. To enable the annotations functionality, tag the service you want to secure with the security.secure_service tag (you can also automatically enable this functionality for all services, see the sidebar below):
Listing 84-6

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 3 # ... 4 services: 5 newsletter_manager: 6 # ... 7 tags: 8 - { name: security.secure_service }

You can then achieve the same results as above using an annotation:
Listing 84-7

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

namespace Acme\HelloBundle\Newsletter; use JMS\SecurityExtraBundle\Annotation\Secure; // ... class NewsletterManager {

/** * @Secure(roles="ROLE_NEWSLETTER_ADMIN") */ public function sendNewsletter() { // ... } // ...

}

1. https://github.com/schmittjoh/JMSSecurityExtraBundle

PDF brought to you by generated on February 10, 2014

Chapter 84: How to secure any Service or Method in your Application | 292

The annotations work because a proxy class is created for your class which performs the security checks. This means that, whilst you can use annotations on public and protected methods, you cannot use them with private methods or methods marked final.

The JMSSecurityExtraBundle also allows you to secure the parameters and return values of methods. For more information, see the JMSSecurityExtraBundle2 documentation.

Activating the Annotations Functionality for all Services

When securing the method of a service (as shown above), you can either tag each service individually, or activate the functionality for all services at once. To do so, set the secure_all_services configuration option to true:
Listing 84-8

1 # app/config/config.yml 2 jms_security_extra: 3 # ... 4 secure_all_services: true

The disadvantage of this method is that, if activated, the initial page load may be very slow depending on how many services you have defined.

2. https://github.com/schmittjoh/JMSSecurityExtraBundle

PDF brought to you by generated on February 10, 2014

Chapter 84: How to secure any Service or Method in your Application | 293

Chapter 85

How to create a custom User Provider

Part of Symfony's standard authentication process depends on "user providers". When a user submits a username and password, the authentication layer asks the configured user provider to return a user object for a given username. Symfony then checks whether the password of this user is correct and generates a security token so the user stays authenticated during the current session. Out of the box, Symfony has an "in_memory" and an "entity" user provider. In this entry you'll see how you can create your own user provider, which could be useful if your users are accessed via a custom database, a file, or - as shown in this example - a web service.

Create a User Class

First, regardless of where your user data is coming from, you'll need to create a User class that represents that data. The User can look however you want and contain any data. The only requirement is that the class implements UserInterface1. The methods in this interface should therefore be defined in the custom user class: getRoles()2, getPassword()3, getSalt()4, getUsername()5, eraseCredentials()6. It may also be useful to implement the EquatableInterface7 interface, which defines a method to check if the user is equal to the current user. This interface requires an isEqualTo()8 method. This is how your WebserviceUser class looks in action:
Listing 85-1

1 2 3 4 5 6

// src/Acme/WebserviceUserBundle/Security/User/WebserviceUser.php namespace Acme\WebserviceUserBundle\Security\User;

use Symfony\Component\Security\Core\User\UserInterface; use Symfony\Component\Security\Core\User\EquatableInterface;

1. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html 2. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html#getRoles() 3. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html#getPassword() 4. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html#getSalt() 5. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html#getUsername() 6. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserInterface.html#eraseCredentials() 7. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/EquatableInterface.html 8. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/EquatableInterface.html#isEqualTo()

PDF brought to you by generated on February 10, 2014

Chapter 85: How to create a custom User Provider | 294

7 class WebserviceUser implements UserInterface, EquatableInterface 8 { 9 private $username; 10 private $password; 11 private $salt; 12 private $roles; 13 14 public function __construct($username, $password, $salt, array $roles) 15 { 16 $this->username = $username; 17 $this->password = $password; 18 $this->salt = $salt; 19 $this->roles = $roles; 20 } 21 22 public function getRoles() 23 { 24 return $this->roles; 25 } 26 27 public function getPassword() 28 { 29 return $this->password; 30 } 31 32 public function getSalt() 33 { 34 return $this->salt; 35 } 36 37 public function getUsername() 38 { 39 return $this->username; 40 } 41 42 public function eraseCredentials() 43 { 44 } 45 46 public function isEqualTo(UserInterface $user) 47 { 48 if (!$user instanceof WebserviceUser) { 49 return false; 50 } 51 52 if ($this->password !== $user->getPassword()) { 53 return false; 54 } 55 56 if ($this->getSalt() !== $user->getSalt()) { 57 return false; 58 } 59 60 if ($this->username !== $user->getUsername()) { 61 return false; 62 } 63 64 return true;

PDF brought to you by generated on February 10, 2014

Chapter 85: How to create a custom User Provider | 295

65 66 }

If you have more information about your users - like a "first name" - then you can add a firstName field to hold that data.

Create a User Provider

Now that you have a User class, you'll create a user provider, which will grab user information from some web service, create a WebserviceUser object, and populate it with data. The user provider is just a plain PHP class that has to implement the UserProviderInterface9, which requires three methods to be defined: loadUserByUsername($username), refreshUser(UserInterface $user), and supportsClass($class). For more details, see UserProviderInterface10. Here's an example of how this might look:
Listing 85-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

// src/Acme/WebserviceUserBundle/Security/User/WebserviceUserProvider.php namespace Acme\WebserviceUserBundle\Security\User;

use use use use Symfony\Component\Security\Core\User\UserProviderInterface; Symfony\Component\Security\Core\User\UserInterface; Symfony\Component\Security\Core\Exception\UsernameNotFoundException; Symfony\Component\Security\Core\Exception\UnsupportedUserException;

class WebserviceUserProvider implements UserProviderInterface { public function loadUserByUsername($username) { // make a call to your webservice here $userData = ... // pretend it returns an array on success, false if there is no user if ($userData) { $password = '...';

// ...
return new WebserviceUser($username, $password, $salt, $roles); } throw new UsernameNotFoundException( sprintf('Username "%s" does not exist.', $username) ); } public function refreshUser(UserInterface $user) { if (!$user instanceof WebserviceUser) { throw new UnsupportedUserException( sprintf('Instances of "%s" are not supported.', get_class($user)) ); }

9. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserProviderInterface.html 10. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/UserProviderInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 85: How to create a custom User Provider | 296

38 39 40 41 42 43 44 45 }

return $this->loadUserByUsername($user->getUsername()); } public function supportsClass($class) { return $class === 'Acme\WebserviceUserBundle\Security\User\WebserviceUser'; }

Create a Service for the User Provider

Now you make the user provider available as a service:
Listing 85-3

1 2 3 4 5 6 7

# src/Acme/WebserviceUserBundle/Resources/config/services.yml parameters: webservice_user_provider.class: Acme\WebserviceUserBundle\Security\User\WebserviceUserProvider

services: webservice_user_provider: class: "%webservice_user_provider.class%"

The real implementation of the user provider will probably have some dependencies or configuration options or other services. Add these as arguments in the service definition.

Make sure the services file is being imported. See Importing Configuration with imports for details.

Modify security.yml
Everything comes together in your security configuration. Add the user provider to the list of providers in the "security" section. Choose a name for the user provider (e.g. "webservice") and mention the id of the service you just defined.
Listing 85-4

1 # app/config/security.yml 2 security: 3 providers: 4 webservice: 5 id: webservice_user_provider

Symfony also needs to know how to encode passwords that are supplied by website users, e.g. by filling in a login form. You can do this by adding a line to the "encoders" section in your security configuration:
Listing 85-5

1 # app/config/security.yml 2 security:

PDF brought to you by generated on February 10, 2014

Chapter 85: How to create a custom User Provider | 297

3 4

encoders: Acme\WebserviceUserBundle\Security\User\WebserviceUser: sha512

The value here should correspond with however the passwords were originally encoded when creating your users (however those users were created). When a user submits their password, the salt value is appended to the password and then encoded using this algorithm before being compared to the hashed password returned by your getPassword() method. Additionally, depending on your options, the password may be encoded multiple times and encoded to base64.

Specifics on how passwords are encoded

Symfony uses a specific method to combine the salt and encode the password before comparing it to your encoded password. If getSalt() returns nothing, then the submitted password is simply encoded using the algorithm you specify in security.yml. If a salt is specified, then the following value is created and then hashed via the algorithm: $password.'{'.$salt.'}'; If your external users have their passwords salted via a different method, then you'll need to do a bit more work so that Symfony properly encodes the password. That is beyond the scope of this entry, but would include sub-classing MessageDigestPasswordEncoder and overriding the mergePasswordAndSalt method. Additionally, the hash, by default, is encoded multiple times and encoded to base64. For specific details, see MessageDigestPasswordEncoder11. To prevent this, configure it in your configuration file:
Listing 85-6

1 # app/config/security.yml 2 security: 3 encoders: 4 Acme\WebserviceUserBundle\Security\User\WebserviceUser: 5 algorithm: sha512 6 encode_as_base64: false 7 iterations: 1

11. https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Core/Encoder/MessageDigestPasswordEncoder.php

PDF brought to you by generated on February 10, 2014

Chapter 85: How to create a custom User Provider | 298

Chapter 86

How to Create a Custom Form Password Authenticator

Imagine you want to allow access to your website only between 2pm and 4pm UTC. Before Symfony 2.4, you had to create a custom token, factory, listener and provider. In this entry, you'll learn how to do this for a login form (i.e. where your user submits their username and password).

The Password Authenticator

New in version 2.4: The SimpleFormAuthenticatorInterface interface was added in Symfony 2.4.

First, create a new class that implements SimpleFormAuthenticatorInterface1. Eventually, this will allow you to create custom logic for authenticating the user:
Listing 86-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// src/Acme/HelloBundle/Security/TimeAuthenticator.php namespace Acme\HelloBundle\Security;

use use use use use use use use Symfony\Component\HttpFoundation\Request; Symfony\Component\Security\Core\Authentication\SimpleFormAuthenticatorInterface; Symfony\Component\Security\Core\Authentication\Token\TokenInterface; Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken; Symfony\Component\Security\Core\Encoder\EncoderFactoryInterface; Symfony\Component\Security\Core\Exception\AuthenticationException; Symfony\Component\Security\Core\Exception\UsernameNotFoundException; Symfony\Component\Security\Core\User\UserProviderInterface;

class TimeAuthenticator implements SimpleFormAuthenticatorInterface {

1. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authentication/SimpleFormAuthenticatorInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 86: How to Create a Custom Form Password Authenticator | 299

15 private $encoderFactory; 16 17 public function __construct(EncoderFactoryInterface $encoderFactory) 18 { 19 $this->encoderFactory = $encoderFactory; 20 } 21 22 public function authenticateToken(TokenInterface $token, UserProviderInterface 23 $userProvider, $providerKey) 24 { 25 try { 26 $user = $userProvider->loadUserByUsername($token->getUsername()); 27 } catch (UsernameNotFoundException $e) { 28 throw new AuthenticationException('Invalid username or password'); 29 } 30 31 $encoder = $this->encoderFactory->getEncoder($user); 32 $passwordValid = $encoder->isPasswordValid( 33 $user->getPassword(), 34 $token->getCredentials(), 35 $user->getSalt() 36 ); 37 38 if ($passwordValid) { 39 $currentHour = date('G'); 40 if ($currentHour < 14 || $currentHour > 16) { 41 throw new AuthenticationException( 42 'You can only log in between 2 and 4!', 43 100 44 ); 45 } 46 47 return new UsernamePasswordToken( 48 $user, 49 $user->getPassword(), 50 $providerKey, 51 $user->getRoles() 52 ); 53 } 54 55 throw new AuthenticationException('Invalid username or password'); 56 } 57 58 public function supportsToken(TokenInterface $token, $providerKey) 59 { 60 return $token instanceof UsernamePasswordToken 61 && $token->getProviderKey() === $providerKey; 62 } 63 64 public function createToken(Request $request, $username, $password, $providerKey) 65 { 66 return new UsernamePasswordToken($username, $password, $providerKey); 67 } }

PDF brought to you by generated on February 10, 2014

Chapter 86: How to Create a Custom Form Password Authenticator | 300

How it Works
Great! Now you just need to setup some Configuration. But first, you can find out more about what each method in this class does.

1) createToken
When Symfony begins handling a request, createToken() is called, where you create a TokenInterface2 object that contains whatever information you need in authenticateToken() to authenticate the user (e.g. the username and password). Whatever token object you create here will be passed to you later in authenticateToken().

2) supportsToken
After Symfony calls createToken(), it will then call supportsToken() on your class (and any other authentication listeners) to figure out who should handle the token. This is just a way to allow several authentication mechanisms to be used for the same firewall (that way, you can for instance first try to authenticate the user via a certificate or an API key and fall back to a form login). Mostly, you just need to make sure that this method returns true for a token that has been created by createToken(). Your logic should probably look exactly like this example.

3) authenticateToken
If supportsToken returns true, Symfony will now call authenticateToken(). Your job here is to check that the token is allowed to log in by first getting the User object via the user provider and then, by checking the password and the current time.
The "flow" of how you get the User object and determine whether or not the token is valid (e.g. checking the password), may vary based on your requirements.

Ultimately, your job is to return a new token object that is "authenticated" (i.e. it has at least 1 role set on it) and which has the User object inside of it. Inside this method, an encoder is needed to check the password's validity:
Listing 86-2

1 $encoder = $this->encoderFactory->getEncoder($user); 2 $passwordValid = $encoder->isPasswordValid( 3 $user->getPassword(), 4 $token->getCredentials(), 5 $user->getSalt() 6 );

This is a service that is already available in Symfony and the password algorithm is configured in the security configuration (e.g. security.yml) under the encoders key. Below, you'll see how to inject that into the TimeAuthenticator.

Configuration
Now, configure your TimeAuthenticator as a service:
2. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authentication/Token/TokenInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 86: How to Create a Custom Form Password Authenticator | 301

Listing 86-3

1 # app/config/config.yml 2 services: 3 # ... 4 5 time_authenticator: 6 class: Acme\HelloBundle\Security\TimeAuthenticator 7 arguments: ["@security.encoder_factory"]

Then, activate it in the firewalls section of the security configuration using the simple_form key:
Listing 86-4

1 # app/config/security.yml 2 security: 3 # ... 4 5 firewalls: 6 secured_area: 7 pattern: ^/admin 8 # ... 9 simple_form: 10 authenticator: time_authenticator 11 check_path: login_check 12 login_path: login

The simple_form key has the same options as the normal form_login option, but with the additional authenticator key that points to the new service. For details, see Form Login Configuration. If creating a login form in general is new to you or you don't understand the check_path or login_path options, see How to customize your Form Login.

PDF brought to you by generated on February 10, 2014

Chapter 86: How to Create a Custom Form Password Authenticator | 302

Chapter 87

How to Authenticate Users with API Keys

Nowadays, it's quite usual to authenticate the user via an API key (when developing a web service for instance). The API key is provided for every request and is passed as a query string parameter or via an HTTP header.

The API Key Authenticator

New in version 2.4: The SimplePreAuthenticatorInterface interface was added in Symfony 2.4.

Authenticating a user based on the Request information should be done via a pre-authentication mechanism. The SimplePreAuthenticatorInterface1 allows you to implement such a scheme really easily. Your exact situation may differ, but in this example, a token is read from an apikey query parameter, the proper username is loaded from that value and then a User object is created:
Listing 87-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php namespace Acme\HelloBundle\Security;

use use use use use use use use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface; Symfony\Component\Security\Core\Authentication\Token\TokenInterface; Symfony\Component\Security\Core\Exception\AuthenticationException; Symfony\Component\Security\Core\Authentication\Token\PreAuthenticatedToken; Symfony\Component\HttpFoundation\Request; Symfony\Component\Security\Core\User\UserProviderInterface; Symfony\Component\Security\Core\Exception\UsernameNotFoundException; Symfony\Component\Security\Core\Exception\BadCredentialsException;

class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface {

1. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authentication/SimplePreAuthenticatorInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 87: How to Authenticate Users with API Keys | 303

15 protected $userProvider; 16 17 public function __construct(ApiKeyUserProvider $userProvider) 18 { 19 $this->userProvider = $userProvider; 20 } 21 22 public function createToken(Request $request, $providerKey) 23 { 24 if (!$request->query->has('apikey')) { 25 throw new BadCredentialsException('No API key found'); 26 } 27 28 return new PreAuthenticatedToken( 29 'anon.', 30 $request->query->get('apikey'), 31 $providerKey 32 ); 33 } 34 35 public function authenticateToken(TokenInterface $token, UserProviderInterface 36 $userProvider, $providerKey) 37 { 38 $apiKey = $token->getCredentials(); 39 $username = $this->userProvider->getUsernameForApiKey($apiKey); 40 41 if (!$username) { 42 throw new AuthenticationException( 43 sprintf('API Key "%s" does not exist.', $apiKey) 44 ); 45 } 46 47 $user = $this->userProvider->loadUserByUsername($username); 48 49 return new PreAuthenticatedToken( 50 $user, 51 $apiKey, 52 $providerKey, 53 $user->getRoles() 54 ); 55 } 56 57 public function supportsToken(TokenInterface $token, $providerKey) 58 { 59 return $token instanceof PreAuthenticatedToken && $token->getProviderKey() === 60 $providerKey; } }

Once you've configured everything, you'll be able to authenticate by adding an apikey parameter to the query string, like http://example.com/admin/foo?apikey=37b51d194a7513e45b56f6524f2d51f2. The authentication process has several steps, and your implementation will probably differ:

1. createToken
Early in the request cycle, Symfony calls createToken(). Your job here is to create a token object that contains all of the information from the request that you need to authenticate the user (e.g. the

PDF brought to you by generated on February 10, 2014

Chapter 87: How to Authenticate Users with API Keys | 304

apikey query parameter). If that information is missing, throwing a BadCredentialsException2 will cause authentication to fail.

2. supportsToken
After Symfony calls createToken(), it will then call supportsToken() on your class (and any other authentication listeners) to figure out who should handle the token. This is just a way to allow several authentication mechanisms to be used for the same firewall (that way, you can for instance first try to authenticate the user via a certificate or an API key and fall back to a form login). Mostly, you just need to make sure that this method returns true for a token that has been created by createToken(). Your logic should probably look exactly like this example.

3. authenticateToken
If supportsToken() returns true, Symfony will now call authenticateToken(). One key part is the $userProvider, which is an external class that helps you load information about the user. You'll learn more about this next. In this specific example, the following things happen in authenticateToken(): 1. First, you use the $userProvider to somehow look up the $username that corresponds to the $apiKey; 2. Second, you use the $userProvider again to load or create a User object for the $username; 3. Finally, you create an authenticated token (i.e. a token with at least one role) that has the proper roles and the User object attached to it. The goal is ultimately to use the $apiKey to find or create a User object. How you do this (e.g. query a database) and the exact class for your User object may vary. Those differences will be most obvious in your user provider.

The User Provider

The $userProvider can be any user provider (see How to create a custom User Provider). In this example, the $apiKey is used to somehow find the username for the user. This work is done in a getUsernameForApiKey() method, which is created entirely custom for this use-case (i.e. this isn't a method that's used by Symfony's core user provider system). The $userProvider might look something like this:
Listing 87-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/HelloBundle/Security/ApiKeyUserProvider.php namespace Acme\HelloBundle\Security;

use use use use Symfony\Component\Security\Core\User\UserProviderInterface; Symfony\Component\Security\Core\User\User; Symfony\Component\Security\Core\User\UserInterface; Symfony\Component\Security\Core\Exception\UnsupportedUserException;

class ApiKeyUserProvider implements UserProviderInterface { public function getUsernameForApiKey($apiKey) { // Look up the username based on the token in the database, via // an API call, or do something entirely different $username = ...; return $username;

2. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Exception/BadCredentialsException.html

PDF brought to you by generated on February 10, 2014

Chapter 87: How to Authenticate Users with API Keys | 305

18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 }

} public function loadUserByUsername($username) { return new User( $username, null, // the roles for the user - you may choose to determine // these dynamically somehow based on the user array('ROLE_USER') ); } public function refreshUser(UserInterface $user) { // this is used for storing authentication in the session // but in this example, the token is sent in each request, // so authentication can be stateless. Throwing this exception // is proper to make things stateless throw new UnsupportedUserException(); } public function supportsClass($class) { return 'Symfony\Component\Security\Core\User\User' === $class; }

Read the dedicated article to learn how to create a custom user provider.

The logic inside getUsernameForApiKey() is up to you. You may somehow transform the API key (e.g. 37b51d) into a username (e.g. jondoe) by looking up some information in a "token" database table. The same is true for loadUserByUsername(). In this example, Symfony's core User3 class is simply created. This makes sense if you don't need to store any extra information on your User object (e.g. firstName). But if you do, you may instead have your own user class which you create and populate here by querying a database. This would allow you to have custom data on the User object. Finally, just make sure that supportsClass() returns true for User objects with the same class as whatever user you return in loadUserByUsername(). If your authentication is stateless like in this example (i.e. you expect the user to send the API key with every request and so you don't save the login to the session), then you can simply throw the UnsupportedUserException exception in refreshUser().
If you do want to store authentication data in the session so that the key doesn't need to be sent on every request, see Storing Authentication in the Session.

3. http://api.symfony.com/2.4/Symfony/Component/Security/Core/User/User.html

PDF brought to you by generated on February 10, 2014

Chapter 87: How to Authenticate Users with API Keys | 306

Configuration
Once you have your ApiKeyAuthentication all setup, you need to register it as a service and use it in your security configuration (e.g. security.yml). First, register it as a service. This assumes that you have already setup your custom user provider as a service called your_api_key_user_provider (see How to create a custom User Provider).
Listing 87-3

1 # app/config/config.yml 2 services: 3 # ... 4 5 apikey_authenticator: 6 class: Acme\HelloBundle\Security\ApiKeyAuthenticator 7 arguments: ["@your_api_key_user_provider"]

Now, activate it in the firewalls section of your security configuration using the simple_preauth key:
Listing 87-4

1 # app/config/security.yml 2 security: 3 # ... 4 5 firewalls: 6 secured_area: 7 pattern: ^/admin 8 stateless: true 9 simple_preauth: 10 authenticator: apikey_authenticator

That's it! Now, your ApiKeyAuthentication should be called at the beginning of each request and your authentication process will take place. The stateless configuration parameter prevents Symfony from trying to store the authentication information in the session, which isn't necessary since the client will send the apikey on each request. If you do need to store authentication in the session, keep reading!

Storing Authentication in the Session

So far, this entry has described a situation where some sort of authentication token is sent on every request. But in some situations (like an OAuth flow), the token may be sent on only one request. In this case, you will want to authenticate the user and store that authentication in the session so that the user is automatically logged in for every subsequent request. To make this work, first remove the stateless key from your firewall configuration or set it to false:
Listing 87-5

1 # app/config/security.yml 2 security: 3 # ... 4 5 firewalls: 6 secured_area: 7 pattern: ^/admin 8 stateless: false 9 simple_preauth: 10 authenticator: apikey_authenticator

Storing authentication information in the session works like this:

PDF brought to you by generated on February 10, 2014 Chapter 87: How to Authenticate Users with API Keys | 307

1. At the end of each request, Symfony serializes the token object (returned from authenticateToken()), which also serializes the User object (since it's set on a property on the token); 2. On the next request the token is deserialized and the deserialized User object is passed to the refreshUser() function of the user provider. The second step is the important one: Symfony calls refreshUser() and passes you the user object that was serialized in the session. If your users are stored in the database, then you may want to re-query for a fresh version of the user to make sure it's not out-of-date. But regardless of your requirements, refreshUser() should now return the User object:
Listing 87-6

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// src/Acme/HelloBundle/Security/ApiKeyUserProvider.php // ... class ApiKeyUserProvider implements UserProviderInterface { // ...

public function refreshUser(UserInterface $user) { // $user is the User that you set in the token inside authenticateToken() // after it has been deserialized from the session

// you might use $user to query the database for a fresh user // $id = $user->getId(); // use $id to make a query // if you are *not* reading from a database and are just creating // a User object (like in this example), you can just return it return $user;
} }

You'll also want to make sure that your User object is being serialized correctly. If your User object has private properties, PHP can't serialize those. In this case, you may get back a User object that has a null value for each property. For an example, see How to load Security Users from the Database (the Entity Provider).

Only Authenticating for Certain URLs

This entry has assumed that you want to look for the apikey authentication on every request. But in some situations (like an OAuth flow), you only really need to look for authentication information once the user has reached a certain URL (e.g. the redirect URL in OAuth). Fortunately, handling this situation is easy: just check to see what the current URL is before creating the token in createToken():
Listing 87-7

1 2 3 4 5 6 7

// src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php // ... use Symfony\Component\Security\Http\HttpUtils; use Symfony\Component\HttpFoundation\Request;

class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface

PDF brought to you by generated on February 10, 2014

Chapter 87: How to Authenticate Users with API Keys | 308

8 { 9 protected $userProvider; 10 11 protected $httpUtils; 12 13 public function __construct(ApiKeyUserProviderInterface $userProvider, HttpUtils 14 $httpUtils) 15 { 16 $this->userProvider = $userProvider; 17 $this->httpUtils = $httpUtils; 18 } 19 20 public function createToken(Request $request, $providerKey) 21 { 22 // set the only URL where we should look for auth information 23 // and only return the token if we're at that URL 24 $targetUrl = '/login/check'; 25 if (!$this->httpUtils->checkRequestPath($request, $targetUrl)) { 26 return; 27 } 28 29 // ... 30 } }

This uses the handy HttpUtils4 class to check if the current URL matches the URL you're looking for. In this case, the URL (/login/check) has been hardcoded in the class, but you could also inject it as the third constructor argument. Next, just update your service configuration to inject the security.http_utils service:
Listing 87-8

1 # app/config/config.yml 2 services: 3 # ... 4 5 apikey_authenticator: 6 class: Acme\HelloBundle\Security\ApiKeyAuthenticator 7 arguments: ["@your_api_key_user_provider", "@security.http_utils"]

That's it! Have fun!

4. http://api.symfony.com/2.4/Symfony/Component/Security/Http/HttpUtils.html

PDF brought to you by generated on February 10, 2014

Chapter 87: How to Authenticate Users with API Keys | 309

Chapter 88

How to create a custom Authentication Provider

Creating a custom authentication system is hard, and this entry will walk you through that process. But depending on your needs, you may be able to solve your problem in a simpler way using these documents: How to Create a Custom Form Password Authenticator How to Authenticate Users with API Keys

If you have read the chapter on Security, you understand the distinction Symfony2 makes between authentication and authorization in the implementation of security. This chapter discusses the core classes involved in the authentication process, and how to implement a custom authentication provider. Because authentication and authorization are separate concepts, this extension will be user-provider agnostic, and will function with your application's user providers, may they be based in memory, a database, or wherever else you choose to store them.

Meet WSSE
The following chapter demonstrates how to create a custom authentication provider for WSSE authentication. The security protocol for WSSE provides several security benefits: 1. Username / Password encryption 2. Safe guarding against replay attacks 3. No web server configuration required WSSE is very useful for the securing of web services, may they be SOAP or REST. There is plenty of great documentation on WSSE1, but this article will focus not on the security protocol, but rather the manner in which a custom protocol can be added to your Symfony2 application. The basis

1. http://www.xml.com/pub/a/2003/12/17/dive.html

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 310

of WSSE is that a request header is checked for encrypted credentials, verified using a timestamp and nonce2, and authenticated for the requested user using a password digest.
WSSE also supports application key validation, which is useful for web services, but is outside the scope of this chapter.

The Token
The role of the token in the Symfony2 security context is an important one. A token represents the user authentication data present in the request. Once a request is authenticated, the token retains the user's data, and delivers this data across the security context. First, you'll create your token class. This will allow the passing of all relevant information to your authentication provider.
Listing 88-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

// src/Acme/DemoBundle/Security/Authentication/Token/WsseUserToken.php namespace Acme\DemoBundle\Security\Authentication\Token;

use Symfony\Component\Security\Core\Authentication\Token\AbstractToken; class WsseUserToken extends AbstractToken { public $created; public $digest; public $nonce; public function __construct(array $roles = array()) { parent::__construct($roles);

// If the user has roles, consider it authenticated $this->setAuthenticated(count($roles) > 0);

} public function getCredentials() { return ''; } }

The WsseUserToken class extends the Security component's AbstractToken3 class, which provides basic token functionality. Implement the TokenInterface4 on any class to use as a token.

The Listener
Next, you need a listener to listen on the security context. The listener is responsible for fielding requests to the firewall and calling the authentication provider. A listener must be an instance of

2. http://en.wikipedia.org/wiki/Cryptographic_nonce 3. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authentication/Token/AbstractToken.html 4. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authentication/Token/TokenInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 311

ListenerInterface5. A security listener should handle the GetResponseEvent6 event, and set an authenticated token in the security context if successful.
Listing 88-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

// src/Acme/DemoBundle/Security/Firewall/WsseListener.php namespace Acme\DemoBundle\Security\Firewall;

use use use use use use use Symfony\Component\HttpFoundation\Response; Symfony\Component\HttpKernel\Event\GetResponseEvent; Symfony\Component\Security\Http\Firewall\ListenerInterface; Symfony\Component\Security\Core\Exception\AuthenticationException; Symfony\Component\Security\Core\SecurityContextInterface; Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface; Acme\DemoBundle\Security\Authentication\Token\WsseUserToken;

class WsseListener implements ListenerInterface { protected $securityContext; protected $authenticationManager; public function __construct(SecurityContextInterface $securityContext, AuthenticationManagerInterface $authenticationManager) { $this->securityContext = $securityContext; $this->authenticationManager = $authenticationManager; } public function handle(GetResponseEvent $event) { $request = $event->getRequest(); $wsseRegex = '/UsernameToken Username="([^"]+)", PasswordDigest="([^"]+)", Nonce="([^"]+)", Created="([^"]+)"/'; if (!$request->headers->has('x-wsse') || 1 !== preg_match($wsseRegex, $request->headers->get('x-wsse'), $matches)) { return; } $token = new WsseUserToken(); $token->setUser($matches[1]); $token->digest $token->nonce $token->created = $matches[2]; = $matches[3]; = $matches[4];

try { $authToken = $this->authenticationManager->authenticate($token); $this->securityContext->setToken($authToken); return; } catch (AuthenticationException $failed) { // ... you might log something here

// To deny the authentication clear the token. This will redirect to the login page. // Make sure to only clear your token, not those of other authentication listeners. // $token = $this->securityContext->getToken();

5. http://api.symfony.com/2.4/Symfony/Component/Security/Http/Firewall/ListenerInterface.html 6. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Event/GetResponseEvent.html

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 312

55 // if ($token instanceof WsseUserToken && $this->providerKey === 56 $token->getProviderKey()) { 57 // $this->securityContext->setToken(null); 58 // } 59 // return; 60 61 // Deny authentication with a '403 Forbidden' HTTP response 62 $response = new Response(); 63 $response->setStatusCode(Response::HTTP_FORBIDDEN); 64 $event->setResponse($response); 65 66 } 67 // By default deny authorization $response = new Response(); $response->setStatusCode(Response::HTTP_FORBIDDEN); $event->setResponse($response); } }

New in version 2.4: Support for HTTP status code constants was added in Symfony 2.4.

This listener checks the request for the expected X-WSSE header, matches the value returned for the expected WSSE information, creates a token using that information, and passes the token on to the authentication manager. If the proper information is not provided, or the authentication manager throws an AuthenticationException7, a 403 Response is returned.
A class not used above, the AbstractAuthenticationListener8 class, is a very useful base class which provides commonly needed functionality for security extensions. This includes maintaining the token in the session, providing success / failure handlers, login form URLs, and more. As WSSE does not require maintaining authentication sessions or login forms, it won't be used for this example.

Returning prematurely from the listener is relevant only if you want to chain authentication providers (for example to allow anonymous users). If you want to forbid access to anonymous users and have a nice 403 error, you should set the status code of the response before returning.

The Authentication Provider

The authentication provider will do the verification of the WsseUserToken. Namely, the provider will verify the Created header value is valid within five minutes, the Nonce header value is unique within five minutes, and the PasswordDigest header value matches with the user's password.
Listing 88-3

1 // src/Acme/DemoBundle/Security/Authentication/Provider/WsseProvider.php 2 namespace Acme\DemoBundle\Security\Authentication\Provider;

7. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Exception/AuthenticationException.html 8. http://api.symfony.com/2.4/Symfony/Component/Security/Http/Firewall/AbstractAuthenticationListener.html

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 313

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61

use Symfony\Component\Security\Core\Authentication\Provider\AuthenticationProviderInterface; use Symfony\Component\Security\Core\User\UserProviderInterface; use Symfony\Component\Security\Core\Exception\AuthenticationException; use Symfony\Component\Security\Core\Exception\NonceExpiredException; use Symfony\Component\Security\Core\Authentication\Token\TokenInterface; use Acme\DemoBundle\Security\Authentication\Token\WsseUserToken; class WsseProvider implements AuthenticationProviderInterface { private $userProvider; private $cacheDir; public function __construct(UserProviderInterface $userProvider, $cacheDir) { $this->userProvider = $userProvider; $this->cacheDir = $cacheDir; } public function authenticate(TokenInterface $token) { $user = $this->userProvider->loadUserByUsername($token->getUsername()); if ($user && $this->validateDigest($token->digest, $token->nonce, $token->created, $user->getPassword())) { $authenticatedToken = new WsseUserToken($user->getRoles()); $authenticatedToken->setUser($user); return $authenticatedToken; } throw new AuthenticationException('The WSSE authentication failed.'); }

/** * This function is specific to Wsse authentication and is only used to help this example * * For more information specific to the logic here, see * https://github.com/symfony/symfony-docs/pull/3134#issuecomment-27699129 */ protected function validateDigest($digest, $nonce, $created, $secret) { // Check created time is not in the future if (strtotime($created) > time()) { return false; } // Expire timestamp after 5 minutes if (time() - strtotime($created) > 300) { return false; } // Validate that the nonce is *not* used in the last 5 minutes // if it has, this could be a replay attack if (file_exists($this->cacheDir.'/'.$nonce) && file_get_contents($this->cacheDir.'/'.$nonce) + 300 > time()) { throw new NonceExpiredException('Previously used nonce detected');

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 314

62 63 64 65 66 67 68 69 70 71 72 73 74 75

} // If cache directory does not exist we create it if (!is_dir($this->cacheDir)) { mkdir($this->cacheDir, 0777, true); } file_put_contents($this->cacheDir.'/'.$nonce, time());

// Validate Secret $expected = base64_encode(sha1(base64_decode($nonce).$created.$secret, true));

return $digest === $expected; } public function supports(TokenInterface $token) { return $token instanceof WsseUserToken; } }

The AuthenticationProviderInterface9 requires an authenticate method on the user token, and a supports method, which tells the authentication manager whether or not to use this provider for the given token. In the case of multiple providers, the authentication manager will then move to the next provider in the list.

The Factory
You have created a custom token, custom listener, and custom provider. Now you need to tie them all together. How do you make your provider available to your security configuration? The answer is by using a factory. A factory is where you hook into the Security component, telling it the name of your provider and any configuration options available for it. First, you must create a class which implements SecurityFactoryInterface10.
Listing 88-4

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

// src/Acme/DemoBundle/DependencyInjection/Security/Factory/WsseFactory.php namespace Acme\DemoBundle\DependencyInjection\Security\Factory;

use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Reference; use Symfony\Component\DependencyInjection\DefinitionDecorator; use Symfony\Component\Config\Definition\Builder\NodeDefinition; use Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\SecurityFactoryInterface; class WsseFactory implements SecurityFactoryInterface { public function create(ContainerBuilder $container, $id, $config, $userProvider, $defaultEntryPoint) { $providerId = 'security.authentication.provider.wsse.'.$id; $container ->setDefinition($providerId, new DefinitionDecorator('wsse.security.authentication.provider'))

9. http://api.symfony.com/2.4/Symfony/Component/Security/Core/Authentication/Provider/AuthenticationProviderInterface.html 10. http://api.symfony.com/2.4/Symfony/Bundle/SecurityBundle/DependencyInjection/Security/Factory/SecurityFactoryInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 315

20 ->replaceArgument(0, new Reference($userProvider)) 21 ; 22 23 $listenerId = 'security.authentication.listener.wsse.'.$id; 24 $listener = $container->setDefinition($listenerId, new 25 DefinitionDecorator('wsse.security.authentication.listener')); 26 27 return array($providerId, $listenerId, $defaultEntryPoint); 28 } 29 30 public function getPosition() 31 { 32 return 'pre_auth'; 33 } 34 35 public function getKey() 36 { 37 return 'wsse'; 38 } 39 public function addConfiguration(NodeDefinition $node) { } }

The SecurityFactoryInterface11 requires the following methods: create method, which adds the listener and authentication provider to the DI container for the appropriate security context; getPosition method, which must be of type pre_auth, form, http, and remember_me and defines the position at which the provider is called; getKey method which defines the configuration key used to reference the provider; addConfiguration method, which is used to define the configuration options underneath the configuration key in your security configuration. Setting configuration options are explained later in this chapter.
A class not used in this example, AbstractFactory12, is a very useful base class which provides commonly needed functionality for security factories. It may be useful when defining an authentication provider of a different type.

Now that you have created a factory class, the wsse key can be used as a firewall in your security configuration.
You may be wondering "why do you need a special factory class to add listeners and providers to the dependency injection container?". This is a very good question. The reason is you can use your firewall multiple times, to secure multiple parts of your application. Because of this, each time your firewall is used, a new service is created in the DI container. The factory is what creates these new services.

11. http://api.symfony.com/2.4/Symfony/Bundle/SecurityBundle/DependencyInjection/Security/Factory/SecurityFactoryInterface.html 12. http://api.symfony.com/2.4/Symfony/Bundle/SecurityBundle/DependencyInjection/Security/Factory/AbstractFactory.html

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 316

Configuration
It's time to see your authentication provider in action. You will need to do a few things in order to make this work. The first thing is to add the services above to the DI container. Your factory class above makes reference to service ids that do not exist yet: wsse.security.authentication.provider and wsse.security.authentication.listener. It's time to define those services.
Listing 88-5

1 # src/Acme/DemoBundle/Resources/config/services.yml 2 services: 3 wsse.security.authentication.provider: 4 class: Acme\DemoBundle\Security\Authentication\Provider\WsseProvider 5 arguments: ["", "%kernel.cache_dir%/security/nonces"] 6 7 wsse.security.authentication.listener: 8 class: Acme\DemoBundle\Security\Firewall\WsseListener 9 arguments: ["@security.context", "@security.authentication.manager"]

Now that your services are defined, tell your security context about your factory in your bundle class:
Listing 88-6

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/DemoBundle/AcmeDemoBundle.php namespace Acme\DemoBundle;

use Acme\DemoBundle\DependencyInjection\Security\Factory\WsseFactory; use Symfony\Component\HttpKernel\Bundle\Bundle; use Symfony\Component\DependencyInjection\ContainerBuilder; class AcmeDemoBundle extends Bundle { public function build(ContainerBuilder $container) { parent::build($container); $extension = $container->getExtension('security'); $extension->addSecurityListenerFactory(new WsseFactory()); } }

You are finished! You can now define parts of your app as under WSSE protection.
Listing 88-7

1 security: 2 firewalls: 3 wsse_secured: 4 pattern: /api/.* 5 stateless: true 6 wsse: true

Congratulations! You have written your very own custom security authentication provider!

A Little Extra
How about making your WSSE authentication provider a bit more exciting? The possibilities are endless. Why don't you start by adding some sparkle to that shine?

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 317

Configuration
You can add custom options under the wsse key in your security configuration. For instance, the time allowed before expiring the Created header item, by default, is 5 minutes. Make this configurable, so different firewalls can have different timeout lengths. You will first need to edit WsseFactory and define the new option in the addConfiguration method.
Listing 88-8

1 class WsseFactory implements SecurityFactoryInterface 2 { 3 // ... 4 5 public function addConfiguration(NodeDefinition $node) 6 { 7 $node 8 ->children() 9 ->scalarNode('lifetime')->defaultValue(300) 10 ->end(); 11 } 12 }

Now, in the create method of the factory, the $config argument will contain a lifetime key, set to 5 minutes (300 seconds) unless otherwise set in the configuration. Pass this argument to your authentication provider in order to put it to use.
Listing 88-9

1 class WsseFactory implements SecurityFactoryInterface 2 { 3 public function create(ContainerBuilder $container, $id, $config, $userProvider, 4 $defaultEntryPoint) 5 { 6 $providerId = 'security.authentication.provider.wsse.'.$id; 7 $container 8 ->setDefinition($providerId, 9 new DefinitionDecorator('wsse.security.authentication.provider')) 10 ->replaceArgument(0, new Reference($userProvider)) 11 ->replaceArgument(2, $config['lifetime']); 12 // ... 13 } 14 15 // ... }

You'll also need to add a third argument to the wsse.security.authentication.provider service configuration, which can be blank, but will be filled in with the lifetime in the factory. The WsseProvider class will also now need to accept a third constructor argument - the lifetime - which it should use instead of the hard-coded 300 seconds. These two steps are not shown here.

The lifetime of each WSSE request is now configurable, and can be set to any desirable value per firewall.
Listing 88-10

1 security: 2 firewalls: 3 wsse_secured: 4 pattern: /api/.* 5 stateless: true 6 wsse: { lifetime: 30 }

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 318

The rest is up to you! Any relevant configuration items can be defined in the factory and consumed or passed to the other classes in the container.

PDF brought to you by generated on February 10, 2014

Chapter 88: How to create a custom Authentication Provider | 319

Chapter 89

How to change the Default Target Path Behavior

By default, the Security component retains the information of the last request URI in a session variable named _security.main.target_path (with main being the name of the firewall, defined in security.yml). Upon a successful login, the user is redirected to this path, as to help them continue from the last known page they visited. On some occasions, this is unexpected. For example when the last request URI was an HTTP POST against a route which is configured to allow only a POST method, the user is redirected to this route only to get a 404 error. To get around this behavior, you would simply need to extend the ExceptionListener class and override the default method named setTargetPath(). First, override the security.exception_listener.class parameter in your configuration file. This can be done from your main configuration file (in app/config) or from a configuration file being imported from a bundle:
Listing 89-1

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 parameters: 3 # ... 4 security.exception_listener.class: Acme\HelloBundle\Security\Firewall\ExceptionListener

Next, create your own ExceptionListener:

Listing 89-2

1 2 3 4 5 6 7 8 9 10

// src/Acme/HelloBundle/Security/Firewall/ExceptionListener.php namespace Acme\HelloBundle\Security\Firewall;

use Symfony\Component\HttpFoundation\Request; use Symfony\Component\Security\Http\Firewall\ExceptionListener as BaseExceptionListener; class ExceptionListener extends BaseExceptionListener { protected function setTargetPath(Request $request) {

PDF brought to you by generated on February 10, 2014

Chapter 89: How to change the Default Target Path Behavior | 320

11 12 13 14 15 16 17 18 19 }

// Do not save target path for XHR and non-GET requests // You can add any more logic here you want if ($request->isXmlHttpRequest() || 'GET' !== $request->getMethod()) { return; }
parent::setTargetPath($request); }

Add as much or few logic here as required for your scenario!

PDF brought to you by generated on February 10, 2014

Chapter 89: How to change the Default Target Path Behavior | 321

Chapter 90

Using CSRF in the Login Form

When using a login form, you should make sure that you are protected against CSRF (Cross-site request forgery1). The Security component already has built-in support for CSRF. In this article you'll learn how you can use it in your login form.
Login CSRF attacks are a bit less well-known. See Forging Login Requests2 if you're curious about more details.

Configuring CSRF
First, configure the Security component so it can use CSRF protection. The Security component needs a CSRF provider. You can set this to use the default provider available in the Form component:
Listing 90-1

1 # app/config/security.yml 2 security: 3 firewalls: 4 secured_area: 5 # ... 6 form_login: 7 # ... 8 csrf_provider: form.csrf_provider

The Security component can be configured further, but this is all information it needs to be able to use CSRF in the login form.

1. http://en.wikipedia.org/wiki/Cross-site_request_forgery 2. http://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests

PDF brought to you by generated on February 10, 2014

Chapter 90: Using CSRF in the Login Form | 322

Rendering the CSRF field

Now that Security component will check for the CSRF token, you have to add a hidden field to the login form containing the CSRF token. By default, this field is named _csrf_token. That hidden field must contain the CSRF token, which can be generated by using the csrf_token function. That function requires a token ID, which must be set to authenticate when using the login form:
Listing 90-2

1 2 3 4 5 6 7 8 9 10 11 12

{# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #} {# ... #} <form action="{{ path('login_check') }}" method="post"> {# ... the login fields #}
<input type="hidden" name="_csrf_token" value="{{ csrf_token('authenticate') }}" > <button type="submit">login</button> </form>

After this, you have protected your login form against CSRF attacks.
You can change the name of the field by setting csrf_parameter and change the token ID by setting intention in your configuration:
Listing 90-3

1 # app/config/security.yml 2 security: 3 firewalls: 4 secured_area: 5 # ... 6 form_login: 7 # ... 8 csrf_parameter: _csrf_security_token 9 intention: a_private_string

PDF brought to you by generated on February 10, 2014

Chapter 90: Using CSRF in the Login Form | 323

Chapter 91

How to use the Serializer

Serializing and deserializing to and from objects and different formats (e.g. JSON or XML) is a very complex topic. Symfony comes with a Serializer Component, which gives you some tools that you can leverage for your solution. In fact, before you start, get familiar with the serializer, normalizers and encoders by reading the Serializer Component. You should also check out the JMSSerializerBundle1, which expands on the functionality offered by Symfony's core serializer.

Activating the Serializer

New in version 2.3: The Serializer has always existed in Symfony, but prior to Symfony 2.3, you needed to build the serializer service yourself.

The serializer service is not available by default. To turn it on, activate it in your configuration:
Listing 91-1

1 # app/config/config.yml 2 framework: 3 # ... 4 serializer: 5 enabled: true

Adding Normalizers and Encoders

Once enabled, the serializer service will be available in the container and will be loaded with two encoders (JsonEncoder2 and XmlEncoder3) but no normalizers, meaning you'll need to load your own.

1. http://jmsyst.com/bundles/JMSSerializerBundle 2. http://api.symfony.com/2.4/Symfony/Component/Serializer/Encoder/JsonEncoder.html 3. http://api.symfony.com/2.4/Symfony/Component/Serializer/Encoder/XmlEncoder.html

PDF brought to you by generated on February 10, 2014

Chapter 91: How to use the Serializer | 324

You can load normalizers and/or encoders by tagging them as serializer.normalizer and serializer.encoder. It's also possible to set the priority of the tag in order to decide the matching order. Here is an example on how to load the GetSetMethodNormalizer4:
Listing 91-2

1 # app/config/config.yml 2 services: 3 get_set_method_normalizer: 4 class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer 5 tags: 6 - { name: serializer.normalizer }

The GetSetMethodNormalizer5 is broken by design. As soon as you have a circular object graph, an infinite loop is created when calling the getters. You're encouraged to add your own normalizers that fit your use-case.

4. http://api.symfony.com/2.4/Symfony/Component/Serializer/Normalizer/GetSetMethodNormalizer.html 5. http://api.symfony.com/2.4/Symfony/Component/Serializer/Normalizer/GetSetMethodNormalizer.html

PDF brought to you by generated on February 10, 2014

Chapter 91: How to use the Serializer | 325

Chapter 92

How to create an Event Listener

Symfony has various events and hooks that can be used to trigger custom behavior in your application. Those events are thrown by the HttpKernel component and can be viewed in the KernelEvents1 class. To hook into an event and add your own custom logic, you have to create a service that will act as an event listener on that event. In this entry, you will create a service that will act as an Exception Listener, allowing you to modify how exceptions are shown by your application. The KernelEvents::EXCEPTION event is just one of the core kernel events:
Listing 92-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

// src/Acme/DemoBundle/EventListener/AcmeExceptionListener.php namespace Acme\DemoBundle\EventListener;

use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface; class AcmeExceptionListener { public function onKernelException(GetResponseForExceptionEvent $event) { // You get the exception object from the received event $exception = $event->getException(); $message = sprintf( 'My Error says: %s with code: %s', $exception->getMessage(), $exception->getCode() );

// Customize your response object to display the exception details $response = new Response(); $response->setContent($message); // HttpExceptionInterface is a special type of exception that // holds status code and header details if ($exception instanceof HttpExceptionInterface) {

1. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelEvents.html

PDF brought to you by generated on February 10, 2014

Chapter 92: How to create an Event Listener | 326

27 28 29 30 31 32 33 34 35 36 }

$response->setStatusCode($exception->getStatusCode()); $response->headers->replace($exception->getHeaders()); } else { $response->setStatusCode(Response::HTTP_INTERNAL_SERVER_ERROR); }

// Send the modified response object to the event $event->setResponse($response);

}

New in version 2.4: Support for HTTP status code constants was added in Symfony 2.4.

Each event receives a slightly different type of $event object. For the kernel.exception event, it is GetResponseForExceptionEvent2. To see what type of object each event listener receives, see KernelEvents3.

Now that the class is created, you just need to register it as a service and notify Symfony that it is a "listener" on the kernel.exception event by using a special "tag":
Listing 92-2

1 # app/config/config.yml 2 services: 3 kernel.listener.your_listener_name: 4 class: Acme\DemoBundle\EventListener\AcmeExceptionListener 5 tags: 6 - { name: kernel.event_listener, event: kernel.exception, method: onKernelException }

There is an additional tag option priority that is optional and defaults to 0. This value can be from -255 to 255, and the listeners will be executed in the order of their priority (highest to lowest). This is useful when you need to guarantee that one listener is executed before another.

Request events, checking types

A single page can make several requests (one master request, and then multiple sub-requests), which is why when working with the KernelEvents::REQUEST event, you might need to check the type of the request. This can be easily done as follow:
Listing 92-3

1 2 3 4 5 6

// src/Acme/DemoBundle/EventListener/AcmeRequestListener.php namespace Acme\DemoBundle\EventListener;

use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\HttpKernel;

2. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/Event/GetResponseForExceptionEvent.html 3. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/KernelEvents.html

PDF brought to you by generated on February 10, 2014

Chapter 92: How to create an Event Listener | 327

7 class AcmeRequestListener 8 { 9 public function onKernelRequest(GetResponseEvent $event) 10 { 11 if (HttpKernel::MASTER_REQUEST != $event->getRequestType()) { 12 // don't do anything if it's not the master request 13 return; 14 } 15 16 // ... 17 } 18 }

Two types of request are available in the HttpKernelInterface4 interface: HttpKernelInterface::MASTER_REQUEST and HttpKernelInterface::SUB_REQUEST.

4. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/HttpKernelInterface.html

PDF brought to you by generated on February 10, 2014

Chapter 92: How to create an Event Listener | 328

Chapter 93

How to Work with Scopes

This entry is all about scopes, a somewhat advanced topic related to the Service Container. If you've ever gotten an error mentioning "scopes" when creating services, then this entry is for you.
If you are trying to inject the request service, the simple solution is to inject the request_stack service instead and access the current Request by calling the getCurrentRequest()1 method (see Injecting the Request). The rest of this entry talks about scopes in a theoretical and more advanced way. If you're dealing with scopes for the request service, simply inject request_stack.

Understanding Scopes
The scope of a service controls how long an instance of a service is used by the container. The DependencyInjection component provides two generic scopes: container (the default one): The same instance is used each time you request it from this container. prototype: A new instance is created each time you request the service. The ContainerAwareHttpKernel2 also defines a third scope: request. This scope is tied to the request, meaning a new instance is created for each subrequest and is unavailable outside the request (for instance in the CLI).

An Example: Client Scope

Other than the request service (which has a simple solution, see the above note), no services in the default Symfony2 container belong to any scope other than container and prototype. But for the purposes of this entry, imagine there is another scope client and a service client_configuration that belongs to it. This is not a common situation, but the idea is that you may enter and exit multiple client scopes during a request, and each has its own client_configuration service.

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/RequestStack.html#getCurrentRequest() 2. http://api.symfony.com/2.4/Symfony/Component/HttpKernel/DependencyInjection/ContainerAwareHttpKernel.html

PDF brought to you by generated on February 10, 2014

Chapter 93: How to Work with Scopes | 329

Scopes add a constraint on the dependencies of a service: a service cannot depend on services from a narrower scope. For example, if you create a generic my_foo service, but try to inject the client_configuration service, you will receive a ScopeWideningInjectionException3 when compiling the container. Read the sidebar below for more details.

Scopes and Dependencies

Imagine you've configured a my_mailer service. You haven't configured the scope of the service, so it defaults to container. In other words, every time you ask the container for the my_mailer service, you get the same object back. This is usually how you want your services to work. Imagine, however, that you need the client_configuration service in your my_mailer service, maybe because you're reading some details from it, such as what the "sender" address should be. You add it as a constructor argument. There are several reasons why this presents a problem: When requesting my_mailer, an instance of my_mailer (called MailerA here) is created and the client_configuration service ( called ConfigurationA here) is passed to it. Life is good! Your application now needs to do something with another client, and you've architected your application in such a way that you handle this by entering a new client_configuration scope and setting a new client_configuration service into the container. Call this ConfigurationB. Somewhere in your application, you once again ask for the my_mailer service. Since your service is in the container scope, the same instance (MailerA) is just re-used. But here's the problem: the MailerA instance still contains the old ConfigurationA object, which is now not the correct configuration object to have (ConfigurationB is now the current client_configuration service). This is subtle, but the mis-match could cause major problems, which is why it's not allowed. So, that's the reason why scopes exist, and how they can cause problems. Keep reading to find out the common solutions.

A service can of course depend on a service from a wider scope without any issue.

Using a Service from a Narrower Scope

There are several solutions to the scope problem: A) Use setter injection if the dependency is synchronized (see A) Using a Synchronized Service); B) Put your service in the same scope as the dependency (or a narrower one). If you depend on the client_configuration service, this means putting your new service in the client scope (see B) Changing the Scope of your Service); C) Pass the entire container to your service and retrieve your dependency from the container each time you need it to be sure you have the right instance -- your service can live in the default container scope (see C) Passing the Container as a Dependency of your Service). Each scenario is detailed in the following sections.

3. http://api.symfony.com/2.4/Symfony/Component/DependencyInjection/Exception/ScopeWideningInjectionException.html

PDF brought to you by generated on February 10, 2014

Chapter 93: How to Work with Scopes | 330

A) Using a Synchronized Service

New in version 2.3: Synchronized services are new in Symfony 2.3.

Both injecting the container and setting your service to a narrower scope have drawbacks. Assume first that the client_configuration service has been marked as synchronized:
Listing 93-1

1 # app/config/config.yml 2 services: 3 client_configuration: 4 class: Acme\HelloBundle\Client\ClientConfiguration 5 scope: client 6 synchronized: true 7 synthetic: true 8 # ...

Now, if you inject this service using setter injection, there are no drawbacks and everything works without any special code in your service or in your definition:
Listing 93-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// src/Acme/HelloBundle/Mail/Mailer.php namespace Acme\HelloBundle\Mail;

use Acme\HelloBundle\Client\ClientConfiguration; class Mailer { protected $clientConfiguration; public function setClientConfiguration(ClientConfiguration $clientConfiguration = null) { $this->clientConfiguration = $clientConfiguration; } public function sendEmail() { if (null === $this->clientConfiguration) { // throw an error? }

// ... do something using the client configuration here

} }

Whenever the client scope is active, the service container will automatically call the setClientConfiguration() method when the client_configuration service is set in the container. You might have noticed that the setClientConfiguration() method accepts null as a valid value for the client_configuration argument. That's because when leaving the client scope, the client_configuration instance can be null. Of course, you should take care of this possibility in your code. This should also be taken into account when declaring your service:
Listing 93-3

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 services: 3 my_mailer:

PDF brought to you by generated on February 10, 2014

Chapter 93: How to Work with Scopes | 331

4 5 6

class: Acme\HelloBundle\Mail\Mailer calls: - [setClientConfiguration, ["@?client_configuration="]]

B) Changing the Scope of your Service

Changing the scope of a service should be done in its definition. This example assumes that the Mailer class has a __construct function whose first argument is the ClientConfiguration object:
Listing 93-4

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 services: 3 my_mailer: 4 class: Acme\HelloBundle\Mail\Mailer 5 scope: client 6 arguments: ["@client_configuration"]

C) Passing the Container as a Dependency of your Service

Setting the scope to a narrower one is not always possible (for instance, a twig extension must be in the container scope as the Twig environment needs it as a dependency). In these cases, you can pass the entire container into your service:
Listing 93-5

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

// src/Acme/HelloBundle/Mail/Mailer.php namespace Acme\HelloBundle\Mail;

use Symfony\Component\DependencyInjection\ContainerInterface; class Mailer { protected $container; public function __construct(ContainerInterface $container) { $this->container = $container; } public function sendEmail() { $request = $this->container->get('client_configuration'); // ... do something using the client configuration here } }

Take care not to store the client configuration in a property of the object for a future call of the service as it would cause the same issue described in the first section (except that Symfony cannot detect that you are wrong).

The service config for this class would look something like this:
Listing 93-6

1 # src/Acme/HelloBundle/Resources/config/services.yml 2 parameters: 3 # ...

PDF brought to you by generated on February 10, 2014

Chapter 93: How to Work with Scopes | 332

4 my_mailer.class: Acme\HelloBundle\Mail\Mailer 5 6 services: 7 my_mailer: 8 class: "%my_mailer.class%" 9 arguments: ["@service_container"] 10 # scope: container can be omitted as it is the default

Injecting the whole container into a service is generally not a good idea (only inject what you need).

PDF brought to you by generated on February 10, 2014

Chapter 93: How to Work with Scopes | 333

Chapter 94

How to work with Compiler Passes in Bundles

Compiler passes give you an opportunity to manipulate other service definitions that have been registered with the service container. You can read about how to create them in the components section "Compiling the Container". To register a compiler pass from a bundle you need to add it to the build method of the bundle definition class:
Listing 94-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/MailerBundle/AcmeMailerBundle.php namespace Acme\MailerBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle; use Symfony\Component\DependencyInjection\ContainerBuilder; use Acme\MailerBundle\DependencyInjection\Compiler\CustomCompilerPass; class AcmeMailerBundle extends Bundle { public function build(ContainerBuilder $container) { parent::build($container); $container->addCompilerPass(new CustomCompilerPass()); } }

One of the most common use-cases of compiler passes is to work with tagged services (read more about tags in the components section "Working with Tagged Services"). If you are using custom tags in a bundle then by convention, tag names consist of the name of the bundle (lowercase, underscores as separators), followed by a dot, and finally the "real" name. For example, if you want to introduce some sort of "transport" tag in your AcmeMailerBundle, you should call it acme_mailer.transport.

PDF brought to you by generated on February 10, 2014

Chapter 94: How to work with Compiler Passes in Bundles | 334

Chapter 95

Session Proxy Examples

The session proxy mechanism has a variety of uses and this example demonstrates two common uses. Rather than injecting the session handler as normal, a handler is injected into the proxy and registered with the session storage driver:
Listing 95-1

1 2 3 4 5 6

use Symfony\Component\HttpFoundation\Session\Session; use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage; use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler; $proxy = new YourProxy(new PdoSessionHandler()); $session = new Session(new NativeSessionStorage(array(), $proxy));

Below, you'll learn two real examples that can be used for YourProxy: encryption of session data and readonly guest session.

Encryption of Session Data

If you wanted to encrypt the session data, you could use the proxy to encrypt and decrypt the session as required:
Listing 95-2

1 use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy; 2 3 class EncryptedSessionProxy extends SessionHandlerProxy 4 { 5 private $key; 6 7 public function __construct(\SessionHandlerInterface $handler, $key) 8 { 9 $this->key = $key; 10 11 parent::__construct($handler); 12 } 13 14 public function read($id)

PDF brought to you by generated on February 10, 2014

Chapter 95: Session Proxy Examples | 335

15 16 17 18 19 20 21 22 23 24 25 26 27 }

{ $data = parent::read($id); return mcrypt_decrypt(\MCRYPT_3DES, $this->key, $data); } public function write($id, $data) { $data = mcrypt_encrypt(\MCRYPT_3DES, $this->key, $data); return parent::write($id, $data); }

Readonly Guest Sessions

There are some applications where a session is required for guest users, but there is no particular need to persist the session. In this case you can intercept the session before it writes:
Listing 95-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

use Foo\User; use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy; class ReadOnlyGuestSessionProxy extends SessionHandlerProxy { private $user; public function __construct(\SessionHandlerInterface $handler, User $user) { $this->user = $user; parent::__construct($handler); } public function write($id, $data) { if ($this->user->isGuest()) { return; } return parent::write($id, $data); } }

PDF brought to you by generated on February 10, 2014

Chapter 95: Session Proxy Examples | 336

Chapter 96

Making the Locale "Sticky" during a User's Session

Prior to Symfony 2.1, the locale was stored in a session attribute called _locale. Since 2.1, it is stored in the Request, which means that it's not "sticky" during a user's request. In this article, you'll learn how to make the locale of a user "sticky" so that once it's set, that same locale will be used for every subsequent request.

Creating a LocaleListener
To simulate that the locale is stored in a session, you need to create and register a new event listener. The listener will look something like this. Typically, _locale is used as a routing parameter to signify the locale, though it doesn't really matter how you determine the desired locale from the request:
Listing 96-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

// src/Acme/LocaleBundle/EventListener/LocaleListener.php namespace Acme\LocaleBundle\EventListener;

use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\KernelEvents; use Symfony\Component\EventDispatcher\EventSubscriberInterface; class LocaleListener implements EventSubscriberInterface { private $defaultLocale; public function __construct($defaultLocale = 'en') { $this->defaultLocale = $defaultLocale; } public function onKernelRequest(GetResponseEvent $event) { $request = $event->getRequest();

PDF brought to you by generated on February 10, 2014

Chapter 96: Making the Locale "Sticky" during a User's Session | 337

20 if (!$request->hasPreviousSession()) { 21 return; 22 } 23 24 // try to see if the locale has been set as a _locale routing parameter 25 if ($locale = $request->attributes->get('_locale')) { 26 $request->getSession()->set('_locale', $locale); 27 } else { 28 // if no explicit locale has been set on this request, use one from the session 29 $request->setLocale($request->getSession()->get('_locale', 30 $this->defaultLocale)); 31 } 32 } 33 34 public static function getSubscribedEvents() 35 { 36 return array( 37 // must be registered before the default Locale listener 38 KernelEvents::REQUEST => array(array('onKernelRequest', 17)), 39 ); 40 } }

Then register the listener:

Listing 96-2

1 services: 2 acme_locale.locale_listener: 3 class: Acme\LocaleBundle\EventListener\LocaleListener 4 arguments: ["%kernel.default_locale%"] 5 tags: 6 - { name: kernel.event_subscriber }

That's it! Now celebrate by changing the user's locale and seeing that it's sticky throughout the request. Remember, to get the user's locale, always use the Request::getLocale1 method:
Listing 96-3

1 2 3 4 5 6 7

// from a controller... use Symfony\Component\HttpFoundation\Request;

public function indexAction(Request $request) { $locale = $request->getLocale(); }

1. http://api.symfony.com/2.4/Symfony/Component/HttpFoundation/Request.html#getLocale()

PDF brought to you by generated on February 10, 2014

Chapter 96: Making the Locale "Sticky" during a User's Session | 338

Chapter 97

Configuring the Directory Where Sessions Files are Saved

By default, the Symfony Standard Edition uses the global php.ini values for session.save_handler and session.save_path to determine where to store session data. This is because of the following configuration:
Listing 97-1

1 # app/config/config.yml 2 framework: 3 session: 4 # handler_id set to null will use default session handler from php.ini 5 handler_id: ~

With this configuration, changing where your session metadata is stored is entirely up to your php.ini configuration. However, if you have the following configuration, Symfony will store the session data in files in the cache directory %kernel.cache_dir%/sessions. This means that when you clear the cache, any current sessions will also be deleted:
Listing 97-2

1 # app/config/config.yml 2 framework: 3 session: ~

Using a different directory to save session data is one method to ensure that your current sessions aren't lost when you clear Symfony's cache.
Using a different session save handler is an excellent (yet more complex) method of session management available within Symfony. See Configuring Sessions and Save Handlers for a discussion of session save handlers. There is also an entry in the cookbook about storing sessions in the database.

To change the directory in which Symfony saves session data, you only need change the framework configuration. In this example, you will change the session directory to app/sessions:
PDF brought to you by generated on February 10, 2014 Chapter 97: Configuring the Directory Where Sessions Files are Saved | 339

Listing 97-3

1 # app/config/config.yml 2 framework: 3 session: 4 handler_id: session.handler.native_file 5 save_path: "%kernel.root_dir%/sessions"

PDF brought to you by generated on February 10, 2014

Chapter 97: Configuring the Directory Where Sessions Files are Saved | 340

Chapter 98

Bridge a legacy application with Symfony Sessions

New in version 2.3: The ability to integrate with a legacy PHP session was added in Symfony 2.3.

If you're integrating the Symfony full-stack Framework into a legacy application that starts the session with session_start(), you may still be able to use Symfony's session management by using the PHP Bridge session. If the application has sets it's own PHP save handler, you can specify null for the handler_id:
Listing 98-1

1 framework: 2 session: 3 storage_id: session.storage.php_bridge 4 handler_id: ~

Otherwise, if the problem is simply that you cannot avoid the application starting the session with session_start(), you can still make use of a Symfony based session save handler by specifying the save handler as in the example below:
Listing 98-2

1 framework: 2 session: 3 storage_id: session.storage.php_bridge 4 handler_id: session.handler.native_file

PDF brought to you by generated on February 10, 2014

Chapter 98: Bridge a legacy application with Symfony Sessions | 341

If the legacy application requires its own session save-handler, do not override this. Instead set handler_id: ~. Note that a save handler cannot be changed once the session has been started. If the application starts the session before Symfony is initialized, the save-handler will have already been set. In this case, you will need handler_id: ~. Only override the save-handler if you are sure the legacy application can use the Symfony save-handler without side effects and that the session has not been started before Symfony is initialized.

For more details, see Integrating with Legacy Sessions.

PDF brought to you by generated on February 10, 2014

Chapter 98: Bridge a legacy application with Symfony Sessions | 342

Chapter 99

Limit Session Metadata Writes

New in version 2.4: The ability to limit session metadata writes was added in Symfony 2.4.

The default behavior of PHP session is to persist the session regardless of whether the session data has changed or not. In Symfony, each time the session is accessed, metadata is recorded (session created/last used) which can be used to determine session age and idle time. If for performance reasons you wish to limit the frequency at which the session persists, this feature can adjust the granularity of the metadata updates and persist the session less often while still maintaining relatively accurate metadata. If other session data is changed, the session will always persist. You can tell Symfony not to update the metadata "session last updated" time until a certain amount of time has passed, by setting framework.session.metadata_update_threshold to a value in seconds greater than zero:
Listing 99-1

1 framework: 2 session: 3 metadata_update_threshold: 120

PHP default's behavior is to save the session whether it has been changed or not. When using framework.session.metadata_update_threshold Symfony will wrap the session handler (configured at framework.session.handler_id) into the WriteCheckSessionHandler. This will prevent any session write if the session was not modified.

Be aware that if the session is not written at every request, it may be garbage collected sooner than usual. This means that your users may be logged out sooner than expected.

PDF brought to you by generated on February 10, 2014

Chapter 99: Limit Session Metadata Writes | 343

Chapter 100

How Symfony2 differs from symfony1

The Symfony2 framework embodies a significant evolution when compared with the first version of the framework. Fortunately, with the MVC architecture at its core, the skills used to master a symfony1 project continue to be very relevant when developing in Symfony2. Sure, app.yml is gone, but routing, controllers and templates all remain. This chapter walks through the differences between symfony1 and Symfony2. As you'll see, many tasks are tackled in a slightly different way. You'll come to appreciate these minor differences as they promote stable, predictable, testable and decoupled code in your Symfony2 applications. So, sit back and relax as you travel from "then" to "now".

Directory Structure
When looking at a Symfony2 project - for example, the Symfony2 Standard Edition1 - you'll notice a very different directory structure than in symfony1. The differences, however, are somewhat superficial.

The app/ Directory

In symfony1, your project has one or more applications, and each lives inside the apps/ directory (e.g. apps/frontend). By default in Symfony2, you have just one application represented by the app/ directory. Like in symfony1, the app/ directory contains configuration specific to that application. It also contains application-specific cache, log and template directories as well as a Kernel class (AppKernel), which is the base object that represents the application. Unlike symfony1, almost no PHP code lives in the app/ directory. This directory is not meant to house modules or library files as it did in symfony1. Instead, it's simply the home of configuration and other resources (templates, translation files).

The src/ Directory

Put simply, your actual code goes here. In Symfony2, all actual application-code lives inside a bundle (roughly equivalent to a symfony1 plugin) and, by default, each bundle lives inside the src directory.
1. https://github.com/symfony/symfony-standard

PDF brought to you by generated on February 10, 2014

Chapter 100: How Symfony2 differs from symfony1 | 344

In that way, the src directory is a bit like the plugins directory in symfony1, but much more flexible. Additionally, while your bundles will live in the src/ directory, third-party bundles will live somewhere in the vendor/ directory. To get a better picture of the src/ directory, first think of the structure of a symfony1 application. First, part of your code likely lives inside one or more applications. Most commonly these include modules, but could also include any other PHP classes you put in your application. You may have also created a schema.yml file in the config directory of your project and built several model files. Finally, to help with some common functionality, you're using several third-party plugins that live in the plugins/ directory. In other words, the code that drives your application lives in many different places. In Symfony2, life is much simpler because all Symfony2 code must live in a bundle. In the pretend symfony1 project, all the code could be moved into one or more plugins (which is a very good practice, in fact). Assuming that all modules, PHP classes, schema, routing configuration, etc. were moved into a plugin, the symfony1 plugins/ directory would be very similar to the Symfony2 src/ directory. Put simply again, the src/ directory is where your code, assets, templates and most anything else specific to your project will live.

The vendor/ Directory

The vendor/ directory is basically equivalent to the lib/vendor/ directory in symfony1, which was the conventional directory for all vendor libraries and bundles. By default, you'll find the Symfony2 library files in this directory, along with several other dependent libraries such as Doctrine2, Twig and Swift Mailer. 3rd party Symfony2 bundles live somewhere in the vendor/.

The web/ Directory

Not much has changed in the web/ directory. The most noticeable difference is the absence of the css/, js/ and images/ directories. This is intentional. Like with your PHP code, all assets should also live inside a bundle. With the help of a console command, the Resources/public/ directory of each bundle is copied or symbolically-linked to the web/bundles/ directory. This allows you to keep assets organized inside your bundle, but still make them available to the public. To make sure that all bundles are available, run the following command:
Listing 100-1

1 $ php app/console assets:install web

This command is the Symfony2 equivalent to the symfony1 plugin:publish-assets command.

Autoloading
One of the advantages of modern frameworks is never needing to worry about requiring files. By making use of an autoloader, you can refer to any class in your project and trust that it's available. Autoloading has changed in Symfony2 to be more universal, faster, and independent of needing to clear your cache. In symfony1, autoloading was done by searching the entire project for the presence of PHP class files and caching this information in a giant array. That array told symfony1 exactly which file contained each class. In the production environment, this caused you to need to clear the cache when classes were added or moved.

PDF brought to you by generated on February 10, 2014

Chapter 100: How Symfony2 differs from symfony1 | 345

In Symfony2, a tool named Composer2 handles this process. The idea behind the autoloader is simple: the name of your class (including the namespace) must match up with the path to the file containing that class. Take the FrameworkExtraBundle from the Symfony2 Standard Edition as an example:
Listing 100-2

1 2 3 4 5 6 7 8 9

namespace Sensio\Bundle\FrameworkExtraBundle; use Symfony\Component\HttpKernel\Bundle\Bundle; // ... class SensioFrameworkExtraBundle extends Bundle { // ... }

The file itself lives at vendor/sensio/framework-extra-bundle/Sensio/Bundle/ FrameworkExtraBundle/SensioFrameworkExtraBundle.php. As you can see, the second part of the path follows the namespace of the class. The first part is equal to the package name of the SensioFrameworkExtraBundle. The namespace, Sensio\Bundle\FrameworkExtraBundle, and package name, sensio/frameworkextra-bundle, spells out the directory that the file should live in (vendor/sensio/framework-extrabundle/Sensio/Bundle/FrameworkExtraBundle/). Composer can then look for the file at this specific place and load it very fast. If the file did not live at this exact location, you'd receive a Class "Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle" does not exist. error. In Symfony2, a "class does not exist" error means that the namespace of the class and physical location do not match. Basically, Symfony2 is looking in one exact location for that class, but that location doesn't exist (or contains a different class). In order for a class to be autoloaded, you never need to clear your cache in Symfony2. As mentioned before, for the autoloader to work, it needs to know that the Sensio namespace lives in the vendor/sensio/framework-extra-bundle directory and that, for example, the Doctrine namespace lives in the vendor/doctrine/orm/lib/ directory. This mapping is entirely controlled by Composer. Each third-party library you load through Composer has its settings defined and Composer takes care of everything for you. For this to work, all third-party libraries used by your project must be defined in the composer.json file. If you look at the HelloController from the Symfony2 Standard Edition you can see that it lives in the Acme\DemoBundle\Controller namespace. Yet, the AcmeDemoBundle is not defined in your composer.json file. Nonetheless are the files autoloaded. This is because you can tell composer to autoload files from specific directories without defining a dependency:
Listing 100-3

"autoload": { "psr-0": { "": "src/" } }

This means that if a class is not found in the vendor directory, Composer will search in the src directory before throwing a "class does not exist" exception. Read more about configuring the Composer autoloader in the Composer documentation3.

Using the Console

In symfony1, the console is in the root directory of your project and is called symfony:
2. http://getcomposer.org 3. http://getcomposer.org/doc/04-schema.md#autoload

PDF brought to you by generated on February 10, 2014

Chapter 100: How Symfony2 differs from symfony1 | 346

Listing 100-4

1 $ php symfony

In Symfony2, the console is now in the app sub-directory and is called console:
Listing 100-5

1 $ php app/console

Applications
In a symfony1 project, it is common to have several applications: one for the frontend and one for the backend for instance. In a Symfony2 project, you only need to create one application (a blog application, an intranet application, ...). Most of the time, if you want to create a second application, you might instead create another project and share some bundles between them. And if you need to separate the frontend and the backend features of some bundles, you can create sub-namespaces for controllers, sub-directories for templates, different semantic configurations, separate routing configurations, and so on. Of course, there's nothing wrong with having multiple applications in your project, that's entirely up to you. A second application would mean a new directory, e.g. my_app/, with the same basic setup as the app/ directory.
Read the definition of a Project, an Application, and a Bundle in the glossary.

Bundles and Plugins

In a symfony1 project, a plugin could contain configuration, modules, PHP libraries, assets and anything else related to your project. In Symfony2, the idea of a plugin is replaced by the "bundle". A bundle is even more powerful than a plugin because the core Symfony2 framework is brought in via a series of bundles. In Symfony2, bundles are first-class citizens that are so flexible that even core code itself is a bundle. In symfony1, a plugin must be enabled inside the ProjectConfiguration class:
Listing 100-6

1 2 3 4 5 6

// config/ProjectConfiguration.class.php public function setup() { // some plugins here $this->enableAllPluginsExcept(array(...)); }

In Symfony2, the bundles are activated inside the application kernel:

Listing 100-7

1 // app/AppKernel.php 2 public function registerBundles() 3 { 4 $bundles = array( 5 new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),

PDF brought to you by generated on February 10, 2014

Chapter 100: How Symfony2 differs from symfony1 | 347

6 7 8 9 10 11 12 }

new Symfony\Bundle\TwigBundle\TwigBundle(), ..., new Acme\DemoBundle\AcmeDemoBundle(), ); return $bundles;

Routing (routing.yml) and Configuration (config.yml)

In symfony1, the routing.yml and app.yml configuration files were automatically loaded inside any plugin. In Symfony2, routing and application configuration inside a bundle must be included manually. For example, to include a routing resource from a bundle called AcmeDemoBundle, you can do the following:
Listing 100-8

1 # app/config/routing.yml 2 _hello: 3 resource: "@AcmeDemoBundle/Resources/config/routing.yml"

This will load the routes found in the Resources/config/routing.yml file of the AcmeDemoBundle. The special @AcmeDemoBundle is a shortcut syntax that, internally, resolves to the full path to that bundle. You can use this same strategy to bring in configuration from a bundle:
Listing 100-9

1 # app/config/config.yml 2 imports: 3 - { resource: "@AcmeDemoBundle/Resources/config/config.yml" }

In Symfony2, configuration is a bit like app.yml in symfony1, except much more systematic. With app.yml, you could simply create any keys you wanted. By default, these entries were meaningless and depended entirely on how you used them in your application:
Listing 100-10 1

# some app.yml file from symfony1 2 all: 3 email: 4 from_address: [email protected]

In Symfony2, you can also create arbitrary entries under the parameters key of your configuration:
Listing 100-11 1

parameters: email.from_address: [email protected]

You can now access this from a controller, for example:

Listing 100-12 1

public function helloAction($name) 2 { 3 $fromAddress = $this->container->getParameter('email.from_address'); 4 }

In reality, the Symfony2 configuration is much more powerful and is used primarily to configure objects that you can use. For more information, see the chapter titled "Service Container".

PDF brought to you by generated on February 10, 2014

Chapter 100: How Symfony2 differs from symfony1 | 348

Chapter 101

How to Inject Variables into all Templates (i.e. Global Variables)

Sometimes you want a variable to be accessible to all the templates you use. This is possible inside your app/config/config.yml file:
Listing 101-1

1 # app/config/config.yml 2 twig: 3 # ... 4 globals: 5 ga_tracking: UA-xxxxx-x

Now, the variable ga_tracking is available in all Twig templates:

Listing 101-2

1 <p>The google tracking code is: {{ ga_tracking }}</p>

It's that easy!

Using Service Container Parameters

You can also take advantage of the built-in Service Parameters system, which lets you isolate or reuse the value:
Listing 101-3

1 # app/config/parameters.yml 2 parameters: 3 ga_tracking: UA-xxxxx-x

Listing 101-4

1 # app/config/config.yml 2 twig: 3 globals: 4 ga_tracking: "%ga_tracking%"

PDF brought to you by generated on February 10, 2014

Chapter 101: How to Inject Variables into all Templates (i.e. Global Variables) | 349

The same variable is available exactly as before.

Referencing Services
Instead of using static values, you can also set the value to a service. Whenever the global variable is accessed in the template, the service will be requested from the service container and you get access to that object.
The service is not loaded lazily. In other words, as soon as Twig is loaded, your service is instantiated, even if you never use that global variable.

To define a service as a global Twig variable, prefix the string with @. This should feel familiar, as it's the same syntax you use in service configuration.
Listing 101-5

1 # app/config/config.yml 2 twig: 3 # ... 4 globals: 5 user_management: "@acme_user.user_management"

Using a Twig Extension

If the global variable you want to set is more complicated - say an object - then you won't be able to use the above method. Instead, you'll need to create a Twig Extension and return the global variable as one of the entries in the getGlobals method.

PDF brought to you by generated on February 10, 2014

Chapter 101: How to Inject Variables into all Templates (i.e. Global Variables) | 350

Chapter 102

How to use and Register namespaced Twig Paths

New in version 2.2: Namespaced path support was added in 2.2.

Usually, when you refer to a template, you'll use the MyBundle:Subdir:filename.html.twig format (see Template Naming and Locations). Twig also natively offers a feature called "namespaced paths", and support is built-in automatically for all of your bundles. Take the following paths as an example:
Listing 102-1

1 {% extends "AcmeDemoBundle::layout.html.twig" %} 2 {% include "AcmeDemoBundle:Foo:bar.html.twig" %}

With namespaced paths, the following works as well:

Listing 102-2

1 {% extends "@AcmeDemo/layout.html.twig" %} 2 {% include "@AcmeDemo/Foo/bar.html.twig" %}

Both paths are valid and functional by default in Symfony2.

As an added bonus, the namespaced syntax is faster.

PDF brought to you by generated on February 10, 2014

Chapter 102: How to use and Register namespaced Twig Paths | 351

Registering your own namespaces

You can also register your own custom namespaces. Suppose that you're using some third-party library that includes Twig templates that live in vendor/acme/foo-bar/templates. First, register a namespace for this directory:
Listing 102-3

1 # app/config/config.yml 2 twig: 3 # ... 4 paths: 5 "%kernel.root_dir%/../vendor/acme/foo-bar/templates": foo_bar

The registered namespace is called foo_bar, which refers to the vendor/acme/foo-bar/templates directory. Assuming there's a file called sidebar.twig in that directory, you can use it easily:
Listing 102-4

1 {% include '@foo_bar/sidebar.twig' %}

PDF brought to you by generated on February 10, 2014

Chapter 102: How to use and Register namespaced Twig Paths | 352

Chapter 103

How to use PHP instead of Twig for Templates

Symfony2 defaults to Twig for its template engine, but you can still use plain PHP code if you want. Both templating engines are supported equally in Symfony2. Symfony2 adds some nice features on top of PHP to make writing templates with PHP more powerful.

Rendering PHP Templates

If you want to use the PHP templating engine, first, make sure to enable it in your application configuration file:
Listing 103-1

1 # app/config/config.yml 2 framework: 3 # ... 4 templating: 5 engines: ['twig', 'php']

You can now render a PHP template instead of a Twig one simply by using the .php extension in the template name instead of .twig. The controller below renders the index.html.php template:
Listing 103-2

1 2 3 4 5 6 7 8 9 10

// src/Acme/HelloBundle/Controller/HelloController.php // ... public function indexAction($name) { return $this->render( 'AcmeHelloBundle:Hello:index.html.php', array('name' => $name) ); }

You can also use the @Template AcmeHelloBundle:Hello:index.html.php template:

Listing 103-3

shortcut

to

render

the

default

PDF brought to you by generated on February 10, 2014

Chapter 103: How to use PHP instead of Twig for Templates | 353

1 2 3 4 5 6 7 8 9 10 11 12 13

// src/Acme/HelloBundle/Controller/HelloController.php
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

// ... /** * @Template(engine="php") */ public function indexAction($name) { return array('name' => $name); }

Decorating Templates
More often than not, templates in a project share common elements, like the well-known header and footer. In Symfony2, this problem is thought about differently: a template can be decorated by another one. The index.html.php template is decorated by layout.html.php, thanks to the extend() call:
Listing 103-4

1 <!-- src/Acme/HelloBundle/Resources/views/Hello/index.html.php --> 2 <?php $view->extend('AcmeHelloBundle::layout.html.php') ?> 3 4 Hello <?php echo $name ?>!

The AcmeHelloBundle::layout.html.php notation sounds familiar, doesn't it? It is the same notation used to reference a template. The :: part simply means that the controller element is empty, so the corresponding file is directly stored under views/. Now, have a look at the layout.html.php file:
Listing 103-5

1 2 3 4 5 6

<!-- src/Acme/HelloBundle/Resources/views/layout.html.php --> <?php $view->extend('::base.html.php') ?>

<h1>Hello Application</h1> <?php $view['slots']->output('_content') ?>

The layout is itself decorated by another one (::base.html.php). Symfony2 supports multiple decoration levels: a layout can itself be decorated by another one. When the bundle part of the template name is empty, views are looked for in the app/Resources/views/ directory. This directory stores global views for your entire project:
Listing 103-6

1 <!-- app/Resources/views/base.html.php --> 2 <!DOCTYPE html> 3 <html> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6 <title><?php $view['slots']->output('title', 'Hello Application') ?></title> 7 </head> 8 <body> 9 <?php $view['slots']->output('_content') ?>

PDF brought to you by generated on February 10, 2014

Chapter 103: How to use PHP instead of Twig for Templates | 354

10 </body> 11 </html>

For both layouts, the $view['slots']->output('_content') expression is replaced by the content of the child template, index.html.php and layout.html.php respectively (more on slots in the next section). As you can see, Symfony2 provides methods on a mysterious $view object. In a template, the $view variable is always available and refers to a special object that provides a bunch of methods that makes the template engine tick.

Working with Slots

A slot is a snippet of code, defined in a template, and reusable in any layout decorating the template. In the index.html.php template, define a title slot:
Listing 103-7

1 2 3 4 5 6

<!-- src/Acme/HelloBundle/Resources/views/Hello/index.html.php --> <?php $view->extend('AcmeHelloBundle::layout.html.php') ?>

<?php $view['slots']->set('title', 'Hello World Application') ?> Hello <?php echo $name ?>!

The base layout already has the code to output the title in the header:
Listing 103-8

1 <!-- app/Resources/views/base.html.php --> 2 <head> 3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 4 <title><?php $view['slots']->output('title', 'Hello Application') ?></title> 5 </head>

The output() method inserts the content of a slot and optionally takes a default value if the slot is not defined. And _content is just a special slot that contains the rendered child template. For large slots, there is also an extended syntax:
Listing 103-9

1 <?php $view['slots']->start('title') ?> 2 Some large amount of HTML 3 <?php $view['slots']->stop() ?>

Including other Templates

The best way to share a snippet of template code is to define a template that can then be included into other templates. Create a hello.html.php template:
Listing 103-10 1

<!-- src/Acme/HelloBundle/Resources/views/Hello/hello.html.php --> 2 Hello <?php echo $name ?>!

And change the index.html.php template to include it:

Listing 103-11

PDF brought to you by generated on February 10, 2014

Chapter 103: How to use PHP instead of Twig for Templates | 355

1 <!-- src/Acme/HelloBundle/Resources/views/Hello/index.html.php --> 2 <?php $view->extend('AcmeHelloBundle::layout.html.php') ?> 3 4 <?php echo $view->render('AcmeHelloBundle:Hello:hello.html.php', array('name' => $name)) ?>

The render() method evaluates and returns the content of another template (this is the exact same method as the one used in the controller).

Embedding other Controllers

And what if you want to embed the result of another controller in a template? That's very useful when working with Ajax, or when the embedded template needs some variable not available in the main template. If you create a fancy action, and want to include it into the index.html.php template, simply use the following code:
Listing 103-12 1

<!-- src/Acme/HelloBundle/Resources/views/Hello/index.html.php --> 2 <?php echo $view['actions']->render( 3 new ControllerReference('AcmeHelloBundle:Hello:fancy', array( 4 'name' => $name, 5 'color' => 'green', 6 )) 7 ) ?>

Here, the AcmeHelloBundle:Hello:fancy string refers to the fancy action of the Hello controller:
Listing 103-13

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

// src/Acme/HelloBundle/Controller/HelloController.php
class HelloController extends Controller { public function fancyAction($name, $color) { // create some object, based on the $color variable $object = ...; return $this->render('AcmeHelloBundle:Hello:fancy.html.php', array( 'name' => $name, 'object' => $object )); }

// ...
}

But where is the $view['actions'] array element defined? Like $view['slots'], it's called a template helper, and the next section tells you more about those.

Using Template Helpers

The Symfony2 templating system can be easily extended via helpers. Helpers are PHP objects that provide features useful in a template context. actions and slots are two of the built-in Symfony2 helpers.

PDF brought to you by generated on February 10, 2014

Chapter 103: How to use PHP instead of Twig for Templates | 356

Creating Links between Pages

Speaking of web applications, creating links between pages is a must. Instead of hardcoding URLs in templates, the router helper knows how to generate URLs based on the routing configuration. That way, all your URLs can be easily updated by changing the configuration:
Listing 103-14 1

<a href="<?php echo $view['router']->generate('hello', array('name' => 'Thomas')) ?>"> 2 Greet Thomas! 3 </a>

The generate() method takes the route name and an array of parameters as arguments. The route name is the main key under which routes are referenced and the parameters are the values of the placeholders defined in the route pattern:
Listing 103-15 1

# src/Acme/HelloBundle/Resources/config/routing.yml 2 hello: # The route name 3 path: /hello/{name} 4 defaults: { _controller: AcmeHelloBundle:Hello:index }

Using Assets: images, JavaScripts, and stylesheets

What would the Internet be without images, JavaScripts, and stylesheets? Symfony2 provides the assets tag to deal with them easily:
Listing 103-16

1 <link href="<?php echo $view['assets']->getUrl('css/blog.css') ?>" rel="stylesheet" 2 type="text/css" /> 3 <img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" />

The assets helper's main purpose is to make your application more portable. Thanks to this helper, you can move the application root directory anywhere under your web root directory without changing anything in your template's code.

Profiling Templates
By using the stopwatch helper, you are able to time parts of your template and display it on the timeline of the WebProfilerBundle:
Listing 103-17 1

<?php $view['stopwatch']->start('foo') ?> 2 ... things that get timed 3 <?php $view['stopwatch']->stop('foo') ?>

If you use the same name more than once in your template, the times are grouped on the same line in the timeline.

Output Escaping
When using PHP templates, escape variables whenever they are displayed to the user:

PDF brought to you by generated on February 10, 2014

Chapter 103: How to use PHP instead of Twig for Templates | 357

Listing 103-18 1

<?php echo $view->escape($var) ?>

By default, the escape() method assumes that the variable is outputted within an HTML context. The second argument lets you change the context. For instance, to output something in a JavaScript script, use the js context:
Listing 103-19 1

<?php echo $view->escape($var, 'js') ?>

PDF brought to you by generated on February 10, 2014

Chapter 103: How to use PHP instead of Twig for Templates | 358

Chapter 104

How to write a custom Twig Extension

The main motivation for writing an extension is to move often used code into a reusable class like adding support for internationalization. An extension can define tags, filters, tests, operators, global variables, functions, and node visitors. Creating an extension also makes for a better separation of code that is executed at compilation time and code needed at runtime. As such, it makes your code faster.
Before writing your own extensions, have a look at the Twig official extension repository1.

Create the Extension Class

This cookbook describes how to write a custom Twig extension as of Twig 1.12. If you are using an older version, please read Twig extensions documentation legacy2.

To get your custom functionality you must first create a Twig Extension class. As an example you'll create a price filter to format a given number into price:
Listing 104-1

1 2 3 4 5 6 7 8

// src/Acme/DemoBundle/Twig/AcmeExtension.php namespace Acme\DemoBundle\Twig;

class AcmeExtension extends \Twig_Extension { public function getFilters() { return array(

1. https://github.com/fabpot/Twig-extensions 2. http://twig.sensiolabs.org/doc/advanced_legacy.html#creating-an-extension

PDF brought to you by generated on February 10, 2014

Chapter 104: How to write a custom Twig Extension | 359

9 new \Twig_SimpleFilter('price', array($this, 'priceFilter')), 10 ); 11 } 12 13 public function priceFilter($number, $decimals = 0, $decPoint = '.', $thousandsSep = 14 ',') 15 { 16 $price = number_format($number, $decimals, $decPoint, $thousandsSep); 17 $price = '$'.$price; 18 19 return $price; 20 } 21 22 public function getName() 23 { 24 return 'acme_extension'; 25 } }

Along with custom filters, you can also add custom functions and register global variables.

Register an Extension as a Service

Now you must let the Service Container know about your newly created Twig Extension:
Listing 104-2

1 # src/Acme/DemoBundle/Resources/config/services.yml 2 services: 3 acme.twig.acme_extension: 4 class: Acme\DemoBundle\Twig\AcmeExtension 5 tags: 6 - { name: twig.extension }

Keep in mind that Twig Extensions are not lazily loaded. This means that there's a higher chance that you'll get a CircularReferenceException or a ScopeWideningInjectionException if any services (or your Twig Extension in this case) are dependent on the request service. For more information take a look at How to Work with Scopes.

Using the custom Extension

Using your newly created Twig Extension is no different than any other:
Listing 104-3

1 {# outputs $5,500.00 #} 2 {{ '5500'|price }}

Passing other arguments to your filter:

Listing 104-4

PDF brought to you by generated on February 10, 2014

Chapter 104: How to write a custom Twig Extension | 360

1 {# outputs $5500,2516 #} 2 {{ '5500.25155'|price(4, ',', '') }}

Learning further
For a more in-depth look into Twig Extensions, please take a look at the Twig extensions documentation3.

3. http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension

PDF brought to you by generated on February 10, 2014

Chapter 104: How to write a custom Twig Extension | 361

Chapter 105

How to render a Template without a custom Controller

Usually, when you need to create a page, you need to create a controller and render a template from within that controller. But if you're rendering a simple template that doesn't need any data passed into it, you can avoid creating the controller entirely, by using the built-in FrameworkBundle:Template:template controller. For example, suppose you want to render a AcmeBundle:Static:privacy.html.twig template, which doesn't require that any variables are passed to it. You can do this without creating a controller:
Listing 105-1

1 acme_privacy: 2 path: /privacy 3 defaults: 4 _controller: FrameworkBundle:Template:template 5 template: 'AcmeBundle:Static:privacy.html.twig'

The FrameworkBundle:Template:template controller will simply render whatever template you've passed as the template default value. You can of course also use this trick when rendering embedded controllers from within a template. But since the purpose of rendering a controller from within a template is typically to prepare some data in a custom controller, this is probably only useful if you'd like to cache this page partial (see Caching the static Template).
Listing 105-2

1 {{ render(url('acme_privacy')) }}

PDF brought to you by generated on February 10, 2014

Chapter 105: How to render a Template without a custom Controller | 362

Caching the static Template

New in version 2.2: The ability to cache FrameworkBundle:Template:template is new in Symfony 2.2. templates rendered via

Since templates that are rendered in this way are typically static, it might make sense to cache them. Fortunately, this is easy! By configuring a few other variables in your route, you can control exactly how your page is cached:
Listing 105-3

1 acme_privacy: 2 path: /privacy 3 defaults: 4 _controller: 5 template: 6 maxAge: 7 sharedMaxAge:

FrameworkBundle:Template:template 'AcmeBundle:Static:privacy.html.twig' 86400 86400

The maxAge and sharedMaxAge values are used to modify the Response object created in the controller. For more information on caching, see HTTP Cache. There is also a private variable (not shown here). By default, the Response will be made public, as long as maxAge or sharedMaxAge are passed. If set to true, the Response will be marked as private.

PDF brought to you by generated on February 10, 2014

Chapter 105: How to render a Template without a custom Controller | 363

Chapter 106

How to simulate HTTP Authentication in a Functional Test

If your application needs HTTP authentication, pass the username and password as server variables to createClient():
Listing 106-1

1 $client = static::createClient(array(), array( 2 'PHP_AUTH_USER' => 'username', 3 'PHP_AUTH_PW' => 'pa$$word', 4 ));

You can also override it on a per request basis:

Listing 106-2

1 $client->request('DELETE', '/post/12', array(), array(), array( 2 'PHP_AUTH_USER' => 'username', 3 'PHP_AUTH_PW' => 'pa$$word', 4 ));

When your application is using a form_login, you can simplify your tests by allowing your test configuration to make use of HTTP authentication. This way you can use the above to authenticate in tests, but still have your users log in via the normal form_login. The trick is to include the http_basic key in your firewall, along with the form_login key:
Listing 106-3

1 # app/config/config_test.yml 2 security: 3 firewalls: 4 your_firewall_name: 5 http_basic: ~

PDF brought to you by generated on February 10, 2014

Chapter 106: How to simulate HTTP Authentication in a Functional Test | 364

Chapter 107

How to simulate Authentication with a Token in a Functional Test

Authenticating requests in functional tests might slow down the suite. It could become an issue especially when form_login is used, since it requires additional requests to fill in and submit the form. One of the solutions is to configure your firewall to use http_basic in the test environment as explained in How to simulate HTTP Authentication in a Functional Test. Another way would be to create a token yourself and store it in a session. While doing this, you have to make sure that an appropriate cookie is sent with a request. The following example demonstrates this technique:
Listing 107-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

// src/Acme/DemoBundle/Tests/Controller/DemoControllerTest.php namespace Acme\DemoBundle\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase; use Symfony\Component\BrowserKit\Cookie; use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken; class DemoControllerTest extends WebTestCase { private $client = null; public function setUp() { $this->client = static::createClient(); } public function testSecuredHello() { $this->logIn(); $this->client->request('GET', '/demo/secured/hello/Fabien'); $this->assertTrue($this->client->getResponse()->isSuccessful()); $this->assertGreaterThan(0, $crawler->filter('html:contains("Hello Fabien")')->count());

PDF brought to you by generated on February 10, 2014

Chapter 107: How to simulate Authentication with a Token in a Functional Test | 365

26 27 28 29 30 31 32 33 34 35 36 37 38 39 }

} private function logIn() { $session = $this->client->getContainer()->get('session'); $firewall = 'secured_area'; $token = new UsernamePasswordToken('admin', null, $firewall, array('ROLE_ADMIN')); $session->set('_security_'.$firewall, serialize($token)); $session->save(); $cookie = new Cookie($session->getName(), $session->getId()); $this->client->getCookieJar()->set($cookie); }

The technique described in How to simulate HTTP Authentication in a Functional Test is cleaner and therefore the preferred way.

PDF brought to you by generated on February 10, 2014

Chapter 107: How to simulate Authentication with a Token in a Functional Test | 366

Chapter 108

How to test the Interaction of several Clients

If you need to simulate an interaction between different clients (think of a chat for instance), create several clients:
Listing 108-1

1 2 3 4 5 6 7 8 9 10

// ...
$harry = static::createClient(); $sally = static::createClient(); $harry->request('POST', '/say/sally/Hello'); $sally->request('GET', '/messages'); $this->assertEquals(Response::HTTP_CREATED, $harry->getResponse()->getStatusCode()); $this->assertRegExp('/Hello/', $sally->getResponse()->getContent());

New in version 2.4: Support for HTTP status code constants was added in Symfony 2.4.

This works except when your code maintains a global state or if it depends on a third-party library that has some kind of global state. In such a case, you can insulate your clients:
Listing 108-2

1 2 3 4 5 6 7 8 9 10 11

// ...
$harry = static::createClient(); $sally = static::createClient(); $harry->insulate(); $sally->insulate(); $harry->request('POST', '/say/sally/Hello'); $sally->request('GET', '/messages');

PDF brought to you by generated on February 10, 2014

Chapter 108: How to test the Interaction of several Clients | 367

12 $this->assertEquals(Response::HTTP_CREATED, $harry->getResponse()->getStatusCode()); 13 $this->assertRegExp('/Hello/', $sally->getResponse()->getContent());

Insulated clients transparently execute their requests in a dedicated and clean PHP process, thus avoiding any side-effects.
As an insulated client is slower, you can keep one client in the main process, and insulate the other ones.

PDF brought to you by generated on February 10, 2014

Chapter 108: How to test the Interaction of several Clients | 368

Chapter 109

How to use the Profiler in a Functional Test

It's highly recommended that a functional test only tests the Response. But if you write functional tests that monitor your production servers, you might want to write tests on the profiling data as it gives you a great way to check various things and enforce some metrics. The Symfony2 Profiler gathers a lot of data for each request. Use this data to check the number of database calls, the time spent in the framework, etc. But before writing assertions, enable the profiler and check that the profiler is indeed available (it is enabled by default in the test environment):
Listing 109-1

1 class HelloControllerTest extends WebTestCase 2 { 3 public function testIndex() 4 { 5 $client = static::createClient(); 6 7 // Enable the profiler for the next request (it does nothing if the profiler is 8 not available) 9 $client->enableProfiler(); 10 11 $crawler = $client->request('GET', '/hello/Fabien'); 12 13 // ... write some assertions about the Response 14 15 // Check that the profiler is enabled 16 if ($profile = $client->getProfile()) { 17 // check the number of requests 18 $this->assertLessThan( 19 10, 20 $profile->getCollector('db')->getQueryCount() 21 ); 22 23 // check the time spent in the framework 24 $this->assertLessThan( 25 500, 26 $profile->getCollector('time')->getDuration() 27 ); }

PDF brought to you by generated on February 10, 2014

Chapter 109: How to use the Profiler in a Functional Test | 369

28 29 }

If a test fails because of profiling data (too many DB queries for instance), you might want to use the Web Profiler to analyze the request after the tests finish. It's easy to achieve if you embed the token in the error message:
Listing 109-2

1 $this->assertLessThan( 2 30, 3 $profile->get('db')->getQueryCount(), 4 sprintf( 5 'Checks that query count is less than 30 (token %s)', 6 $profile->getToken() 7 ) 8 );

The profiler store can be different depending on the environment (especially if you use the SQLite store, which is the default configured one).

The profiler information is available even if you insulate the client or if you use an HTTP layer for your tests.

Read the API for built-in data collectors to learn more about their interfaces.

PDF brought to you by generated on February 10, 2014

Chapter 109: How to use the Profiler in a Functional Test | 370

Chapter 110

How to test code that interacts with the Database

If your code interacts with the database, e.g. reads data from or stores data into it, you need to adjust your tests to take this into account. There are many ways how to deal with this. In a unit test, you can create a mock for a Repository and use it to return expected objects. In a functional test, you may need to prepare a test database with predefined values to ensure that your test always has the same data to work with.
If you want to test your queries directly, see How to test Doctrine Repositories.

Mocking the Repository in a Unit Test

If you want to test code which depends on a Doctrine repository in isolation, you need to mock the Repository. Normally you inject the EntityManager into your class and use it to get the repository. This makes things a little more difficult as you need to mock both the EntityManager and your repository class.
It is possible (and a good idea) to inject your repository directly by registering your repository as a factory service. This is a little bit more work to setup, but makes testing easier as you only need to mock the repository.

Suppose the class you want to test looks like this:

Listing 110-1

1 namespace Acme\DemoBundle\Salary; 2 3 use Doctrine\Common\Persistence\ObjectManager; 4

PDF brought to you by generated on February 10, 2014

Chapter 110: How to test code that interacts with the Database | 371

5 class SalaryCalculator 6 { 7 private $entityManager; 8 9 public function __construct(ObjectManager $entityManager) 10 { 11 $this->entityManager = $entityManager; 12 } 13 14 public function calculateTotalSalary($id) 15 { 16 $employeeRepository = 17 $this->entityManager->getRepository('AcmeDemoBundle::Employee'); 18 $employee = $employeeRepository->find($id); 19 20 return $employee->getSalary() + $employee->getBonus(); 21 } }

Since the ObjectManager gets injected into the class through the constructor, it's easy to pass a mock object within a test:
Listing 110-2

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

use Acme\DemoBundle\Salary\SalaryCalculator; class SalaryCalculatorTest extends \PHPUnit_Framework_TestCase { public function testCalculateTotalSalary() { // First, mock the object to be used in the test $employee = $this->getMock('\Acme\DemoBundle\Entity\Employee'); $employee->expects($this->once()) ->method('getSalary') ->will($this->returnValue(1000)); $employee->expects($this->once()) ->method('getBonus') ->will($this->returnValue(1100));

// Now, mock the repository so it returns the mock of the employee $employeeRepository = $this->getMockBuilder('\Doctrine\ORM\EntityRepository') ->disableOriginalConstructor() ->getMock(); $employeeRepository->expects($this->once()) ->method('find') ->will($this->returnValue($employee)); // Last, mock the EntityManager to return the mock of the repository $entityManager = $this->getMockBuilder('\Doctrine\Common\Persistence\ObjectManager') ->disableOriginalConstructor() ->getMock(); $entityManager->expects($this->once()) ->method('getRepository') ->will($this->returnValue($employeeRepository));
$salaryCalculator = new SalaryCalculator($entityManager); $this->assertEquals(2100, $salaryCalculator->calculateTotalSalary(1)); } }

PDF brought to you by generated on February 10, 2014

Chapter 110: How to test code that interacts with the Database | 372

In this example, you are building the mocks from the inside out, first creating the employee which gets returned by the Repository, which itself gets returned by the EntityManager. This way, no real class is involved in testing.

Changing database Settings for functional Tests

If you have functional tests, you want them to interact with a real database. Most of the time you want to use a dedicated database connection to make sure not to overwrite data you entered when developing the application and also to be able to clear the database before every test. To do this, you can specify a database configuration which overwrites the default configuration:
Listing 110-3

1 # app/config/config_test.yml 2 doctrine: 3 # ... 4 dbal: 5 host: localhost 6 dbname: testdb 7 user: testdb 8 password: testdb

Make sure that your database runs on localhost and has the defined database and user credentials set up.

PDF brought to you by generated on February 10, 2014

Chapter 110: How to test code that interacts with the Database | 373

Chapter 111

How to test Doctrine Repositories

Unit testing Doctrine repositories in a Symfony project is not recommended. When you're dealing with a repository, you're really dealing with something that's meant to be tested against a real database connection. Fortunately, you can easily test your queries against a real database, as described below.

Functional Testing
If you need to actually execute a query, you will need to boot the kernel to get a valid connection. In this case, you'll extend the WebTestCase, which makes all of this quite easy:
Listing 111-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// src/Acme/StoreBundle/Tests/Entity/ProductRepositoryFunctionalTest.php namespace Acme\StoreBundle\Tests\Entity;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase; class ProductRepositoryFunctionalTest extends WebTestCase { /** * @var \Doctrine\ORM\EntityManager */ private $em;

/** * {@inheritDoc} */ public function setUp() { static::$kernel = static::createKernel(); static::$kernel->boot(); $this->em = static::$kernel->getContainer() ->get('doctrine') ->getManager() ;

PDF brought to you by generated on February 10, 2014

Chapter 111: How to test Doctrine Repositories | 374

24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 }

} public function testSearchByCategoryName() { $products = $this->em ->getRepository('AcmeStoreBundle:Product') ->searchByCategoryName('foo') ; $this->assertCount(1, $products); }

/** * {@inheritDoc} */ protected function tearDown() { parent::tearDown(); $this->em->close(); }

PDF brought to you by generated on February 10, 2014

Chapter 111: How to test Doctrine Repositories | 375

Chapter 112

How to customize the Bootstrap Process before running Tests

Sometimes when running tests, you need to do additional bootstrap work before running those tests. For example, if you're running a functional test and have introduced a new translation resource, then you will need to clear your cache before running those tests. This cookbook covers how to do that. First, add the following file:
Listing 112-1

1 2 3 4 5 6 7 8 9 10

// app/tests.bootstrap.php if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) { passthru(sprintf( 'php "%s/console" cache:clear --env=%s --no-warmup', __DIR__, $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'] )); }
require __DIR__.'/bootstrap.php.cache';

Replace the test bootstrap tests.bootstrap.php:

Listing 112-2

file

bootstrap.php.cache

in

app/phpunit.xml.dist

with

<!-- app/phpunit.xml.dist --> <!-- ... --> <phpunit ... bootstrap = "tests.bootstrap.php" >

Now, you can define in your phpunit.xml.dist file which environment you want the cache to be cleared:
Listing 112-3

PDF brought to you by generated on February 10, 2014

Chapter 112: How to customize the Bootstrap Process before running Tests | 376

1 <!-- app/phpunit.xml.dist --> 2 <php> 3 <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test"/> 4 </php>

This now becomes an environment variable (i.e. $_ENV) that's available in the custom bootstrap file (tests.bootstrap.php).

PDF brought to you by generated on February 10, 2014

Chapter 112: How to customize the Bootstrap Process before running Tests | 377

Chapter 113

How to create a Custom Validation Constraint

You can create a custom constraint by extending the base constraint class, Constraint1. As an example you're going to create a simple validator that checks if a string contains only alphanumeric characters.

Creating Constraint class

First you need to create a Constraint class and extend Constraint2:
Listing 113-1

1 2 3 4 5 6 7 8 9 10 11 12

// src/Acme/DemoBundle/Validator/Constraints/ContainsAlphanumeric.php namespace Acme\DemoBundle\Validator\Constraints;

use Symfony\Component\Validator\Constraint;

/** * @Annotation */ class ContainsAlphanumeric extends Constraint { public $message = 'The string "%string%" contains an illegal character: it can only contain letters or numbers.'; }

The @Annotation annotation is necessary for this new constraint in order to make it available for use in classes via annotations. Options for your constraint are represented as public properties on the constraint class.

1. http://api.symfony.com/2.4/Symfony/Component/Validator/Constraint.html 2. http://api.symfony.com/2.4/Symfony/Component/Validator/Constraint.html

PDF brought to you by generated on February 10, 2014

Chapter 113: How to create a Custom Validation Constraint | 378

Creating the Validator itself

As you can see, a constraint class is fairly minimal. The actual validation is performed by another "constraint validator" class. The constraint validator class is specified by the constraint's validatedBy() method, which includes some simple default logic:
Listing 113-2

1 2 3 4 5

// in the base Symfony\Component\Validator\Constraint class public function validatedBy() { return get_class($this).'Validator'; }

In other words, if you create a custom Constraint (e.g. MyConstraint), Symfony2 will automatically look for another class, MyConstraintValidator when actually performing the validation. The validator class is also simple, and only has one required method validate():
Listing 113-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

// src/Acme/DemoBundle/Validator/Constraints/ContainsAlphanumericValidator.php namespace Acme\DemoBundle\Validator\Constraints;

use Symfony\Component\Validator\Constraint; use Symfony\Component\Validator\ConstraintValidator; class ContainsAlphanumericValidator extends ConstraintValidator { public function validate($value, Constraint $constraint) { if (!preg_match('/^[a-zA-Za0-9]+$/', $value, $matches)) { $this->context->addViolation( $constraint->message, array('%string%' => $value) ); } } }

The validate method does not return a value; instead, it adds violations to the validator's context property with an addViolation method call if there are validation failures. Therefore, a value could be considered as being valid if it causes no violations to be added to the context. The first parameter of the addViolation call is the error message to use for that violation.

Using the new Validator

Using custom validators is very easy, just as the ones provided by Symfony2 itself:
Listing 113-4

1 # src/Acme/BlogBundle/Resources/config/validation.yml 2 Acme\DemoBundle\Entity\AcmeEntity: 3 properties: 4 name: 5 - NotBlank: ~ 6 - Acme\DemoBundle\Validator\Constraints\ContainsAlphanumeric: ~

If your constraint contains options, then they should be public properties on the custom Constraint class you created earlier. These options can be configured like options on core Symfony constraints.
PDF brought to you by generated on February 10, 2014 Chapter 113: How to create a Custom Validation Constraint | 379

Constraint Validators with Dependencies

If your constraint validator has dependencies, such as a database connection, it will need to be configured as a service in the dependency injection container. This service must include the validator.constraint_validator tag and an alias attribute:
Listing 113-5

1 services: 2 validator.unique.your_validator_name: 3 class: Fully\Qualified\Validator\Class\Name 4 tags: 5 - { name: validator.constraint_validator, alias: alias_name }

Your constraint class should now use this alias to reference the appropriate validator:
Listing 113-6

1 public function validatedBy() 2 { 3 return 'alias_name'; 4 }

As mentioned above, Symfony2 will automatically look for a class named after the constraint, with Validator appended. If your constraint validator is defined as a service, it's important that you override the validatedBy() method to return the alias used when defining your service, otherwise Symfony2 won't use the constraint validator service, and will instantiate the class instead, without any dependencies injected.

Class Constraint Validator

Beside validating a class property, a constraint can have a class scope by providing a target in its Constraint class:
Listing 113-7

1 public function getTargets() 2 { 3 return self::CLASS_CONSTRAINT; 4 }

With this, the validator validate() method gets an object as its first argument:
Listing 113-8

1 class ProtocolClassValidator extends ConstraintValidator 2 { 3 public function validate($protocol, Constraint $constraint) 4 { 5 if ($protocol->getFoo() != $protocol->getBar()) { 6 $this->context->addViolationAt( 7 'foo', 8 $constraint->message, 9 array(), 10 null 11 ); 12 } 13 } 14 }

Note that a class constraint validator is applied to the class itself, and not to the property:
Listing 113-9

PDF brought to you by generated on February 10, 2014

Chapter 113: How to create a Custom Validation Constraint | 380

1 # src/Acme/BlogBundle/Resources/config/validation.yml 2 Acme\DemoBundle\Entity\AcmeEntity: 3 constraints: 4 - Acme\DemoBundle\Validator\Constraints\ContainsAlphanumeric: ~

PDF brought to you by generated on February 10, 2014

Chapter 113: How to create a Custom Validation Constraint | 381

Chapter 114

How to Create a SOAP Web Service in a Symfony2 Controller

Setting up a controller to act as a SOAP server is simple with a couple tools. You must, of course, have the PHP SOAP1 extension installed. As the PHP SOAP extension can not currently generate a WSDL, you must either create one from scratch or use a 3rd party generator.
There are several SOAP server implementations available for use with PHP. Zend SOAP2 and NuSOAP3 are two examples. Although the PHP SOAP extension is used in these examples, the general idea should still be applicable to other implementations.

SOAP works by exposing the methods of a PHP object to an external entity (i.e. the person using the SOAP service). To start, create a class - HelloService - which represents the functionality that you'll expose in your SOAP service. In this case, the SOAP service will allow the client to call a method called hello, which happens to send an email:
Listing 114-1

1 2 3 4 5 6 7 8 9 10 11 12 13 14

// src/Acme/SoapBundle/Services/HelloService.php namespace Acme\SoapBundle\Services;

class HelloService { private $mailer; public function __construct(\Swift_Mailer $mailer) { $this->mailer = $mailer; } public function hello($name) {

1. http://php.net/manual/en/book.soap.php 2. http://framework.zend.com/manual/en/zend.soap.server.html 3. http://sourceforge.net/projects/nusoap

PDF brought to you by generated on February 10, 2014

Chapter 114: How to Create a SOAP Web Service in a Symfony2 Controller | 382

15 16 17 18 19 20 21 22 23 24 25 }

$message = \Swift_Message::newInstance() ->setTo('[email protected]') ->setSubject('Hello Service') ->setBody($name . ' says hi!'); $this->mailer->send($message); return 'Hello, '.$name; }

Next, you can train Symfony to be able to create an instance of this class. Since the class sends an e-mail, it's been designed to accept a Swift_Mailer instance. Using the Service Container, you can configure Symfony to construct a HelloService object properly:
Listing 114-2

1 # app/config/config.yml 2 services: 3 hello_service: 4 class: Acme\SoapBundle\Services\HelloService 5 arguments: ["@mailer"]

Below is an example of a controller that is capable of handling a SOAP request. If indexAction() is accessible via the route /soap, then the WSDL document can be retrieved via /soap?wsdl.
Listing 114-3

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

namespace Acme\SoapBundle\Controller; use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\HttpFoundation\Response; class HelloServiceController extends Controller { public function indexAction() { $server = new \SoapServer('/path/to/hello.wsdl'); $server->setObject($this->get('hello_service')); $response = new Response(); $response->headers->set('Content-Type', 'text/xml; charset=ISO-8859-1'); ob_start(); $server->handle(); $response->setContent(ob_get_clean()); return $response; } }

Take note of the calls to ob_start() and ob_get_clean(). These methods control output buffering4 which allows you to "trap" the echoed output of $server->handle(). This is necessary because Symfony expects your controller to return a Response object with the output as its "content". You must also remember to set the "Content-Type" header to "text/xml", as this is what the client will expect. So, you use ob_start() to start buffering the STDOUT and use ob_get_clean() to dump the echoed output into the content of the Response and clear the output buffer. Finally, you're ready to return the Response.

4. http://php.net/manual/en/book.outcontrol.php

PDF brought to you by generated on February 10, 2014

Chapter 114: How to Create a SOAP Web Service in a Symfony2 Controller | 383

Below is an example calling the service using a NuSOAP5 client. This example assumes that the indexAction in the controller above is accessible via the route /soap:
Listing 114-4

1 $client = new \Soapclient('http://example.com/app.php/soap?wsdl', true); 2 3 $result = $client->call('hello', array('name' => 'Scott'));

An example WSDL is below.

Listing 114-5

1 <?xml version="1.0" encoding="ISO-8859-1"?> 2 <definitions xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 3 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 4 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 5 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 6 xmlns:tns="urn:arnleadservicewsdl" 7 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 8 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 9 xmlns="http://schemas.xmlsoap.org/wsdl/" 10 targetNamespace="urn:helloservicewsdl"> 11 12 <types> 13 <xsd:schema targetNamespace="urn:hellowsdl"> 14 <xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/" /> 15 <xsd:import namespace="http://schemas.xmlsoap.org/wsdl/" /> 16 </xsd:schema> 17 </types> 18 19 <message name="helloRequest"> 20 <part name="name" type="xsd:string" /> 21 </message> 22 23 <message name="helloResponse"> 24 <part name="return" type="xsd:string" /> 25 </message> 26 27 <portType name="hellowsdlPortType"> 28 <operation name="hello"> 29 <documentation>Hello World</documentation> 30 <input message="tns:helloRequest"/> 31 <output message="tns:helloResponse"/> 32 </operation> 33 </portType> 34 35 <binding name="hellowsdlBinding" type="tns:hellowsdlPortType"> 36 <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> 37 <operation name="hello"> 38 <soap:operation soapAction="urn:arnleadservicewsdl#hello" style="rpc"/> 39 40 <input> 41 <soap:body use="encoded" namespace="urn:hellowsdl" 42 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> 43 </input> 44 45 <output> 46 <soap:body use="encoded" namespace="urn:hellowsdl" 47 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> 48 </output>

5. http://sourceforge.net/projects/nusoap

PDF brought to you by generated on February 10, 2014

Chapter 114: How to Create a SOAP Web Service in a Symfony2 Controller | 384

49 </operation> 50 </binding> 51 52 <service name="hellowsdl"> 53 <port name="hellowsdlPort" binding="tns:hellowsdlBinding"> 54 <soap:address location="http://example.com/app.php/soap" /> 55 </port> 56 </service> 57 </definitions>

PDF brought to you by generated on February 10, 2014

Chapter 114: How to Create a SOAP Web Service in a Symfony2 Controller | 385

Chapter 115

How to Create and store a Symfony2 Project in Git

Though this entry is specifically about Git, the same generic principles will apply if you're storing your project in Subversion.

Once you've read through Creating Pages in Symfony2 and become familiar with using Symfony, you'll no-doubt be ready to start your own project. In this cookbook article, you'll learn the best way to start a new Symfony2 project that's stored using the Git1 source control management system.

Initial Project Setup

To get started, you'll need to download Symfony and initialize your local git repository: 1. Download the Symfony2 Standard Edition2 without vendors. 2. Unzip/untar the distribution. It will create a folder called Symfony with your new project structure, config files, etc. Rename it to whatever you like. 3. Create a new file called .gitignore at the root of your new project (e.g. next to the composer.json file) and paste the following into it. Files matching these patterns will be ignored by Git:
Listing 115-1

1 2 3 4 5 6

/web/bundles/ /app/bootstrap* /app/cache/* /app/logs/* /vendor/ /app/config/parameters.yml

1. http://git-scm.com/ 2. http://symfony.com/download

PDF brought to you by generated on February 10, 2014

Chapter 115: How to Create and store a Symfony2 Project in Git | 386

You may also want to create a .gitignore file that can be used system-wide, in which case, you can find more information here: Github .gitignore3 This way you can exclude files/folders often used by your IDE for all of your projects.

4. Copy app/config/parameters.yml to app/config/parameters.yml.dist. The parameters.yml file is ignored by Git (see above) so that machine-specific settings like database passwords aren't committed. By creating the parameters.yml.dist file, new developers can quickly clone the project, copy this file to parameters.yml, customize it, and start developing. 5. Initialize your Git repository:
Listing 115-2

1 $ git init

6. Add all of the initial files to Git:

Listing 115-3

1 $ git add .

7. Create an initial commit with your started project:

Listing 115-4

1 $ git commit -m "Initial commit"

8. Finally, download all of the third-party vendor libraries by executing Composer. For details, see Updating Vendors. At this point, you have a fully-functional Symfony2 project that's correctly committed to Git. You can immediately begin development, committing the new changes to your Git repository. You can continue to follow along with the Creating Pages in Symfony2 chapter to learn more about how to configure and develop inside your application.
The Symfony2 Standard Edition comes with some example functionality. To remove the sample code, follow the instructions in the "How to remove the AcmeDemoBundle" article.

Managing Vendor Libraries with composer.json

How does it work?
Every Symfony project uses a group of third-party "vendor" libraries. One way or another the goal is to download these files into your vendor/ directory and, ideally, to give you some sane way to manage the exact version you need for each. By default, these libraries are downloaded by running a php composer.phar install "downloader" binary. This composer.phar file is from a library called Composer4 and you can read more about installing it in the Installation chapter. The composer.phar file reads from the composer.json file at the root of your project. This is an JSONformatted file, which holds a list of each of the external packages you need, the version to be downloaded and more. The composer.phar file also reads from a composer.lock file, which allows you to pin each library to an exact version. In fact, if a composer.lock file exists, the versions inside will override those in composer.json. To upgrade your libraries to new versions, run php composer.phar update.
3. https://help.github.com/articles/ignoring-files 4. http://getcomposer.org/

PDF brought to you by generated on February 10, 2014

Chapter 115: How to Create and store a Symfony2 Project in Git | 387

If you want to add a new package to your application, modify the composer.json file:
Listing 115-5

{ "require": { ... "doctrine/doctrine-fixtures-bundle": "@dev" } }

and then execute the update command for this specific package, i.e.:
Listing 115-6

1 $ php composer.phar update doctrine/doctrine-fixtures-bundle

You can also combine both steps into a single command:

Listing 115-7

1 $ php composer.phar require doctrine/doctrine-fixtures-bundle:@dev

To learn more about Composer, see GetComposer.org5: It's important to realize that these vendor libraries are not actually part of your repository. Instead, they're simply un-tracked files that are downloaded into the vendor/. But since all the information needed to download these files is saved in composer.json and composer.lock (which are stored in the repository), any other developer can use the project, run php composer.phar install, and download the exact same set of vendor libraries. This means that you're controlling exactly what each vendor library looks like, without needing to actually commit them to your repository. So, whenever a developer uses your project, they should run the php composer.phar install script to ensure that all of the needed vendor libraries are downloaded.

Upgrading Symfony
Since Symfony is just a group of third-party libraries and third-party libraries are entirely controlled through composer.json and composer.lock, upgrading Symfony means simply upgrading each of these files to match their state in the latest Symfony Standard Edition. Of course, if you've added new entries to composer.json, be sure to replace only the original parts (i.e. be sure not to also delete any of your custom entries).

Vendors and Submodules

Instead of using the composer.json system for managing your vendor libraries, you may instead choose to use native git submodules6. There is nothing wrong with this approach, though the composer.json system is the official way to solve this problem and probably much easier to deal with. Unlike Git submodules, Composer is smart enough to calculate which libraries depend on which other libraries.

Storing your Project on a Remote Server

You now have a fully-functional Symfony2 project stored in Git. However, in most cases, you'll also want to store your project on a remote server both for backup purposes, and so that other developers can collaborate on the project.

5. http://getcomposer.org/ 6. http://git-scm.com/book/en/Git-Tools-Submodules

PDF brought to you by generated on February 10, 2014

Chapter 115: How to Create and store a Symfony2 Project in Git | 388

The easiest way to store your project on a remote server is via a web-based hosting service like GitHub7 or Bitbucket8. Of course, there are more services out there, you can start your research with a comparison of hosting services9. Alternatively, you can store your Git repository on any server by creating a barebones repository10 and then pushing to it. One library that helps manage this is Gitolite11.

7. https://github.com/ 8. https://bitbucket.org/ 9. http://en.wikipedia.org/wiki/Comparison_of_open-source_software_hosting_facilities 10. http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository 11. https://github.com/sitaramc/gitolite

PDF brought to you by generated on February 10, 2014

Chapter 115: How to Create and store a Symfony2 Project in Git | 389

Chapter 116

How to Create and store a Symfony2 Project in Subversion

This entry is specifically about Subversion, and based on principles found in How to Create and store a Symfony2 Project in Git.

Once you've read through Creating Pages in Symfony2 and become familiar with using Symfony, you'll no-doubt be ready to start your own project. The preferred method to manage Symfony2 projects is using Git1 but some prefer to use Subversion2 which is totally fine!. In this cookbook article, you'll learn how to manage your project using SVN3 in a similar manner you would do with Git4.
This is a method to tracking your Symfony2 project in a Subversion repository. There are several ways to do and this one is simply one that works.

The Subversion Repository

For this article it's assumed that your repository layout follows the widespread standard structure:
Listing 116-1

1 myproject/ 2 branches/ 3 tags/ 4 trunk/

1. http://git-scm.com/ 2. http://subversion.apache.org/ 3. http://subversion.apache.org/ 4. http://git-scm.com/

PDF brought to you by generated on February 10, 2014

Chapter 116: How to Create and store a Symfony2 Project in Subversion | 390

Most Subversion hosting should follow this standard practice. This is the recommended layout in Version Control with Subversion5 and the layout used by most free hosting (see Subversion hosting solutions).

Initial Project Setup

To get started, you'll need to download Symfony2 and get the basic Subversion setup: 1. Download the Symfony2 Standard Edition6 with or without vendors. 2. Unzip/untar the distribution. It will create a folder called Symfony with your new project structure, config files, etc. Rename it to whatever you like. 3. Checkout the Subversion repository that will host this project. Suppose it is hosted on Google code7 and called myproject:
Listing 116-2

1 $ svn checkout http://myproject.googlecode.com/svn/trunk myproject

4. Copy the Symfony2 project files in the Subversion folder:

Listing 116-3

1 $ mv Symfony/* myproject/

5. Now, set the ignore rules. Not everything should be stored in your Subversion repository. Some files (like the cache) are generated and others (like the database configuration) are meant to be customized on each machine. This makes use of the svn:ignore property, so that specific files can be ignored.
Listing 116-4

1 2 3 4 5 6 7 8 9 10 11 12

$ cd myproject/ $ svn add --depth=empty app app/cache app/logs app/config web $ $ $ $ $ svn svn svn svn svn propset propset propset propset propset svn:ignore svn:ignore svn:ignore svn:ignore svn:ignore "vendor" . "bootstrap*" app/ "parameters.yml" app/config/ "*" app/cache/ "*" app/logs/

$ svn propset svn:ignore "bundles" web $ svn ci -m "commit basic Symfony ignore list (vendor, app/bootstrap*, app/config/ parameters.yml, app/cache/*, app/logs/*, web/bundles)"

6. The rest of the files can now be added and committed to the project:
Listing 116-5

1 $ svn add --force . 2 $ svn ci -m "add basic Symfony Standard 2.X.Y"

7. Copy app/config/parameters.yml to app/config/parameters.yml.dist. The parameters.yml file is ignored by svn (see above) so that machine-specific settings like database passwords aren't committed. By creating the parameters.yml.dist file, new developers can quickly clone the project, copy this file to parameters.yml, customize it, and start developing.

5. http://svnbook.red-bean.com/ 6. http://symfony.com/download 7. http://code.google.com/hosting/

PDF brought to you by generated on February 10, 2014

Chapter 116: How to Create and store a Symfony2 Project in Subversion | 391

8. Finally, download all of the third-party vendor libraries by executing Composer. For details, see Updating Vendors.
If you rely on any "dev" versions, then Git may be used to install those libraries, since there is no archive available for download.

At this point, you have a fully-functional Symfony2 project stored in your Subversion repository. The development can start with commits in the Subversion repository. You can continue to follow along with the Creating Pages in Symfony2 chapter to learn more about how to configure and develop inside your application.
The Symfony2 Standard Edition comes with some example functionality. To remove the sample code, follow the instructions in the "How to remove the AcmeDemoBundle" article.

Managing Vendor Libraries with composer.json

How does it work?
Every Symfony project uses a group of third-party "vendor" libraries. One way or another the goal is to download these files into your vendor/ directory and, ideally, to give you some sane way to manage the exact version you need for each. By default, these libraries are downloaded by running a php composer.phar install "downloader" binary. This composer.phar file is from a library called Composer8 and you can read more about installing it in the Installation chapter. The composer.phar file reads from the composer.json file at the root of your project. This is an JSONformatted file, which holds a list of each of the external packages you need, the version to be downloaded and more. The composer.phar file also reads from a composer.lock file, which allows you to pin each library to an exact version. In fact, if a composer.lock file exists, the versions inside will override those in composer.json. To upgrade your libraries to new versions, run php composer.phar update.
If you want to add a new package to your application, modify the composer.json file:
Listing 116-6

{ "require": { ... "doctrine/doctrine-fixtures-bundle": "@dev" } }

and then execute the update command for this specific package, i.e.:
Listing 116-7

1 $ php composer.phar update doctrine/doctrine-fixtures-bundle

You can also combine both steps into a single command:

Listing 116-8

1 $ php composer.phar require doctrine/doctrine-fixtures-bundle:@dev

8. http://getcomposer.org/

PDF brought to you by generated on February 10, 2014

Chapter 116: How to Create and store a Symfony2 Project in Subversion | 392

To learn more about Composer, see GetComposer.org9: It's important to realize that these vendor libraries are not actually part of your repository. Instead, they're simply un-tracked files that are downloaded into the vendor/. But since all the information needed to download these files is saved in composer.json and composer.lock (which are stored in the repository), any other developer can use the project, run php composer.phar install, and download the exact same set of vendor libraries. This means that you're controlling exactly what each vendor library looks like, without needing to actually commit them to your repository. So, whenever a developer uses your project, they should run the php composer.phar install script to ensure that all of the needed vendor libraries are downloaded.

Upgrading Symfony
Since Symfony is just a group of third-party libraries and third-party libraries are entirely controlled through composer.json and composer.lock, upgrading Symfony means simply upgrading each of these files to match their state in the latest Symfony Standard Edition. Of course, if you've added new entries to composer.json, be sure to replace only the original parts (i.e. be sure not to also delete any of your custom entries).

Subversion hosting solutions

The biggest difference between Git10 and SVN11 is that Subversion needs a central repository to work. You then have several solutions: Self hosting: create your own repository and access it either through the filesystem or the network. To help in this task you can read Version Control with Subversion. Third party hosting: there are a lot of serious free hosting solutions available like GitHub12, Google code13, SourceForge14 or Gna15. Some of them offer Git hosting as well.

9. http://getcomposer.org/ 10. http://git-scm.com/ 11. http://subversion.apache.org/ 12. https://github.com/ 13. http://code.google.com/hosting/ 14. http://sourceforge.net/ 15. http://gna.org/

PDF brought to you by generated on February 10, 2014

Chapter 116: How to Create and store a Symfony2 Project in Subversion | 393