Merge branch '2.4'

Author: weaverryan

book/doctrine.rst

@@ -553,7 +553,8 @@ them for you. Here's the same sample application, now built in Symfony2::
     {
         public function listAction()
         {
-            $posts = $this->get('doctrine')->getManager()
+            $posts = $this->get('doctrine')
+                ->getManager()
                 ->createQuery('SELECT p FROM AcmeBlogBundle:Post p')
                 ->execute();
 
@@ -568,8 +569,7 @@ them for you. Here's the same sample application, now built in Symfony2::
             $post = $this->get('doctrine')
                 ->getManager()
                 ->getRepository('AcmeBlogBundle:Post')
-                ->find($id)
-            ;
+                ->find($id);
 
             if (!$post) {
                 // cause the 404 page not found to be displayed

book/from_flat_php_to_symfony2.rst

@@ -542,7 +542,7 @@ regardless of how your project is developed. To name a few:
 * `Security`_ - A powerful library for handling all types of security inside
   an application;
 
-* `Translation`_ A framework for translating strings in your application.
+* `Translation`_ - A framework for translating strings in your application.
 
 Each and every one of these components is decoupled and can be used in *any*
 PHP project, regardless of whether or not you use the Symfony2 framework.

book/http_fundamentals.rst

@@ -0,0 +1,43 @@
+.. index::
+   single: Doctrine; ORM console commands
+   single: CLI; Doctrine ORM
+
+Console Commands
+----------------
+
+The Doctrine2 ORM integration offers several console commands under the
+``doctrine`` namespace. To view the command list you can use the ``list``
+command:
+
+.. code-block:: bash
+
+    $ php app/console list doctrine
+
+A list of available commands will print out. You can find out more information
+about any of these commands (or any Symfony command) by running the ``help``
+command. For example, to get details about the ``doctrine:database:create``
+task, run:
+
+.. code-block:: bash
+
+    $ php app/console help doctrine:database:create
+
+Some notable or interesting tasks include:
+
+* ``doctrine:ensure-production-settings`` - checks to see if the current
+  environment is configured efficiently for production. This should always
+  be run in the ``prod`` environment:
+
+  .. code-block:: bash
+
+      $ php app/console doctrine:ensure-production-settings --env=prod
+
+* ``doctrine:mapping:import`` - allows Doctrine to introspect an existing
+  database and create mapping information. For more information, see
+  :doc:`/cookbook/doctrine/reverse_engineering`.
+
+* ``doctrine:mapping:info`` - tells you all of the entities that Doctrine
+  is aware of and whether or not there are any basic errors with the mapping.
+
+* ``doctrine:query:dql`` and ``doctrine:query:sql`` - allow you to execute
+  DQL or SQL queries directly from the command line.

cookbook/doctrine/console.rst

@@ -14,3 +14,4 @@ Doctrine
     resolve_target_entity
     mapping_model_classes
     registration_form
+    console

cookbook/doctrine/index.rst

@@ -216,6 +216,7 @@ Next, create the form for this ``Registration`` model::
                 'checkbox',
                 array('property_path' => 'termsAccepted')
             );
+            $builder->add('Register', 'submit');
         }
 
         public function getName()
@@ -239,7 +240,6 @@ controller for displaying the registration form::
     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;
@@ -270,6 +270,9 @@ And its template:
 Next, create the controller which handles the form submission. This performs
 the validation and saves the data into the database::
 
+    use Symfony\Component\HttpFoundation\Request;
+    // ...
+
     public function createAction(Request $request)
     {
         $em = $this->getDoctrine()->getManager();

cookbook/doctrine/registration_form.rst

@@ -62,6 +62,7 @@
   * :doc:`/cookbook/doctrine/resolve_target_entity`
   * :doc:`/cookbook/doctrine/mapping_model_classes`
   * :doc:`/cookbook/doctrine/registration_form`
+  * :doc:`/cookbook/doctrine/console`
 
 * :doc:`/cookbook/email/index`
 
@@ -132,6 +133,7 @@
   * :doc:`/cookbook/security/remember_me`
   * :doc:`/cookbook/security/impersonating_user`
   * :doc:`/cookbook/security/voters`
+  * :doc:`/cookbook/security/voters_data_permission`
   * :doc:`/cookbook/security/acl`
   * :doc:`/cookbook/security/acl_advanced`
   * :doc:`/cookbook/security/force_https`

cookbook/map.rst.inc

@@ -14,7 +14,7 @@ the ACL system comes in.
     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
-    :doc:`voters </cookbook/security/voters>`. A voter is passed the object
+    :doc:`voters </cookbook/security/voters_data_permission>`. 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

cookbook/security/acl.rst

@@ -8,6 +8,7 @@ Security
     remember_me
     impersonating_user
     voters
+    voters_data_permission
     acl
     acl_advanced
     force_https

cookbook/security/index.rst

@@ -0,0 +1,24 @@
+.. code-block:: php
+
+    interface VoterInterface
+    {
+        public function supportsAttribute($attribute);
+        public function supportsClass($class);
+        public function vote(TokenInterface $token, $post, array $attributes);
+    }
+
+The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::supportsAttribute`
+method is used to check if the voter supports the given user attribute (i.e:
+a role like ``ROLE_USER``, an ACL ``EDIT``, etc.).
+
+The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::supportsClass`
+method is used to check if the voter supports the class of the object whose
+access is being checked.
+
+The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::vote`
+method must implement the business logic that verifies whether or not the
+user has access. This method must return one of the following values:
+
+* ``VoterInterface::ACCESS_GRANTED``: The authorization will be granted by this voter;
+* ``VoterInterface::ACCESS_ABSTAIN``: The voter cannot decide if authorization should be granted;
+* ``VoterInterface::ACCESS_DENIED``: The authorization will be denied by this voter.

cookbook/security/voter_interface.rst.inc

@@ -21,28 +21,7 @@ A custom voter must implement
 :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
 which requires the following three methods:
 
-.. code-block:: php
-
-    interface VoterInterface
-    {
-        public function supportsAttribute($attribute);
-        public function supportsClass($class);
-        public function vote(TokenInterface $token, $object, array $attributes);
-    }
-
-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;
-* ``VoterInterface::ACCESS_ABSTAIN``: The voter cannot decide if authorization should be granted;
-* ``VoterInterface::ACCESS_DENIED``: The authorization will be denied by this voter.
+.. include:: /cookbook/security/voter_interface.rst.inc
 
 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

cookbook/security/voters.rst

@@ -0,0 +1,225 @@
+.. index::
+   single: Security; Data Permission Voters
+
+How to Use Voters to Check User Permissions
+===========================================
+
+In Symfony2 you can check the permission to access data by using the
+:doc:`ACL module </cookbook/security/acl>`, which is a bit overwhelming
+for many applications. A much easier solution is to work with custom voters,
+which are like simple conditional statements.
+
+.. seealso::
+
+    Voters can also be used in other ways, like, for example, blacklisting IP
+    addresses from the entire application: :doc:`/cookbook/security/voters`.
+
+.. tip::
+
+    Take a look at the
+    :doc:`authorization </components/security/authorization>`
+    chapter for an even deeper understanding on voters.
+
+How Symfony Uses Voters
+-----------------------
+
+In order to use voters, you have to understand how Symfony works with them.
+All voters are called each time you use the ``isGranted()`` method on Symfony's
+security context (i.e. the ``security.context`` service). Each one decides
+if the current user should have access to some resource.
+
+Ultimately, Symfony uses one of three different approaches on what to do
+with the feedback from all voters: affirmative, consensus and unanimous.
+
+For more information take a look at
+:ref:`the section about access decision managers <components-security-access-decision-manager>`.
+
+The Voter Interface
+-------------------
+
+A custom voter must implement
+:class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
+which has this structure:
+
+.. include:: /cookbook/security/voter_interface.rst.inc
+
+In this example, the voter will check if the user has access to a specific
+object according to your custom conditions (e.g. they must be the owner of
+the object). If the condition fails, you'll return
+``VoterInterface::ACCESS_DENIED``, otherwise you'll return
+``VoterInterface::ACCESS_GRANTED``. In case the responsibility for this decision
+does not belong to this voter, it will return ``VoterInterface::ACCESS_ABSTAIN``.
+
+Creating the Custom Voter
+-------------------------
+
+The goal is to create a voter that checks if a user has access to view or
+edit a particular object. Here's an example implementation:
+
+    // src/Acme/DemoBundle/Security/Authorization/Voter/PostVoter.php
+    namespace Acme\DemoBundle\Security\Authorization\Voter;
+
+    use Symfony\Component\Security\Core\Exception\InvalidArgumentException;
+    use Symfony\Component\DependencyInjection\ContainerInterface;
+    use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
+    use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+    use Symfony\Component\Security\Core\User\UserInterface;
+    use Acme\DemoBundle\Entity\Post;
+
+    class PostVoter implements VoterInterface
+    {
+        const VIEW = 'view';
+        const EDIT = 'edit';
+
+        public function supportsAttribute($attribute)
+        {
+            return in_array($attribute, array(
+                self::VIEW,
+                self::EDIT,
+            ));
+        }
+
+        public function supportsClass($obj)
+        {
+            return $obj instanceof Post;
+        }
+
+        /**
+         * @var \Acme\DemoBundle\Entity\Post $post
+         */
+        public function vote(TokenInterface $token, $post, array $attributes)
+        {
+            // check if class of this object is supported by this voter
+            if (!$this->supportsClass($post)) {
+                return VoterInterface::ACCESS_ABSTAIN;
+            }
+
+            // check if the voter is used correct, only allow one attribute
+            // this isn't a requirement, it's just one easy way for you to
+            // design your voter
+            if(1 !== count($attributes)) {
+                throw new InvalidArgumentException(
+                    'Only one attribute is allowed for VIEW or EDIT'
+                );
+            }
+
+            // set the attribute to check against
+            $attribute = $attributes[0];
+
+            // get current logged in user
+            $user = $token->getUser();
+
+            // check if the given attribute is covered by this voter
+            if (!$this->supportsAttribute($attribute)) {
+                return VoterInterface::ACCESS_ABSTAIN;
+            }
+
+            // make sure there is a user object (i.e. that the user is logged in)
+            if (!$user instanceof UserInterface) {
+                return VoterInterface::ACCESS_DENIED;
+            }
+
+            switch($attribute) {
+                case 'view':
+                    // the data object could have for example a method isPrivate()
+                    // which checks the Boolean attribute $private
+                    if (!$post->isPrivate()) {
+                        return VoterInterface::ACCESS_GRANTED;
+                    }
+                    break;
+
+                case 'edit':
+                    // we assume that our data object has a method getOwner() to
+                    // get the current owner user entity for this data object
+                    if ($user->getId() === $post->getOwner()->getId()) {
+                        return VoterInterface::ACCESS_GRANTED;
+                    }
+                    break;
+            }
+        }
+    }
+
+That's it! The voter is done. The next step is to inject the voter into
+the security layer.
+
+Declaring the Voter as a Service
+--------------------------------
+
+To inject the voter into the security layer, you must declare it as a service
+and tag it with ``security.voter``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/Acme/DemoBundle/Resources/config/services.yml
+        services:
+            security.access.post_voter:
+                class:      Acme\DemoBundle\Security\Authorization\Voter\PostVoter
+                public:     false
+                tags:
+                   - { name: security.voter }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/DemoBundle/Resources/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+            <services>
+                <service id="security.access.post_document_voter"
+                    class="Acme\DemoBundle\Security\Authorization\Voter\PostVoter"
+                    public="false">
+                    <tag name="security.voter" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // src/Acme/DemoBundle/Resources/config/services.php
+        $container
+            ->register(
+                    'security.access.post_document_voter',
+                    'Acme\DemoBundle\Security\Authorization\Voter\PostVoter'
+            )
+            ->addTag('security.voter')
+        ;
+
+How to Use the Voter in a Controller
+------------------------------------
+
+The registered voter will then always be asked as soon as the method ``isGranted()``
+from the security context is called.
+
+.. code-block:: php
+
+    // src/Acme/DemoBundle/Controller/PostController.php
+    namespace Acme\DemoBundle\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+
+    class PostController extends Controller
+    {
+        public function showAction()
+        {
+            // get a Post instance
+            $post = ...;
+
+            // keep in mind, this will call all registered security voters
+            if (false === $this->get('security.context')->isGranted('view', $post)) {
+                throw new AccessDeniedException('Unauthorised access!');
+            }
+
+            $product = $this->getDoctrine()
+                ->getRepository('AcmeStoreBundle:Post')
+                ->find($id);
+
+            return new Response('<h1>'.$post->getName().'</h1>');
+        }
+    }
+
+It's that easy!

cookbook/security/voters_data_permission.rst

@@ -11,13 +11,12 @@ Understanding the Directory Structure
 -------------------------------------
 
 The directory structure of a Symfony2 :term:`application` is rather flexible,
-but the directory structure of the *Standard Edition* distribution reflects
-the typical and recommended structure of a Symfony2 application:
+but the recommended structure is as follows:
 
-* ``app/``:    The application configuration;
-* ``src/``:    The project's PHP code;
-* ``vendor/``: The third-party dependencies;
-* ``web/``:    The web root directory.
+* ``app/``:    the application configuration;
+* ``src/``:    the project's PHP code;
+* ``vendor/``: the third-party dependencies;
+* ``web/``:    the web root directory.
 
 The ``web/`` Directory
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -36,11 +35,10 @@ lives::
     $kernel->loadClassCache();
     $kernel->handle(Request::createFromGlobals())->send();
 
-The kernel first requires the ``bootstrap.php.cache`` file, which bootstraps
-the framework and registers the autoloader (see below).
-
-Like any front controller, ``app.php`` uses a Kernel Class, ``AppKernel``, to
-bootstrap the application.
+The controller first bootstraps the application using a kernel class (``AppKernel``
+in this case). Then, it creates the ``Request`` object using the PHP's global
+variables and passes it to the kernel. The last step is to send the response
+contents returned by the kernel back to the user.
 
 .. _the-app-dir:
 
@@ -59,17 +57,11 @@ This class must implement two methods:
   (more on this later).
 
 Autoloading is handled automatically via `Composer`_, which means that you
-can use any PHP classes without doing anything at all! If you need more flexibility,
-you can extend the autoloader in the ``app/autoload.php`` file. All dependencies
+can use any PHP class without doing anything at all! All dependencies
 are stored under the ``vendor/`` directory, but this is just a convention.
 You can store them wherever you want, globally on your server or locally
 in your projects.
 
-.. note::
-
-    If you want to learn more about Composer's autoloader, read `Composer-Autoloader`_.
-    Symfony also has an autoloading component - read ":doc:`/components/class_loader/class_loader`".
-
 Understanding the Bundle System
 -------------------------------
 
@@ -79,12 +71,13 @@ Symfony2, the :term:`bundle` system.
 A bundle is kind of like a plugin in other software. So why is it called a
 *bundle* and not a *plugin*? This is because *everything* is a bundle in
 Symfony2, from the core framework features to the code you write for your
-application. Bundles are first-class citizens in Symfony2. This gives you
-the flexibility to use pre-built features packaged in third-party bundles
-or to distribute your own bundles. It makes it easy to pick and choose which
-features to enable in your application and optimize them the way you want.
-And at the end of the day, your application code is just as *important* as
-the core framework itself.
+application.
+
+Bundles are first-class citizens in Symfony2. This gives you the flexibility
+to use pre-built features packaged in third-party bundles or to distribute your
+own bundles. It makes it easy to pick and choose which features to enable in
+your application and optimize them the way you want. And at the end of the day,
+your application code is just as *important* as the core framework itself.
 
 Registering a Bundle
 ~~~~~~~~~~~~~~~~~~~~
@@ -119,14 +112,14 @@ a single ``Bundle`` class that describes it::
 
 In addition to the AcmeDemoBundle that was already talked about, notice
 that the kernel also enables other bundles such as the FrameworkBundle,
-DoctrineBundle, SwiftmailerBundle, and AsseticBundle bundle.
-They are all part of the core framework.
+DoctrineBundle, SwiftmailerBundle and AsseticBundle bundle. They are all part
+of the core framework.
 
 Configuring a Bundle
 ~~~~~~~~~~~~~~~~~~~~
 
 Each bundle can be customized via configuration files written in YAML, XML, or
-PHP. Have a look at the default configuration:
+PHP. Have a look at the default Symfony configuration:
 
 .. code-block:: yaml
 
@@ -191,9 +184,9 @@ PHP. Have a look at the default configuration:
         password:  "%mailer_password%"
         spool:     { type: memory }
 
-Each entry like ``framework`` defines the configuration for a specific bundle.
-For example, ``framework`` configures the FrameworkBundle while ``swiftmailer``
-configures the SwiftmailerBundle.
+Each first level entry like ``framework``, ``twig`` or ``doctrine`` defines the
+configuration for a specific bundle. For example, ``framework`` configures the
+FrameworkBundle while ``swiftmailer`` configures the SwiftmailerBundle.
 
 Each :term:`environment` can override the default configuration by providing a
 specific configuration file. For example, the ``dev`` environment loads the
@@ -268,7 +261,7 @@ Extending Bundles
 
 If you follow these conventions, then you can use :doc:`bundle inheritance</cookbook/bundles/inheritance>`
 to "override" files, controllers or templates. For example, you can create
-a bundle - ``AcmeNewBundle`` - and specify that it overrides AcmeDemoBundle.
+a bundle - AcmeNewBundle - and specify that it overrides AcmeDemoBundle.
 When Symfony loads the ``AcmeDemoBundle:Welcome:index`` controller, it will
 first look for the ``WelcomeController`` class in AcmeNewBundle and, if
 it doesn't exist, then look inside AcmeDemoBundle. This means that one bundle
@@ -296,8 +289,9 @@ each request? The speed is partly due to its cache system. The application
 configuration is only parsed for the very first request and then compiled down
 to plain PHP code stored in the ``app/cache/`` directory. In the development
 environment, Symfony2 is smart enough to flush the cache when you change a
-file. But in the production environment, it is your responsibility to clear
-the cache when you update your code or change its configuration.
+file. But in the production environment, to speed things up, it is your
+responsibility to clear the cache when you update your code or change its
+configuration.
 
 When developing a web application, things can go wrong in many ways. The log
 files in the ``app/logs/`` directory tell you everything about the requests
@@ -336,4 +330,3 @@ topics now? Look no further - go to the official :doc:`/book/index` and pick
 any topic you want.
 
 .. _Composer:   http://getcomposer.org
-.. _`Composer-Autoloader`: http://getcomposer.org/doc/01-basic-usage.md#autoloading

images/quick_tour/hello_fabien.png

@@ -28,8 +28,8 @@ in Symfony2 is straightforward. Tweak the route by adding a default value of
         return array('name' => $name);
     }
 
-By using the request format (as defined by the ``_format`` value), Symfony2
-automatically selects the right template, here ``hello.xml.twig``:
+By using the request format (as defined by the special ``_format`` variable),
+Symfony2 automatically selects the right template, here ``hello.xml.twig``:
 
 .. code-block:: xml+php
 
@@ -50,18 +50,23 @@ placeholder in the route path instead::
     // ...
 
     /**
-     * @Route("/hello/{name}.{_format}", defaults={"_format"="html"}, requirements={"_format"="html|xml|json"}, name="_demo_hello")
+     * @Route(
+     *     "/hello/{name}.{_format}",
+     *     defaults = { "_format" = "html" },
+     *     requirements = { "_format" = "html|xml|json" },
+     *     name = "_demo_hello"
+     * )
      * @Template()
      */
     public function helloAction($name)
     {
         return array('name' => $name);
     }
 
-The controller will now be called for URLs like ``/demo/hello/Fabien.xml`` or
+The controller will now match URLs like ``/demo/hello/Fabien.xml`` or
 ``/demo/hello/Fabien.json``.
 
-The ``requirements`` entry defines regular expressions that placeholders must
+The ``requirements`` entry defines regular expressions that variables must
 match. In this example, if you try to request the ``/demo/hello/Fabien.js``
 resource, you will get a 404 HTTP error, as it does not match the ``_format``
 requirement.
@@ -78,21 +83,33 @@ The ``generateUrl()`` is the same method as the ``path()`` function used in the
 templates. It takes the route name and an array of parameters as arguments and
 returns the associated friendly URL.
 
-You can also easily forward the action to another one with the ``forward()``
-method. Internally, Symfony makes a "sub-request", and returns the ``Response``
-object from that sub-request::
+You can also internally forward the action to another using the ``forward()``
+method::
+
+    return $this->forward('AcmeDemoBundle:Hello:fancy', array(
+        'name'  => $name,
+        'color' => 'green'
+    ));
+
+Displaying Error Pages
+----------------------
+
+Errors will inevitably happen during the execution of every web application.
+In the case of ``404`` errors, Symfony includes a handy shortcut that you can
+use in your controllers::
 
-    $response = $this->forward('AcmeDemoBundle:Hello:fancy', array('name' => $name, 'color' => 'green'));
+    throw $this->createNotFoundException();
 
-    // ... do something with the response or return it directly
+For ``500`` errors, just throw a regular PHP exception inside the controller and
+Symfony will transform it into a proper ``500`` error page::
+
+    throw new \Exception('Something went wrong!');
 
 Getting information from the Request
 ------------------------------------
 
-Besides the values of the routing placeholders, the controller also has access
-to the ``Request`` object. The framework injects the ``Request`` object in the
-controller if a variable is type hinted with
-`Symfony\Component\HttpFoundation\Request`::
+Symfony automatically injects the ``Request`` object when the controller has an
+argument that's type hinted with ``Symfony\Component\HttpFoundation\Request`::
 
     use Symfony\Component\HttpFoundation\Request;
 
@@ -102,7 +119,7 @@ controller if a variable is type hinted with
 
         $request->getPreferredLanguage(array('en', 'fr'));
 
-        $request->query->get('page'); // get a $_GET parameter
+        $request->query->get('page');   // get a $_GET parameter
 
         $request->request->get('page'); // get a $_POST parameter
     }
@@ -136,94 +153,24 @@ from any controller::
         // store an attribute for reuse during a later user request
         $session->set('foo', 'bar');
 
-        // in another controller for another request
+        // get the value of a session attribute
         $foo = $session->get('foo');
 
-        // use a default value if the key doesn't exist
-        $filters = $session->get('filters', array());
+        // use a default value if the attribute doesn't exist
+        $foo = $session->get('foo', 'default_value');
     }
 
