Merge remote-tracking branch 'upstream/2.6'

Author: javiereguiluz

.travis.yml

@@ -3,6 +3,8 @@ language: python
 python:
     - "2.7"
 
+sudo: false
+
 install: 
     - "pip install -q -r requirements.txt --use-mirrors"
 

best_practices/business-logic.rst

@@ -15,7 +15,7 @@ Inside here, you can create whatever directories you want to organize things:
 
 .. code-block:: text
 
-    symfoy2-project/
+    symfony2-project/
     ├─ app/
     ├─ src/
     │  └─ AppBundle/
@@ -33,7 +33,7 @@ and put things there:
 
 .. code-block:: text
 
-    symfoy2-project/
+    symfony2-project/
     ├─ app/
     ├─ src/
     │  ├─ Acme/
@@ -81,7 +81,7 @@ Next, define a new service for that class.
     # app/config/services.yml
     services:
         # keep your service names short
-        slugger:
+        app.slugger:
             class: AppBundle\Utils\Slugger
 
 Traditionally, the naming convention for a service involved following the
@@ -92,7 +92,8 @@ your code will be easier to read and use.
 .. best-practice::
 
     The name of your application's services should be as short as possible,
-    ideally just one simple word.
+    but unique enough that you can search your project for the service if
+    you ever need to.
 
 Now you can use the custom slugger in any controller class, such as the
 ``AdminController``:
