Merge branch '2.7' into 2.8

Author: wouterj

book/controller.rst

@@ -321,42 +321,42 @@ Keep the following guidelines in mind while you develop.
 
 #. **The order of the controller arguments does not matter**
 
-    Symfony matches the parameter **names** from the route to the variable
-    **names** of the controller. The arguments of the controller could be
-    totally reordered and still work perfectly::
+   Symfony matches the parameter **names** from the route to the variable
+   **names** of the controller. The arguments of the controller could be
+   totally reordered and still work perfectly::
 
-        public function indexAction($lastName, $firstName)
-        {
-            // ...
-        }
+       public function indexAction($lastName, $firstName)
+       {
+           // ...
+       }
 
 #. **Each required controller argument must match up with a routing parameter**
 
-    The following would throw a ``RuntimeException`` because there is no
-    ``foo`` parameter defined in the route::
+   The following would throw a ``RuntimeException`` because there is no
+   ``foo`` parameter defined in the route::
 
-        public function indexAction($firstName, $lastName, $foo)
-        {
-            // ...
-        }
+       public function indexAction($firstName, $lastName, $foo)
+       {
+           // ...
+       }
 
-    Making the argument optional, however, is perfectly ok. The following
-    example would not throw an exception::
+   Making the argument optional, however, is perfectly ok. The following
+   example would not throw an exception::
 
-        public function indexAction($firstName, $lastName, $foo = 'bar')
-        {
-            // ...
-        }
+       public function indexAction($firstName, $lastName, $foo = 'bar')
+       {
+           // ...
+       }
 
 #. **Not all routing parameters need to be arguments on your controller**
 
-    If, for example, the ``lastName`` weren't important for your controller,
-    you could omit it entirely::
+   If, for example, the ``lastName`` weren't important for your controller,
+   you could omit it entirely::
 
-        public function indexAction($firstName)
-        {
-            // ...
-        }
+       public function indexAction($firstName)
+       {
+           // ...
+       }
 
 .. tip::
 

book/installation.rst

@@ -230,10 +230,9 @@ If there are any issues, correct them now before moving on.
     its user to be the same as your CLI user (e.g. for Apache, update the ``User``
     and ``Group`` values).
 
-    **2. Using ACL on a system that supports chmod +a**
+    **2. Using ACL on a system that supports chmod +a (MacOS X)**
 
-    Many systems allow you to use the ``chmod +a`` command. Try this first,
-    and if you get an error - try the next method. This uses a command to
+    MacOS X allows you to use the ``chmod +a`` command. This uses a command to
     try to determine your web server user and set it as ``HTTPDUSER``:
 
     .. code-block:: bash
@@ -245,14 +244,12 @@ If there are any issues, correct them now before moving on.
         $ sudo chmod +a "$HTTPDUSER allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
         $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
 
+    **3. Using ACL on a system that supports setfacl (most Linux/BSD)**
 
-    **3. Using ACL on a system that does not support chmod +a**
-
-    Some systems don't support ``chmod +a``, but do support another utility
-    called ``setfacl``. You may need to `enable ACL support`_ on your partition
-    and install setfacl before using it (as is the case with Ubuntu). This
-    uses a command to try to determine your web server user and set it as
-    ``HTTPDUSER``:
+    Most Linux and BSD distributions don't support ``chmod +a``, but do support
+    another utility called ``setfacl``. You may need to `enable ACL support`_
+    on your partition and install setfacl before using it. This uses a command
+    to try to determine your web server user and set it as ``HTTPDUSER``:
 
     .. code-block:: bash
 
@@ -262,6 +259,11 @@ If there are any issues, correct them now before moving on.
 
     If this doesn't work, try adding ``-n`` option.
 
+    .. note::
+
+        setfacl isn't available on NFS mount points. However, setting cache
+        and logs over NFS is strongly not recommended for performance.
+
     **4. Without using ACL**
 
     If none of the previous methods work for you, change the umask so that the

book/routing.rst

@@ -805,6 +805,13 @@ Path     Parameters
 ``/es``  *won't match this route*
 =======  ========================
 
+.. tip::
+
+    The route requirements can also include container parameters, as explained
+    in :doc:`this article </cookbook/routing/service_container_parameters>`.
+    This comes in handy when the regular expression is very complex and used
+    repeatedly in your application.
+
 .. index::
    single: Routing; Method requirement
 

changelog.rst

@@ -13,6 +13,51 @@ documentation.
     Do you also want to participate in the Symfony Documentation? Take a look
     at the ":doc:`/contributing/documentation/overview`" article.
 