-You can also store small messages that will only be available for the very
-next request::
+You can also store "flash messages" that will auto-delete after the next request.
+They are useful when you need to set a success message before redirecting the
+user to another page (which will then show the message)::
 
     // store a message for the very next request (in a controller)
     $session->getFlashBag()->add('notice', 'Congratulations, your action succeeded!');
 
-    // display any messages back in the next request (in a template)
-
-    {% for flashMessage in app.session.flashbag.get('notice') %}
-        <div>{{ flashMessage }}</div>
-    {% endfor %}
-
-This is useful when you need to set a success message before redirecting
-the user to another page (which will then show the message). Please note that
-when you use has() instead of get(), the flash message will not be cleared and
-thus remains available during the following requests.
-
-Securing Resources
-------------------
-
-The Symfony Standard Edition comes with a simple security configuration that
-fits most common needs:
-
-.. code-block:: yaml
-
-    # app/config/security.yml
-    security:
-        encoders:
-            Symfony\Component\Security\Core\User\User: plaintext
-
-        role_hierarchy:
-            ROLE_ADMIN:       ROLE_USER
-            ROLE_SUPER_ADMIN: [ROLE_USER, ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH]
-
-        providers:
-            in_memory:
-                memory:
-                    users:
-                        user:  { password: userpass, roles: [ 'ROLE_USER' ] }
-                        admin: { password: adminpass, roles: [ 'ROLE_ADMIN' ] }
-
-        firewalls:
-            dev:
-                pattern:  ^/(_(profiler|wdt)|css|images|js)/
-                security: false
-
-            login:
-                pattern:  ^/demo/secured/login$
-                security: false
-
-            secured_area:
-                pattern:    ^/demo/secured/
-                form_login:
-                    check_path: /demo/secured/login_check
-                    login_path: /demo/secured/login
-                logout:
-                    path:   /demo/secured/logout
-                    target: /demo/
-
-This configuration requires users to log in for any URL starting with
-``/demo/secured/`` and defines two valid users: ``user`` and ``admin``.
-Moreover, the ``admin`` user has a ``ROLE_ADMIN`` role, which includes the
-``ROLE_USER`` role as well (see the ``role_hierarchy`` setting).
-
-.. tip::
-
-    For readability, passwords are stored in clear text in this simple
-    configuration, but you can use any hashing algorithm by tweaking the
-    ``encoders`` section.
-
-Going to the ``http://localhost/app_dev.php/demo/secured/hello``
-URL will automatically redirect you to the login form because this resource is
-protected by a ``firewall``.
-
-.. note::
+.. code-block:: html+jinja
 