@@ -104,7 +105,7 @@ Now you can use the custom slugger in any controller class, such as the
         // ...
 
         if ($form->isSubmitted() && $form->isValid()) {
-            $slug = $this->get('slugger')->slugify($post->getTitle());
+            $slug = $this->get('app.slugger')->slugify($post->getTitle());
             $post->setSlug($slug);
 
             // ...
@@ -139,12 +140,9 @@ the class namespace as a parameter:
     # app/config/services.yml
 
     # service definition with class namespace as parameter
-    parameters:
-        slugger.class: AppBundle\Utils\Slugger
-
     services:
-        slugger:
-            class: "%slugger.class%"
+        app.slugger:
+            class: AppBundle\Utils\Slugger
 
 This practice is cumbersome and completely unnecessary for your own services:
 
@@ -299,7 +297,7 @@ Then, enable the bundle in ``AppKernel.php``, but only for the ``dev`` and
 
             if (in_array($this->getEnvironment(), array('dev', 'test'))) {
                 // ...
-                $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle(),
+                $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle();
             }
 
             return $bundles;
@@ -334,8 +332,8 @@ in a matter of seconds.
 
 .. _`full definition`: http://en.wikipedia.org/wiki/Business_logic
 .. _`Doctrine project`: http://www.doctrine-project.org/
-.. _`fixture class`: http://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures
+.. _`fixture class`: http://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures
 .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/
 .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/
 .. _`the Symfony Code Standards`: http://symfony.com/doc/current/contributing/code/standards.html
-.. _`PHP-CS-Fixer`: https://github.com/fabpot/PHP-CS-Fixer
+.. _`PHP-CS-Fixer`: https://github.com/FriendsOfPHP/PHP-CS-Fixer

best_practices/configuration.rst

@@ -74,9 +74,9 @@ add an extra layer of configuration that's not needed because you don't need
 or want these configuration values to change on each server.
 
 The configuration options defined in the ``config.yml`` file usually vary from
-one `execution environment`_ to another. That's why Symfony already includes
-``app/config/config_dev.yml`` and ``app/config/config_prod.yml`` files so
-that you can override specific values for each environment.
+one :doc:`/cookbook/configuration/environments` to another. That's why Symfony
+already includes ``app/config/config_dev.yml`` and ``app/config/config_prod.yml``
+files so that you can override specific values for each environment.
 
 Constants vs Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -158,10 +158,10 @@ Semantic Configuration: Don't Do It
 
     Don't define a semantic dependency injection configuration for your bundles.
 
-As explained in `How to Expose a semantic Configuration for a Bundle`_ article,
-Symfony bundles have two choices on how to handle configuration: normal service
-configuration through the ``services.yml`` file and semantic configuration
-through a special ``*Extension`` class.
+As explained in :doc:`/cookbook/bundles/extension` article, Symfony bundles
+have two choices on how to handle configuration: normal service configuration
+through the ``services.yml`` file and semantic configuration through a special
+``*Extension`` class.
 
 Although semantic configuration is much more powerful and provides nice features
 such as configuration validation, the amount of work needed to define that
@@ -174,10 +174,7 @@ Moving Sensitive Options Outside of Symfony Entirely
 When dealing with sensitive options, like database credentials, we also recommend
 that you store them outside the Symfony project and make them available
 through environment variables. Learn how to do it in the following article:
-`How to Set external Parameters in the Service Container`_
+:doc:`/cookbook/configuration/external_parameters`
 
 .. _`feature toggles`: http://en.wikipedia.org/wiki/Feature_toggle
-.. _`execution environment`: http://symfony.com/doc/current/cookbook/configuration/environments.html
 .. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html
-.. _`How to Expose a semantic Configuration for a Bundle`: http://symfony.com/doc/current/cookbook/bundles/extension.html
-.. _`How to Set external Parameters in the Service Container`: http://symfony.com/doc/current/cookbook/configuration/external_parameters.html

best_practices/controllers.rst

@@ -206,7 +206,6 @@ Pre and Post Hooks
 ------------------
 
 If you need to execute some code before or after the execution of your controllers,
-you can use the EventDispatcher component to `set up before/after filters`_.
+you can use the EventDispatcher component to :doc:`/cookbook/event_dispatcher/before_after_filters`.
 
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`set up before/after filters`: http://symfony.com/doc/current/cookbook/event_dispatcher/before_after_filters.html

best_practices/creating-the-project.rst

@@ -220,7 +220,8 @@ Extending the Directory Structure
 ---------------------------------
 
 If your project or infrastructure requires some changes to the default directory
-structure of Symfony, you can `override the location of the main directories`_:
+structure of Symfony, you can
+:doc:`override the location of the main directories </cookbook/configuration/override_dir_structure>`:
 ``cache/``, ``logs/`` and ``web/``.
 
 In addition, Symfony3 will use a slightly different directory structure when
@@ -247,6 +248,5 @@ the Symfony2 directory structure.
 .. _`Composer`: https://getcomposer.org/
 .. _`Get Started`: https://getcomposer.org/doc/00-intro.md
 .. _`Composer download page`: https://getcomposer.org/download/
-.. _`override the location of the main directories`: http://symfony.com/doc/current/cookbook/configuration/override_dir_structure.html
 .. _`public checksums repository`: https://github.com/sensiolabs/checksums
 .. _`these steps`: http://fabien.potencier.org/article/73/signing-project-releases

best_practices/forms.rst

@@ -15,9 +15,7 @@ Building Forms
 The Form component allows you to build forms right inside your controller
 code. Honestly, unless you need to reuse the form somewhere else, that's
 totally fine. But for organize and reuse, we recommend that you define each
-form in its own PHP class:
-
-.. code-block:: php
+form in its own PHP class::
 
     namespace AppBundle\Form;
 
@@ -51,9 +49,7 @@ form in its own PHP class:
         }
     }
 
-To use the class, use ``createForm`` and instantiate the new class:
-
-.. code-block:: php
+To use the class, use ``createForm`` and instantiate the new class::
 
     use AppBundle\Form\PostType;
     // ...
@@ -69,9 +65,11 @@ To use the class, use ``createForm`` and instantiate the new class:
 Registering Forms as Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can also `register your form type as a service`_. But this is *not* recommended
-unless you plan to reuse the new form type in many places or embed it in
-other forms directly or via the `collection type`_.
+You can also
+:ref:`register your form type as a service <form-cookbook-form-field-service>`.
+But this is *not* recommended unless you plan to reuse the new form type in many
+places or embed it in other forms directly or via the
+:doc:`collection type </reference/forms/types/collection>`.
 
 For most forms that are used only to edit or create something, registering
 the form as a service is over-kill, and makes it more difficult to figure
@@ -108,9 +106,7 @@ directly in your form class, this would effectively limit the scope of that form
 
 This form *may* have been designed for creating posts, but if you wanted
 to reuse it for editing posts, the button label would be wrong. Instead,
-some developers configure form buttons in the controller:
-
-.. code-block:: php
+some developers configure form buttons in the controller::
 
     namespace AppBundle\Controller\Admin;
 