+April, 2016
+-----------
+
+New Documentation
+~~~~~~~~~~~~~~~~~
+
+* `#6470 <https://github.com/symfony/symfony-docs/pull/6470>`_ Documented the config options of TwigBundle (javiereguiluz)
+* `#6427 <https://github.com/symfony/symfony-docs/pull/6427>`_ [Testing] Explain how to add or remove data in a collection of forms (alexislefebvre)
+* `#6394 <https://github.com/symfony/symfony-docs/pull/6394>`_ Updated Heroku instructions (magnusnordlander)
+
+Fixed Documentation
+~~~~~~~~~~~~~~~~~~~
+
+* `#6503 <https://github.com/symfony/symfony-docs/pull/6503>`_ Fix typo in from flat PHP to Symfony (gregfriedrice, WouterJ)
+* `#6483 <https://github.com/symfony/symfony-docs/pull/6483>`_ Fix typo: signifcantly => significantly (ifdattic)
+* `#6482 <https://github.com/symfony/symfony-docs/pull/6482>`_ fixed wrong secret string in array examples (OskarStark)
+* `#6460 <https://github.com/symfony/symfony-docs/pull/6460>`_ Update authorization.rst (mantulo)
+* `#6451 <https://github.com/symfony/symfony-docs/pull/6451>`_ fix status code in snippet (Barno)
+* `#6448 <https://github.com/symfony/symfony-docs/pull/6448>`_ [Form] fixed CollectionType needless option (HeahDude)
+* `#6439 <https://github.com/symfony/symfony-docs/pull/6439>`_ Fix form/validation directory path (nemo-)
+
+Minor Documentation Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `#6522 <https://github.com/symfony/symfony-docs/pull/6522>`_ On line 360 the ``404 Not Found`` header not working (mbrig-co)
+* `#6521 <https://github.com/symfony/symfony-docs/pull/6521>`_ The ``$link`` argument must be passed as a reference (mbrig-co)
+* `#6523 <https://github.com/symfony/symfony-docs/pull/6523>`_ Fix snippet (ismailbaskin)
+* `#6472 <https://github.com/symfony/symfony-docs/pull/6472>`_ Avoid confusion (gerryvdm)
+* `#6300 <https://github.com/symfony/symfony-docs/pull/6300>`_ Document constraint validator alias optional (Triiistan)
+* `#6513 <https://github.com/symfony/symfony-docs/pull/6513>`_ remove documentation of not supported "verbose" option value (TobiasXy)
+* `#6510 <https://github.com/symfony/symfony-docs/pull/6510>`_ use port 587 in Amazon SES example (snoek09)
+* `#6464 <https://github.com/symfony/symfony-docs/pull/6464>`_ Added possible values for access_decision_manager.strategy (AAstakhov)
+* `#6478 <https://github.com/symfony/symfony-docs/pull/6478>`_ Replace reference to the request service (gerryvdm)
+* `#6479 <https://github.com/symfony/symfony-docs/pull/6479>`_ Update php.rst (carlos-granados)
+* `#6481 <https://github.com/symfony/symfony-docs/pull/6481>`_ Remove reference to Symfony2 in request-flow.png (Daniel Cotton)
+* `#6449 <https://github.com/symfony/symfony-docs/pull/6449>`_ [Form] fixed ChoiceType example in CollectionType (HeahDude)
+* `#6445 <https://github.com/symfony/symfony-docs/pull/6445>`_ updated the core team (fabpot)
+* `#6423 <https://github.com/symfony/symfony-docs/pull/6423>`_ Added a caution note about REMOTE_USER and user impersonation (javiereguiluz)
+* `#6452 <https://github.com/symfony/symfony-docs/pull/6452>`_ Use different placeholders in mailer config (sblaut)
+* `#6457 <https://github.com/symfony/symfony-docs/pull/6457>`_ Fixed an array notation in comment (serializer.rst) (iltar)
+* `#6456 <https://github.com/symfony/symfony-docs/pull/6456>`_ Fixed array [] notation and trailing spaces (iltar)
+* `#6420 <https://github.com/symfony/symfony-docs/pull/6420>`_ Added tip for optional second parameter for form submissions. (Michael Phillips)
+* `#6418 <https://github.com/symfony/symfony-docs/pull/6418>`_ fix spelling of the flashBag() method (xabbuh)
+
+
 March, 2016
 -----------
 

components/dependency_injection/definitions.rst

@@ -4,6 +4,9 @@
 Working with Container Service Definitions
 ==========================================
 