-    The Symfony2 security layer is very flexible and comes with many different
-    user providers (like one for the Doctrine ORM) and authentication providers
-    (like HTTP basic, HTTP digest, or X509 certificates). Read the
-    ":doc:`/book/security`" chapter of the book for more information
-    on how to use and configure them.
+    {# display the flash message in the template #}
+    <div>{{ app.session.flashbag.get('notice') }}</div>
 
 Caching Resources
 -----------------
@@ -247,19 +194,10 @@ convenient ``@Cache()`` annotation::
         return array('name' => $name);
     }
 
-In this example, the resource will be cached for a day. But you can also use
-validation instead of expiration or a combination of both if that fits your
-needs better.
-
-Resource caching is managed by the Symfony2 built-in reverse proxy. But because
-caching is managed using regular HTTP cache headers, you can replace the
-built-in reverse proxy with Varnish or Squid and easily scale your application.
-
-.. note::
-
-    But what if you cannot cache whole pages? Symfony2 still has the solution
-    via Edge Side Includes (ESI), which are supported natively. Learn more by
-    reading the ":doc:`/book/http_cache`" chapter of the book.
+In this example, the resource will be cached for a day (``86400`` seconds).
+Resource caching is managed by Symfony2 itself. But because caching is managed
+using standard HTTP cache headers, you can use Varnish or Squid without having
+to modify a single line of code in your application.
 
 Final Thoughts
 --------------

