Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

best_practices/business-logic.rst

@@ -10,7 +10,7 @@ your app that's not specific to the framework (e.g. routing and controllers).
 Domain classes, Doctrine entities and regular PHP classes that are used as
 services are good examples of business logic.
 
-For most projects, you should store everything inside the ``AppBundle``.
+For most projects, you should store everything inside the AppBundle.
 Inside here, you can create whatever directories you want to organize things:
 
 .. code-block:: text
@@ -45,7 +45,7 @@ and put things there:
 
 .. tip::
 
-    The recommended approach of using the ``AppBundle`` directory is for
+    The recommended approach of using the ``AppBundle/`` directory is for
     simplicity. If you're advanced enough to know what needs to live in
     a bundle and what can live outside of one, then feel free to do that.
 
@@ -140,9 +140,12 @@ the class namespace as a parameter:
     # app/config/services.yml
 
     # service definition with class namespace as parameter
+    parameters:
+        slugger.class: AppBundle\Utils\Slugger
+
     services:
         app.slugger:
-            class: AppBundle\Utils\Slugger
+            class: "%slugger.class%"
 
 This practice is cumbersome and completely unnecessary for your own services:
 
@@ -166,8 +169,8 @@ library or strategy you want for this.
 
 In practice, many Symfony applications rely on the independent
 `Doctrine project`_ to define their model using entities and repositories.
-Just like with business logic, we recommend storing Doctrine entities in
-the ``AppBundle``
+Just like with business logic, we recommend storing Doctrine entities in the
+AppBundle.
 
 The three entities defined by our sample blog application are a good example:
 

best_practices/configuration.rst

@@ -6,6 +6,8 @@ and security credentials) and different environments (development, production).
 That's why Symfony recommends that you split the application configuration into
 three parts.
 
+.. _config-parameters.yml:
+
 Infrastructure-Related Configuration
 ------------------------------------
 

best_practices/controllers.rst

@@ -13,8 +13,8 @@ into a service.
 
 .. best-practice::
 
-    Make your controller extend the ``FrameworkBundle`` base Controller and
-    use annotations to configure routing, caching and security whenever possible.
+    Make your controller extend the FrameworkBundle base controller and use
+    annotations to configure routing, caching and security whenever possible.
 
 Coupling the controllers to the underlying framework allows you to leverage
 all of its features and increases your productivity.

best_practices/creating-the-project.rst

@@ -109,26 +109,26 @@ Application Bundles
 
 When Symfony 2.0 was released, most developers naturally adopted the symfony
 1.x way of dividing applications into logical modules. That's why many Symfony
-apps use bundles to divide their code into logical features: ``UserBundle``,
-``ProductBundle``, ``InvoiceBundle``, etc.
+apps use bundles to divide their code into logical features: UserBundle,
+ProductBundle, InvoiceBundle, etc.
 
 But a bundle is *meant* to be something that can be reused as a stand-alone
-piece of software. If ``UserBundle`` cannot be used *"as is"* in other Symfony
-apps, then it shouldn't be its own bundle. Moreover ``InvoiceBundle`` depends
-on ``ProductBundle``, then there's no advantage to having two separate bundles.
+piece of software. If UserBundle cannot be used *"as is"* in other Symfony
+apps, then it shouldn't be its own bundle. Moreover InvoiceBundle depends on
+ProductBundle, then there's no advantage to having two separate bundles.
 
 .. best-practice::
 
-    Create only one bundle called ``AppBundle`` for your application logic
+    Create only one bundle called AppBundle for your application logic
 
-Implementing a single ``AppBundle`` bundle in your projects will make your code
+Implementing a single AppBundle bundle in your projects will make your code
 more concise and easier to understand. Starting in Symfony 2.6, the official
-Symfony documentation uses the ``AppBundle`` name.
+Symfony documentation uses the AppBundle name.
 
 .. note::
 
-    There is no need to prefix the ``AppBundle`` with your own vendor (e.g.
-    ``AcmeAppBundle``), because this application bundle is never going to be
+    There is no need to prefix the AppBundle with your own vendor (e.g.
+    AcmeAppBundle), because this application bundle is never going to be
     shared.
 
 All in all, this is the typical directory structure of a Symfony application
@@ -152,7 +152,7 @@ that follows these best practices:
 
 .. tip::
 
-    If your Symfony installation doesn't come with a pre-generated ``AppBundle``,
+    If your Symfony installation doesn't come with a pre-generated AppBundle,
     you can generate it by hand executing this command:
 
     .. code-block:: bash