+Service definitions are the instructions describing how the container should
+build a service. They are not the actual services used by your applications
+
 Getting and Setting Service Definitions
 ---------------------------------------
 
@@ -32,34 +35,68 @@ with these methods and make changes to it these will be reflected in the
 container. If, however, you are creating a new definition then you can add
 it to the container using::
 
-    $container->setDefinition($id, $definition);
+    use Symfony\Component\DependencyInjection\Definition;
+
+    $definition = new Definition('Acme\Service\MyService');
+    $container->setDefinition('acme.my_service', $definition);
+
+.. tip::
+
+    Registering service definitions is so common that the container provides a
+    shortcut method called ``register()``::
+
+        $container->register('acme.my_service', 'Acme\Service\MyService');
 
 Working with a Definition
 -------------------------
 
 Creating a New Definition
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you need to create a new definition rather than manipulate one retrieved
-from the container then the definition class is :class:`Symfony\\Component\\DependencyInjection\\Definition`.
+In addition to manipulating and retrieving existing definitions, you can also
+define new service definitions with the :class:`Symfony\\Component\\DependencyInjection\\Definition`
+class.
 
 Class
 ~~~~~
 
-First up is the class of a definition, this is the class of the object returned
-when the service is requested from the container.
+The first optional argument of the ``Definition`` class is the fully qualified
+class name of the object returned when the service is fetched from the container::
 
-To find out what class is set for a definition::
+    use Symfony\Component\DependencyInjection\Definition;
+
+    $definition = new Definition('Acme\Service\MyService');
+
+If the class is unknown when instantiating the ``Definition`` class, use the
+``setClass()`` method to set it later::
 
-    $definition->getClass();
+    $definition->setClass('Acme\Service\MyService');
 
-and to set a different class::
+To find out what class is set for a definition::
 
-    $definition->setClass($class); // Fully qualified class name as string
+    $class = $definition->getClass();
+    // $class = 'Acme\Service\MyService'
 
 Constructor Arguments
 ~~~~~~~~~~~~~~~~~~~~~
 
+The second optional argument of the ``Definition`` class is an array with the
+arguments passed to the constructor of the object returned when the service is
+fetched from the container::
+
+    use Symfony\Component\DependencyInjection\Definition;
+
+    $definition = new Definition(
+        'Acme\Service\MyService',
+        array('argument1' => 'value1', 'argument2' => 'value2')
+    );
+
+If the arguments are unknown when instantiating the ``Definition`` class or if
+you want to add new arguments, use the ``addArgument()`` method, which adds them
+at the end of the arguments array::
+
+    $definition->addArgument($argument);
+
 To get an array of the constructor arguments for a definition you can use::
 
     $definition->getArguments();
@@ -69,12 +106,16 @@ or to get a single argument by its position::
     $definition->getArgument($index);
     // e.g. $definition->getArgument(0) for the first argument
 
-You can add a new argument to the end of the arguments array using::
+The argument can be a string, an array or a service parameter by using the
+``%parameter_name%`` syntax::
 
-    $definition->addArgument($argument);
+    $definition->addArgument('%kernel_debug%');
 
-The argument can be a string, an array, a service parameter by using ``%parameter_name%``
-or a service id by using::
+If the argument is another service, don't use the ``get()`` method to fetch it,
+because it won't be available when defining services. Instead, use the
+:class:`Symfony\\Component\\DependencyInjection\\Reference` class to get a
+reference to the service which will be available once the service container is
+fully built::
 
     use Symfony\Component\DependencyInjection\Reference;
 
@@ -139,4 +180,3 @@ the service itself gets loaded. To do so, you can use the
 
 Notice that Symfony will internally call the PHP statement ``require_once``,
 which means that your file will be included only once per request.
-

components/dependency_injection/introduction.rst

@@ -104,7 +104,9 @@ like this::
         // ...
     }
 
-Then you can register this as a service as well and pass the ``mailer`` service into it::
+When defining the ``newsletter_manager`` service, the ``mailer`` service does
+not exist yet. Use the ``Reference`` class to tell the container to inject the
+``mailer`` service when it initializes the newsletter manager::
 
     use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Reference;

contributing/community/releases.rst

@@ -187,4 +187,4 @@ version is published every two years and there is a year to upgrade.
 .. _SensioLabs:     http://sensiolabs.com/
 .. _roadmap notification: https://symfony.com/roadmap
 .. _extended to September 2014: https://symfony.com/blog/extended-maintenance-for-symfony-2-4
-.. _timeline calculator: https://symfony.com/roadmap
+.. _timeline calculator: https://symfony.com/roadmap#checker