images/quick_tour/profiler.png

@@ -2,32 +2,28 @@ The View
 ========
 
 After reading the first part of this tutorial, you have decided that Symfony2
-was worth another 10 minutes. Great choice! In this second part, you will
-learn more about the Symfony2 template engine, `Twig`_. Twig is a flexible,
-fast, and secure template engine for PHP. It makes your templates more
-readable and concise; it also makes them more friendly for web designers.
-
-.. note::
-
-    Instead of Twig, you can also use :doc:`PHP </cookbook/templating/PHP>`
-    for your templates. Both template engines are supported by Symfony2.
+was worth another 10 minutes. In this second part, you will learn more about
+`Twig`_, the fast, flexible, and secure template engine for PHP. Twig makes your
+templates more readable and concise; it also makes them more friendly for web
+designers.
 
 Getting familiar with Twig
 --------------------------
 
-.. tip::
+The official `Twig documentation`_ is the best resource to learn everything
+about this new template engine. This section just gives you a quick overview of
+its main concepts.
 
-    If you want to learn Twig, it's highly recommended you read its official
-    `documentation`_. This section is just a quick overview of the main
-    concepts.
+A Twig template is a text file that can generate any type of content (HTML, CSS,
+JavaScript, XML, CSV, LaTeX, ...). Twig elements are separated from the rest of
+the template contents using any of these delimiters:
 