@@ -143,12 +139,12 @@ view layer:
 
 .. code-block:: html+jinja
 
-    <form method="POST" {{ form_enctype(form) }}>
+    {{ form_start(form) }}
         {{ form_widget(form) }}
 
         <input type="submit" value="Create"
                class="btn btn-default pull-right" />
-    </form>
+    {{ form_end(form) }}
 
 Rendering the Form
 ------------------
@@ -157,33 +153,19 @@ There are a lot of ways to render your form, ranging from rendering the entire
 thing in one line to rendering each part of each field independently. The
 best way depends on how much customization you need.
 
-The simplest way - which is especially useful during development - is to render
-the form tags manually and then use ``form_widget()`` to render all of the fields:
+One of the simplest ways - which is especially useful during development -
+is to render the form tags and use ``form_widget()`` to render all of the
+fields:
 
 .. code-block:: html+jinja
 
-    <form method="POST" {{ form_enctype(form) }}>
+    {{ form_start(form, {'attr': {'class': 'my-form-class'} }) }}
         {{ form_widget(form) }}
-    </form>
-
-.. best-practice::
-
-    Don't use the ``form()`` or ``form_start()`` functions to render the
-    starting and ending form tags.
-
-Experienced Symfony developers will recognize that we're rendering the ``<form>``
-tags manually instead of using the ``form_start()`` or ``form()`` functions.
-While those are convenient, they take away from some clarity with little
-benefit.
-
-.. tip::
-
-    The exception is a delete form because it's really just one button and
-    so benefits from some of these extra shortcuts.
+    {{ form_end(form) }}
 
 If you need more control over how your fields are rendered, then you should
 remove the ``form_widget(form)`` function and render your fields individually.
-See `How to Customize Form Rendering`_ for more information on this and how
+See :doc:`/cookbook/form/form_customization` for more information on this and how
 you can control *how* the form renders at a global level using form theming.
 
 Handling Form Submits
@@ -224,8 +206,3 @@ Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement
 for clarity. This isn't technically needed, since ``isValid()`` first calls
 ``isSubmitted()``. But without this, the flow doesn't read well as it *looks*
 like the form is *always* processed (even on the GET request).
-
-.. _`register your form type as a service`: http://symfony.com/doc/current/cookbook/form/create_custom_field_type.html#creating-your-field-type-as-a-service
-.. _`collection type`: http://symfony.com/doc/current/reference/forms/types/collection.html
-.. _`How to Customize Form Rendering`: http://symfony.com/doc/current/cookbook/form/form_customization.html
-.. _`form event system`: http://symfony.com/doc/current/cookbook/form/dynamic_form_modification.html

best_practices/i18n.rst

@@ -83,7 +83,7 @@ English in the application would be:
     <!-- app/Resources/translations/messages.en.xliff -->
     <?xml version="1.0"?>
     <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
-        <file source-language="en" target-language="en" datatype="plaintext">
+        <file source-language="en" target-language="en" datatype="plaintext" original="file.ext">
             <body>
                 <trans-unit id="1">
                     <source>title.post_list</source>

best_practices/introduction.rst