best_practices/forms.rst

@@ -21,7 +21,7 @@ form in its own PHP class::
 
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class PostType extends AbstractType
     {
@@ -36,7 +36,7 @@ form in its own PHP class::
             ;
         }
 
-        public function setDefaultOptions(OptionsResolverInterface $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             $resolver->setDefaults(array(
                 'data_class' => 'AppBundle\Entity\Post'

best_practices/security.rst

@@ -245,7 +245,7 @@ Security Voters
 
 If your security logic is complex and can't be centralized into a method
 like ``isAuthor()``, you should leverage custom voters. These are an order
-of magnitude easier than :doc:`ACL's </cookbook/security/acl>` and will give
+of magnitude easier than :doc:`ACLs </cookbook/security/acl>` and will give
 you the flexibility you need in almost all cases.
 
 First, create a voter class. The following example shows a voter that implements

book/controller.rst

@@ -228,9 +228,9 @@ Simple, right?
 Route Parameters as Controller Arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You already know that the route points to the ``HelloController::indexAction()`` method
-that lives inside ``AppBundle``. What's more interesting is the argument
-that is passed to that method::
+You already know that the route points to the
+``HelloController::indexAction()`` method that lives inside AppBundle. What's
+more interesting is the argument that is passed to that method::
 
     // src/AppBundle/Controller/HelloController.php
     // ...
@@ -771,8 +771,8 @@ object that's returned from *that* controller::
 Notice that the ``forward()`` method uses a special string representation
 of the controller (see :ref:`controller-string-syntax`). In this case, the
 target controller function will be ``SomethingController::fancyAction()``
-inside the ``AppBundle``. The array passed to the method becomes the arguments
-on the resulting controller. This same idea is used when embedding controllers
+inside the AppBundle. The array passed to the method becomes the arguments on
+the resulting controller. This same idea is used when embedding controllers
 into templates (see :ref:`templating-embedding-controller`). The target
 controller method would look something like this::
 

book/doctrine.rst

@@ -77,8 +77,10 @@ information. By convention, this information is usually configured in an
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/doctrine
+                    http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
                 <doctrine:config>
                     <doctrine:dbal
@@ -165,8 +167,10 @@ for you:
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                    http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/doctrine
+                    http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
                 <doctrine:config>
                     <doctrine:dbal
@@ -193,7 +197,7 @@ Creating an Entity Class
 Suppose you're building an application where products need to be displayed.
 Without even thinking about Doctrine or databases, you already know that
 you need a ``Product`` object to represent those products. Create this class
-inside the ``Entity`` directory of your ``AppBundle``::
+inside the ``Entity`` directory of your AppBundle::
 
     // src/AppBundle/Entity/Product.php
     namespace AppBundle\Entity;
@@ -426,6 +430,7 @@ mapping information) of a bundle or an entire namespace:
 
     # generates all entities in the AppBundle
     $ php app/console doctrine:generate:entities AppBundle
+    
     # generates all entities of bundles in the Acme namespace
     $ php app/console doctrine:generate:entities Acme
 
@@ -864,7 +869,7 @@ You can use this new method just like the default finder methods of the reposito
 
     $em = $this->getDoctrine()->getManager();
     $products = $em->getRepository('AppBundle:Product')
-                ->findAllOrderedByName();
+        ->findAllOrderedByName();
 
 .. note::
 
@@ -884,7 +889,9 @@ you can let Doctrine create the class for you.
 
 .. code-block:: bash
 
-    $ php app/console doctrine:generate:entity --entity="AppBundle:Category" --fields="name:string(255)"
+    $ php app/console doctrine:generate:entity \
+        --entity="AppBundle:Category" \
+        --fields="name:string(255)"
 
 This task generates the ``Category`` entity for you, with an ``id`` field,
 a ``name`` field and the associated getter and setter functions.
@@ -929,7 +936,8 @@ To relate the ``Category`` and ``Product`` entities, start by creating a
                 products:
                     targetEntity: Product
                     mappedBy: category
-            # don't forget to init the collection in the __construct() method of the entity
+            # don't forget to init the collection in the __construct() method
+            # of the entity
 
     .. code-block:: xml
 
@@ -1038,7 +1046,7 @@ methods for you:
 
 .. code-block:: bash
 
-    $ php app/console doctrine:generate:entities Acme
+    $ php app/console doctrine:generate:entities AppBundle
 
 Ignore the Doctrine metadata for a moment. You now have two classes - ``Category``
 and ``Product`` with a natural one-to-many relationship. The ``Category``
@@ -1151,7 +1159,7 @@ the category (i.e. it's "lazily loaded").
 
 You can also query in the other direction::
 
-    public function showProductAction($id)
+    public function showProductsAction($id)
     {
         $category = $this->getDoctrine()
             ->getRepository('AppBundle:Category')
@@ -1372,7 +1380,7 @@ list of all available types and more information, see Doctrine's
 Summary
 -------
 
-With Doctrine, you can focus on your objects and how they're useful in your
+With Doctrine, you can focus on your objects and how they're used in your
 application and worry about database persistence second. This is because
 Doctrine allows you to use any PHP object to hold your data and relies on
 mapping metadata information to map an object's data to a particular database

book/forms.rst

@@ -175,7 +175,7 @@ That's it! Just three lines are needed to render the complete form:
     Renders all the fields, which includes the field element itself, a label
     and any validation error messages for the field.
 
-``form_end()``
+``form_end(form)``
     Renders the end tag of the form and any fields that have not
     yet been rendered, in case you rendered each field yourself. This is useful
     for rendering hidden fields and taking advantage of the automatic
@@ -470,13 +470,17 @@ you'll need to specify which validation group(s) your form should use::
         'validation_groups' => array('registration'),
     ))->add(...);
 
+.. versionadded:: 2.7
+    The ``configureOptions()`` method was introduced in Symfony 2.7. Previously,
+    the method was called ``setDefaultOptions()``.
+
 If you're creating :ref:`form classes <book-form-creating-form-classes>` (a
-good practice), then you'll need to add the following to the ``setDefaultOptions()``
+good practice), then you'll need to add the following to the ``configureOptions()``
 method::
 
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'validation_groups' => array('registration'),
@@ -498,9 +502,9 @@ Disabling Validation
 Sometimes it is useful to suppress the validation of a form altogether. For
 these cases you can set the ``validation_groups`` option to ``false``::
 
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'validation_groups' => false,
@@ -524,10 +528,10 @@ If you need some advanced logic to determine the validation groups (e.g.
 based on submitted data), you can set the ``validation_groups`` option
 to an array callback::
 
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     // ...
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'validation_groups' => array(
@@ -544,10 +548,10 @@ You can also define whole logic inline by using a ``Closure``::
 
     use Acme\AcmeBundle\Entity\Client;
     use Symfony\Component\Form\FormInterface;
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     // ...
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'validation_groups' => function(FormInterface $form) {
@@ -567,10 +571,10 @@ of the entity as well you have to adjust the option as follows::
 
     use Acme\AcmeBundle\Entity\Client;
     use Symfony\Component\Form\FormInterface;
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     // ...
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'validation_groups' => function(FormInterface $form) {
@@ -1090,9 +1094,9 @@ the choice is ultimately up to you.
     good idea to explicitly specify the ``data_class`` option by adding the
     following to your form type class::
 
-        use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+        use Symfony\Component\OptionsResolver\OptionsResolver;
 
-        public function setDefaultOptions(OptionsResolverInterface $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             $resolver->setDefaults(array(
                 'data_class' => 'AppBundle\Entity\Task',
@@ -1321,7 +1325,7 @@ create a form class so that a ``Category`` object can be modified by the user::
 
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class CategoryType extends AbstractType
     {
@@ -1330,7 +1334,7 @@ create a form class so that a ``Category`` object can be modified by the user::
             $builder->add('name');
         }
 
-        public function setDefaultOptions(OptionsResolverInterface $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             $resolver->setDefaults(array(
                 'data_class' => 'AppBundle\Entity\Category',
@@ -1756,13 +1760,13 @@ that all un-rendered fields are output.
 
 The CSRF token can be customized on a form-by-form basis. For example::
 
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class TaskType extends AbstractType
     {
         // ...
 
-        public function setDefaultOptions(OptionsResolverInterface $resolver)
+        public function configureOptions(OptionsResolver $resolver)
         {
             $resolver->setDefaults(array(
                 'data_class'      => 'AppBundle\Entity\Task',

book/from_flat_php_to_symfony2.rst

@@ -244,7 +244,7 @@ the layout:
 
     <?php include 'layout.php' ?>
 
-You now have a setup that will allow you to reuse the layout. 
+You now have a setup that will allow you to reuse the layout.
 Unfortunately, to accomplish this, you're forced to use a few ugly
 PHP functions (``ob_start()``, ``ob_get_clean()``) in the template. Symfony
 uses a Templating component that allows this to be accomplished cleanly