-A Twig template is a text file that can generate any type of content (HTML,
-XML, CSV, LaTeX, ...). Twig defines two kinds of delimiters:
+* ``{{ ... }}``: prints the content of a variable or the result of an expression;
 
-* ``{{ ... }}``: Prints a variable or the result of an expression;
+* ``{% ... %}``: controls the logic of the template; it is used for example to
+  execute ``for`` loops and ``if`` statements;
 
-* ``{% ... %}``: Controls the logic of the template; it is used to execute
-  ``for`` loops and ``if`` statements, for example.
+* ``{# ... #}``: allows including comments inside templates.
 
 Below is a minimal template that illustrates a few basics, using two variables
 ``page_title`` and ``navigation``, which would be passed into the template:
@@ -37,74 +33,65 @@ Below is a minimal template that illustrates a few basics, using two variables
     <!DOCTYPE html>
     <html>
         <head>
-            <title>My Webpage</title>
+            <title>{{ page_title }}</title>
         </head>
         <body>
             <h1>{{ page_title }}</h1>
 
             <ul id="navigation">
                 {% for item in navigation %}
-                    <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
+                    <li><a href="{{ item.url }}">{{ item.label }}</a></li>
                 {% endfor %}
             </ul>
         </body>
     </html>
 
-.. tip::
-
-   Comments can be included inside templates using the ``{# ... #}`` delimiter.
-
 To render a template in Symfony, use the ``render`` method from within a controller
-and pass it any variables needed in the template::
+and pass the variables needed as an array using the optional second argument::
 
     $this->render('AcmeDemoBundle:Demo:hello.html.twig', array(
         'name' => $name,
     ));
 
 Variables passed to a template can be strings, arrays, or even objects. Twig
 abstracts the difference between them and lets you access "attributes" of a
-variable with the dot (``.``) notation:
+variable with the dot (``.``) notation. The following code listing shows how to
+display the content of a variable depending on the type of the variable passed
+by the controller:
 
 .. code-block:: jinja
 
+    {# 1. Simple variables #}
     {# array('name' => 'Fabien') #}
     {{ name }}
 
+    {# 2. Arrays #}
     {# array('user' => array('name' => 'Fabien')) #}
     {{ user.name }}
 
-    {# force array lookup #}
+    {# alternative syntax for arrays #}
     {{ user['name'] }}
 
+    {# 3. Objects #}
     {# array('user' => new User('Fabien')) #}
     {{ user.name }}
     {{ user.getName }}
 
-    {# force method name lookup #}
+    {# alternative syntax for objects #}
     {{ user.name() }}
     {{ user.getName() }}
 
-    {# pass arguments to a method #}
-    {{ user.date('Y-m-d') }}
-
-.. note::
-
-    It's important to know that the curly braces are not part of the variable
-    but the print statement. If you access variables inside tags don't put the
-    braces around.
-
 Decorating Templates
 --------------------
 
 More often than not, templates in a project share common elements, like the
-well-known header and footer. In Symfony2, you think about this problem
-differently: a template can be decorated by another one. This works exactly
-the same as PHP classes: template inheritance allows you to build a base
-"layout" template that contains all the common elements of your site and
-defines "blocks" that child templates can override.
+well-known header and footer. Twig solves this problem elegantly with a concept
+called "template inheritance". This feature allows you to build a base "layout"
+template that contains all the common elements of your site and defines "blocks"
+that child templates can override.
 
-The ``hello.html.twig`` template inherits from ``layout.html.twig``, thanks to
-the ``extends`` tag:
+The ``hello.html.twig`` template uses the ``extends`` tag to indicate that it
+inherits from the common ``layout.html.twig`` template:
 
 .. code-block:: html+jinja
 
@@ -120,40 +107,50 @@ the ``extends`` tag:
 The ``AcmeDemoBundle::layout.html.twig`` notation sounds familiar, doesn't it?
 It is the same notation used to reference a regular template. The ``::`` part
 simply means that the controller element is empty, so the corresponding file
-is directly stored under the ``Resources/views/`` directory.
+is directly stored under the ``Resources/views/`` directory of the bundle.
 
 Now, simplify the ``layout.html.twig`` template:
 
 .. code-block:: jinja
 
     {# src/Acme/DemoBundle/Resources/views/layout.html.twig #}
-    <div class="symfony-content">
+    <div>
         {% block content %}
         {% endblock %}
     </div>
 
-The ``{% block %}`` tags define blocks that child templates can fill in. All
-the block tag does is to tell the template engine that a child template may
-override those portions of the template.
-
-In this example, the ``hello.html.twig`` template overrides the ``content``
-block, meaning that the "Hello Fabien" text is rendered inside the ``div.symfony-content``
-element.
+The ``{% block %}`` tags tell the template engine that a child template may
+override those portions of the template. In this example, the ``hello.html.twig``
+template overrides the ``content`` block, meaning that the "Hello Fabien" text
+is rendered inside the ``<div>`` element.
 
 Using Tags, Filters, and Functions
 ----------------------------------
 
 One of the best feature of Twig is its extensibility via tags, filters, and
-functions. Symfony2 comes bundled with many of these built-in to ease the
-work of the template designer.
+functions. Take a look at the following sample template that uses filters
+extensively to modify the information before displaying it to the user:
+
+.. code-block:: jinja
+
+    <h1>{{ article.title|trim|capitalize }}</h1>
+
+    <p>{{ article.content|striptags|slice(0, 1024) }}</p>
+
+    <p>Tags: {{ article.tags|sort|join(", ") }}</p>
+
+    <p>Next article will be published on {{ 'next Monday'|date('M j, Y')}}</p>
+
+Don't forget to check out the official `Twig documentation`_ to learn everything
+about filters, functions and tags.
 
 Including other Templates
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The best way to share a snippet of code between several distinct templates is
-to create a new template that can then be included from other templates.
+The best way to share a snippet of code between several templates is to create a
+new template fragment that can then be included from other templates.
 
-Create an ``embedded.html.twig`` template:
+First, create an ``embedded.html.twig`` template:
 
 .. code-block:: jinja
 
@@ -179,32 +176,31 @@ 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.
 
-Suppose you've created a ``fancyAction`` controller method, and you want to
-"render" it inside the ``index`` template, which means including the result
-(e.g. ``HTML``) of the controller. To do this, use the ``render`` function:
+Suppose you've created a ``topArticlesAction`` controller method to display the
+most popular articles of your website. If you want to "render" the result of
+that method (e.g. ``HTML``) inside the ``index`` template, use the ``render``
+function:
 
 .. code-block:: jinja
 
     {# src/Acme/DemoBundle/Resources/views/Demo/index.html.twig #}
-    {{ render(controller("AcmeDemoBundle:Demo:fancy", {'name': name, 'color': 'green'})) }}
+    {{ render(controller("AcmeDemoBundle:Demo:topArticles", {'num': 10})) }}
 
-Here, the ``AcmeDemoBundle:Demo:fancy`` string refers to the ``fancy`` action
-of the ``Demo`` controller. The arguments (``name`` and ``color``) act like
-simulated request variables (as if the ``fancyAction`` were handling a whole
-new request) and are made available to the controller::
+Here, the ``AcmeDemoBundle:Demo:topArticles`` string refers to the
+``topArticlesAction`` action of the ``Demo`` controller, and the ``num``
+argument is made available to the controller::
 
     // src/Acme/DemoBundle/Controller/DemoController.php
 
     class DemoController extends Controller
     {
-        public function fancyAction($name, $color)
+        public function topArticlesAction($num)
         {
-            // create some object, based on the $color variable
-            $object = ...;
+            // look for the $num most popular articles in the database
+            $articles = ...;
 
-            return $this->render('AcmeDemoBundle:Demo:fancy.html.twig', array(
-                'name' => $name,
-                'object' => $object,
+            return $this->render('AcmeDemoBundle:Demo:topArticles.html.twig', array(
+                'articles' => $articles,
             ));
         }
 
@@ -214,8 +210,8 @@ new request) and are made available to the controller::
 Creating Links between Pages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Speaking of web applications, creating links between pages is a must. Instead
-of hardcoding URLs in templates, the ``path`` function knows how to generate
+Creating links between pages is a must for web applications. Instead of
+hardcoding URLs in templates, the ``path`` function knows how to generate
 URLs based on the routing configuration. That way, all your URLs can be easily
 updated by just changing the configuration:
 
@@ -224,9 +220,8 @@ updated by just changing the configuration:
     <a href="{{ path('_demo_hello', { 'name': 'Thomas' }) }}">Greet Thomas!</a>
 
 The ``path`` function 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::
+arguments. The route name is the key under which routes are defined and the
+parameters are the values of the variables defined in the route pattern::
 
     // src/Acme/DemoBundle/Controller/DemoController.php
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
@@ -245,8 +240,9 @@ pattern::
 
 .. tip::
 
-    The ``url`` function generates *absolute* URLs: ``{{ url('_demo_hello', {
-    'name': 'Thomas'}) }}``.
+    The ``url`` function is very similar to the ``path`` function, but generates
+    *absolute* URLs, which is very handy when rendering emails and RSS files:
+    ``{{ url('_demo_hello', {'name': 'Thomas'}) }}``.
 
 Including Assets: images, JavaScripts, and stylesheets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -265,13 +261,6 @@ Thanks to this function, you can move the application root directory anywhere
 under your web root directory without changing anything in your template's
 code.
 
-Escaping Variables
-------------------
-
-Twig is configured to automatically escape all output by default. Read Twig
-`documentation`_ to learn more about output escaping and the Escaper
-extension.
-
 Final Thoughts
 --------------
 
@@ -289,5 +278,5 @@ But I'm getting ahead of myself. First, you need to learn more about the control
 and that's exactly the topic of the :doc:`next part of this tutorial <the_controller>`.
 Ready for another 10 minutes with Symfony2?
 
-.. _Twig:          http://twig.sensiolabs.org/
-.. _documentation: http://twig.sensiolabs.org/documentation
+.. _Twig:               http://twig.sensiolabs.org/
+.. _Twig documentation: http://twig.sensiolabs.org/documentation

images/quick_tour/web_debug_toolbar.png

@@ -160,7 +160,7 @@ your validation function is ``Vendor\Package\Validator::validate()``::
 
     class Validator
     {
-        public function validate($object, ExecutionContextInterface $context)
+        public static function validate($object, ExecutionContextInterface $context)
         {
             // ...
         }

images/quick_tour/welcome.png

@@ -62,3 +62,7 @@ on all fields.
 .. include:: /reference/forms/types/options/post_max_size_message.rst.inc
 
 .. include:: /reference/forms/types/options/pattern.rst.inc
+
+.. include:: /reference/forms/types/options/action.rst.inc
+
+.. include:: /reference/forms/types/options/method.rst.inc

quick_tour/the_architecture.rst

@@ -0,0 +1,12 @@
+.. versionadded:: 2.3
+    The ``action`` option was introduced in Symfony 2.3.
+
+action
+~~~~~~
+
+**type**: ``string`` **default**: empty string
+
+This option specifies where to send the form's data on submission (usually an
+URI). Its value is rendered as the ``action`` attribute of the ``form``
+element. An empty value is considered a same-document reference, i.e. the form
+will be submitted to the same URI that rendered the form.

quick_tour/the_big_picture.rst

@@ -4,5 +4,5 @@ compound
 **type**: ``boolean`` **default**: ``false``
 
 This option specifies if a form is compound. As it's not the
-case for checkbox, by fefault the value is overriden with
+case for checkbox, by default the value is overridden with
 ``false`` value.

quick_tour/the_controller.rst

@@ -0,0 +1,31 @@
+.. versionadded:: 2.3
+    The ``method`` option was introduced in Symfony 2.3.
+
+method
+~~~~~~
+
+**type**: ``string`` **default**: ``POST``
+
+This option specifies the HTTP method used to submit the form's data. Its
+value is rendered as the ``method`` attribute of the ``form`` element and is
+used to decide whether to process the form submission in the
+``handleRequest()`` method after submission. Possible values are:
+
+* POST
+* GET
+* PUT
+* DELETE
+* PATCH
+
+.. note:
+
+    When the method is PUT, PATCH, or DELETE, Symfony will automatically
+    render a ``_method`` hidden field in your form. This is used to "fake"
+    these HTTP methods, as they're not supported on standard browsers. For
+    more information, see :doc:`/cookbook/routing/method_parameters`.
+
+.. note:
+
+    Only the PATCH method allows submitting partial data without that missing
+    fields are set to ``null`` in the underlying data (preserving default
+    values, if any).