@@ -59,7 +59,7 @@ Who this Book Is for (Hint: It's not a Tutorial)
 Any Symfony developer, whether you are an expert or a newcomer, can read this
 guide. But since this isn't a tutorial, you'll need some basic knowledge of
 Symfony to follow everything. If you are totally new to Symfony, welcome!
-Start with `The Quick Tour`_ tutorial first.
+Start with :doc:`The Quick Tour </quick_tour/the_big_picture>` tutorial first.
 
 We've deliberately kept this guide short. We won't repeat explanations that
 you can find in the vast Symfony documentation, like discussions about dependency
@@ -95,7 +95,3 @@ practices**. The reasons for not doing it are various:
   your tests or adding features that provide real value to the end users.
 
 .. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
-.. _`The Quick Tour`: http://symfony.com/doc/current/quick_tour/the_big_picture.html
-.. _`The Official Symfony Book`: http://symfony.com/doc/current/book/index.html
-.. _`The Symfony Cookbook`: http://symfony.com/doc/current/cookbook/index.html
-.. _`github.com/.../...`: http://github.com/.../...

best_practices/security.rst

@@ -6,7 +6,8 @@ Authentication and Firewalls (i.e. Getting the User's Credentials)
 
 You can configure Symfony to authenticate your users using any method you
 want and to load user information from any source. This is a complex topic,
-but the `Security Cookbook Section`_ has a lot of information about this.
+but the :doc:`Security Cookbook Section </cookbook/security/index>` has a
+lot of information about this.
 
 Regardless of your needs, authentication is configured in ``security.yml``,
 primarily under the ``firewalls`` key.
@@ -72,8 +73,9 @@ Authorization (i.e. Denying Access)
 -----------------------------------
 
 Symfony gives you several ways to enforce authorization, including the ``access_control``
-configuration in `security.yml`_, the :ref:`@Security annotation <best-practices-security-annotation>`
-and using :ref:`isGranted <best-practices-directy-isGranted>` on the ``security.context``
+configuration in :doc:`security.yml </reference/configuration/security>` the
+:ref:`@Security annotation <best-practices-security-annotation>` and using
+:ref:`isGranted <best-practices-directly-isGranted>` on the ``security.context``
 service directly.
 
 .. best-practice::
@@ -204,7 +206,7 @@ Now you can reuse this method both in the template and in the security expressio
         <a href=""> ... </a>
     {% endif %}
 
-.. _best-practices-directy-isGranted:
+.. _best-practices-directly-isGranted:
 
 Checking Permissions without @Security
 --------------------------------------
@@ -240,8 +242,8 @@ 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 `ACL's`_ and will give you the flexibility you need
-in almost all cases.
+of magnitude easier than :doc:`ACL's </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
 the same ``getAuthorEmail`` logic you used above:
@@ -337,27 +339,22 @@ The `FOSUserBundle`_, developed by the Symfony community, adds support for a
 database-backed user system in Symfony2. It also handles common tasks like
 user registration and forgotten password functionality.
 
-Enable the `Remember Me feature`_ to allow your users to stay logged in for
-a long period of time.
+Enable the :doc:`Remember Me feature </cookbook/security/remember_me>` to
+allow your users to stay logged in for a long period of time.
 
 When providing customer support, sometimes it's necessary to access the application
 as some *other* user so that you can reproduce the problem. Symfony provides
-the ability to `impersonate users`_.
+the ability to :doc:`impersonate users </cookbook/security/impersonating_user>`.
 
 If your company uses a user login method not supported by Symfony, you can
-develop `your own user provider`_ and `your own authentication provider`_.
+develop :doc:`your own user provider </cookbook/security/custom_provider>` and
+:doc:`your own authentication provider </cookbook/security/custom_authentication_provider>`.
 
 .. _`Security Cookbook Section`: http://symfony.com/doc/current/cookbook/security/index.html
 .. _`security.yml`: http://symfony.com/doc/current/reference/configuration/security.html
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Security annotation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
-.. _`security.yml`: http://symfony.com/doc/current/reference/configuration/security.html
 .. _`security voter`: http://symfony.com/doc/current/cookbook/security/voters_data_permission.html
-.. _`Acces Control List`: http://symfony.com/doc/current/cookbook/security/acl.html
 .. _`ACL's`: http://symfony.com/doc/current/cookbook/security/acl.html
 .. _`expression`: http://symfony.com/doc/current/components/expression_language/introduction.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
-.. _`Remember Me feature`: http://symfony.com/doc/current/cookbook/security/remember_me.html
-.. _`impersonate users`: http://symfony.com/doc/current/cookbook/security/impersonating_user.html
-.. _`your own user provider`: http://symfony.com/doc/current/cookbook/security/custom_provider.html
-.. _`your own authentication provider`: http://symfony.com/doc/current/cookbook/security/custom_authentication_provider.html

best_practices/templates.rst

@@ -156,9 +156,5 @@ name is irrelevant because you never use it in your own code):
             tags:
                 - { name: twig.extension }
 
-
 .. _`Twig`: http://twig.sensiolabs.org/
 .. _`Parsedown`: http://parsedown.org/
-.. _`Twig global variables`: http://symfony.com/doc/master/cookbook/templating/global_variables.html
-.. _`override error pages`: http://symfony.com/doc/current/cookbook/controller/error_pages.html
-.. _`render a template without using a controller`: http://symfony.com/doc/current/cookbook/templating/render_without_controller.html