Merge branch '2.7' into 2.8

* 2.7: (32 commits)
  Minor reword
  Update deployment.rst
  Update best_practices.rst
  Better explain the purpose of the "license" Composer metadata
  Reverted the changes about bundle namespaces
  Removed backticks from bundle names
  add mention of symfony.com re folder structure
  reword the documentation section re Resources/doc
  Reverting previous grammar change
  Removing trailing space
  Minor changes throughout BP for Reusable Bundles
  Mention the YAML features not supported by the Yaml component
  Update storage.rst
  Moved the commas in the opening paragraph.
  Adjust .platform.app.yaml from 'symfony' to 'composer'
  Don't pass .ico through app.php
  Update upload_file.rst
  Fixed class namespaces
  Reworded the prepare() method explanation
  Update dev_environment.rst
  ...

Author: xabbuh

bundles/best_practices.rst

@@ -31,7 +31,7 @@ Bundle Name
 A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or
 `PSR-4`_ interoperability standards for PHP namespaces and class names: it starts
 with a vendor segment, followed by zero or more category segments, and it ends
-with the namespace short name, which must end with a ``Bundle`` suffix.
+with the namespace short name, which must end with ``Bundle``.
 
 A namespace becomes a bundle as soon as you add a bundle class to it. The
 bundle class name must follow these simple rules:
@@ -48,8 +48,8 @@ Here are some valid bundle namespaces and class names:
 ==========================  ==================
 Namespace                   Bundle Class Name
 ==========================  ==================
-``Acme\Bundle\BlogBundle``  ``AcmeBlogBundle``
-``Acme\BlogBundle``         ``AcmeBlogBundle``
+``Acme\Bundle\BlogBundle``  AcmeBlogBundle
+``Acme\BlogBundle``         AcmeBlogBundle
 ==========================  ==================
 
 By convention, the ``getName()`` method of the bundle class should return the
@@ -58,8 +58,7 @@ class name.
 .. note::
 
     If you share your bundle publicly, you must use the bundle class name as
-    the name of the repository (``AcmeBlogBundle`` and not ``BlogBundle``
-    for instance).
+    the name of the repository (AcmeBlogBundle and not BlogBundle for instance).
 
 .. note::
 
@@ -68,7 +67,7 @@ class name.
     :class:`Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle`.
 
 Each bundle has an alias, which is the lower-cased short version of the bundle
-name using underscores (``acme_blog`` for ``AcmeBlogBundle``). This alias
+name using underscores (``acme_blog`` for AcmeBlogBundle). This alias
 is used to enforce uniqueness within a project and for defining bundle's
 configuration options (see below for some usage examples).
 
@@ -105,8 +104,8 @@ that automated tools can rely on:
   bundles are published under the MIT license, but you can `choose any license`_;
 * ``Resources/doc/index.rst``: The root file for the Bundle documentation.
 
-The depth of sub-directories should be kept to the minimum for most used
-classes and files (two levels maximum).
+The depth of subdirectories should be kept to a minimum for the most used
+classes and files. Two levels is the maximum.
 
 The bundle directory is read-only. If you need to write temporary files, store
 them under the ``cache/`` or ``log/`` directory of the host application. Tools
@@ -138,9 +137,9 @@ Classes
 -------
 
 The bundle directory structure is used as the namespace hierarchy. For
-instance, a ``ContentController`` controller is stored in
-``Acme/BlogBundle/Controller/ContentController.php`` and the fully qualified
-class name is ``Acme\BlogBundle\Controller\ContentController``.
+instance, a ``ContentController`` controller which is stored in
+``Acme/BlogBundle/Controller/ContentController.php`` would have the fully
+qualified class name of ``Acme\BlogBundle\Controller\ContentController``.
 
 All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.
 
@@ -158,8 +157,8 @@ Vendors
 A bundle must not embed third-party PHP libraries. It should rely on the
 standard Symfony autoloading instead.
 
-A bundle should not embed third-party libraries written in JavaScript, CSS or
-any other language.
+A bundle should also not embed third-party libraries written in JavaScript,
+CSS or any other language.
 
 Tests
 -----
@@ -183,10 +182,13 @@ Documentation
 
 All classes and functions must come with full PHPDoc.
 
-Extensive documentation should also be provided in the
-:doc:`reStructuredText </contributing/documentation/format>` format, under
-the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is
-the only mandatory file and must be the entry point for the documentation.
+Extensive documentation should also be provided in the ``Resources/doc/`` 
+directory.
+The index file (for example ``Resources/doc/index.rst`` or 
+``Resources/doc/index.md``) is the only mandatory file and must be the entry 
+point for the documentation. The 
+:doc:`reStructuredText (rST) </contributing/documentation/format>` is the format
+used to render the documentation on symfony.com.
 
 Installation Instructions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -232,7 +234,6 @@ following standardized instructions in your ``README.md`` file.
             {
                 $bundles = array(
                     // ...
-
                     new <vendor>\<bundle-name>\<bundle-long-name>(),
                 );
 
@@ -399,9 +400,9 @@ The ``composer.json`` file should include at least the following metadata:
 ``name``
     Consists of the vendor and the short bundle name. If you are releasing the
     bundle on your own instead of on behalf of a company, use your personal name
-    (e.g. ``johnsmith/blog-bundle``). The bundle short name excludes the vendor
-    name and separates each word with an hyphen. For example: ``AcmeBlogBundle``
-    is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is
+    (e.g. ``johnsmith/blog-bundle``). Exclude the vendor name from the bundle
+    short name and separate each word with an hyphen. For example: AcmeBlogBundle
+    is transformed into ``blog-bundle`` and AcmeSocialConnectBundle is
     transformed into ``social-connect-bundle``.
 
 ``description``
@@ -411,8 +412,7 @@ The ``composer.json`` file should include at least the following metadata:
     Use the ``symfony-bundle`` value.
 
 ``license``
-    ``MIT`` is the preferred license for Symfony bundles, but you can use any
-    other license.
+    a string (or array of strings) with a `valid license identifier`_, such as ``MIT``.
 
 ``autoload``
     This information is used by Symfony to load the classes of the bundle. The
@@ -497,3 +497,4 @@ Learn more
 .. _`Semantic Versioning Standard`: http://semver.org/
 .. _`Packagist`: https://packagist.org/
 .. _`choose any license`: http://choosealicense.com/
+.. _`valid license identifier`: https://spdx.org/licenses/

components/http_foundation.rst

@@ -352,9 +352,9 @@ UTF-8.
 Sending the Response
 ~~~~~~~~~~~~~~~~~~~~
 
-Before sending the Response, you can ensure that it is compliant with the HTTP
-specification by calling the
-:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method::
+Before sending the Response, you can optionally call the
+:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method to fix any
+incompatibility with the HTTP specification (e.g. a wrong ``Content-Type`` header)::
 
     $response->prepare($request);
 

components/yaml/yaml_format.rst

@@ -4,16 +4,11 @@
 The YAML Format
 ===============
 
-According to the official `YAML`_ website, YAML is "a human friendly data
-serialization standard for all programming languages".
-
-Even if the YAML format can describe complex nested data structure, this
-article only describes the minimum set of features needed to use YAML as a
-configuration file format.
-
-YAML is a simple language that describes data. As PHP, it has a syntax for
-simple types like strings, booleans, floats, or integers. But unlike PHP, it
-makes a difference between arrays (sequences) and hashes (mappings).
+According to the official `YAML website`_, YAML is "a human friendly data
+serialization standard for all programming languages". The Symfony Yaml
+component implements a subset of the `YAML specification`_. Specifically, it
+implements the minimum set of features needed to use YAML as a configuration
+file format.
 
 Scalars
 -------
@@ -171,8 +166,8 @@ Collections
 -----------
 
 A YAML file is rarely used to describe a simple scalar. Most of the time, it
-describes a collection. A collection can be a sequence or a mapping of
-elements. Both sequences and mappings are converted to PHP arrays.
+describes a collection. YAML collections can be a sequence (indexed arrays in PHP)
+or a mapping of elements (associative arrays in PHP).
 
 Sequences use a dash followed by a space:
 
@@ -318,4 +313,20 @@ The YAML specification defines some tags to set the type of any data explicitly:
             Pz7Y6OjuDg4J+fn5OTk6enp
             56enmleECcgggoBADs=
 
-.. _YAML: http://yaml.org/
+Unsupported YAML Features
+-------------------------
+
+The following YAML features are not supported by the Symfony Yaml component:
+
+* Multi-documents (``---`` and ``...`` markers);
+* Complex mapping keys and complex values starting with ``?``;
+* Tagged values as keys;
+* The following tags and types: `!!set`, `!!omap`, `!!pairs`, `!!set`, `!!seq`,
+  `!!bool`, `!!int`, `!!merge`, `!!null`, `!!timestamp`, `!!value`, `!!yaml`;
+* Tags (``TAG`` directive; example: ``%TAG ! tag:example.com,2000:app/``)
+  and tag references (example: ``!<tag:example.com,2000:app/foo>``);
+* Using sequence-like syntax for mapping elements (example: ``{foo, bar}``; use
+  ``{foo: ~, bar: ~}`` instead).
+
+.. _`YAML website`: http://yaml.org/
+.. _`YAML specification`: http://www.yaml.org/spec/1.2/spec.html

controller/upload_file.rst

@@ -412,7 +412,7 @@ Now, register this class as a Doctrine listener:
 
         // ...
         $container->register('app.doctrine_brochure_listener', BrochureUploaderListener::class)
-            ->addArgument(new Reference('brochures_directory'))
+            ->addArgument(new Reference('app.brochure_uploader'))
             ->addTag('doctrine.event_listener', array(
                 'event' => 'prePersist',
             ))

deployment.rst

@@ -52,9 +52,10 @@ Using Source Control
 ~~~~~~~~~~~~~~~~~~~~
 
 If you're using source control (e.g. Git or SVN), you can simplify by having
-your live installation also be a copy of your repository. When you're ready
-to upgrade it is as simple as fetching the latest updates from your source
-control system.
+your live installation also be a copy of your repository. When you're ready to
+upgrade it is as simple as fetching the latest updates from your source control
+system. When using Git, a common approach is to create a tag for each release
+and check out the appropriate tag on deployment (see `Git Tagging`_).
 
 This makes updating your files *easier*, but you still need to worry about
 manually taking other steps (see `Common Post-Deployment Tasks`_).
@@ -206,6 +207,7 @@ Don't forget that deploying your application also involves updating any dependen
 (typically via Composer), migrating your database, clearing your cache and
 other potential things like pushing assets to a CDN (see `Common Post-Deployment Tasks`_).
 
+.. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging
 .. _`Capifony`: https://github.com/everzet/capifony
 .. _`Capistrano`: http://capistranorb.com/
 .. _`sf2debpkg`: https://github.com/liip/sf2debpkg

deployment/azure-website.rst

@@ -417,7 +417,7 @@ application, configure it with the following content:
               <action type="CustomResponse" statusCode="403" statusReason="Forbidden: Access is denied." statusDescription="You do not have permission to view this directory or page using the credentials that you supplied." />
             </rule>
             <rule name="RewriteAssetsToPublic" stopProcessing="true">
-              <match url="^(.*)(\.css|\.js|\.jpg|\.png|\.gif)$" />
+              <match url="^(.*)(\.css|\.js|\.jpg|\.png|\.gif|\.ico)$" />
               <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
               </conditions>
               <action type="Rewrite" url="web/{R:0}" />

deployment/fortrabbit.rst

@@ -151,7 +151,7 @@ Make sure this file is imported into the main config file:
             <!-- .. -->
             <framework:config>
                 <!-- .. -->
-                <framework:session save-path="null" />
+                <framework:session handler-id="null" />
             </framework:config>
         </container>
 

deployment/platformsh.rst

@@ -41,7 +41,7 @@ Platform.sh how to deploy your application (read more about
     # The type of the application to build.
     type: php:5.6
     build:
-      flavor: symfony
+      flavor: composer
 
     # The relationships of the application with services or other applications.
     # The left-hand side is the name of the relationship as it will be exposed

email/dev_environment.rst

@@ -28,7 +28,7 @@ will not be sent when you run tests, but will continue to be sent in the
 
         # app/config/config_test.yml
         swiftmailer:
-            disable_delivery:  true
+            disable_delivery: true
 
     .. code-block:: xml
 
@@ -48,7 +48,7 @@ will not be sent when you run tests, but will continue to be sent in the
 
         // app/config/config_test.php
         $container->loadFromExtension('swiftmailer', array(
-            'disable_delivery'  => "true",
+            'disable_delivery' => "true",
         ));
 
 If you'd also like to disable deliver in the ``dev`` environment, simply
@@ -80,7 +80,8 @@ via the ``delivery_addresses`` option:
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
                 http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+                http://symfony.com/schema/dic/swiftmailer
+                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
             <swiftmailer:config>
                 <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
@@ -155,15 +156,14 @@ by adding the ``delivery_whitelist`` option:
     .. code-block:: xml
 
         <!-- app/config/config_dev.xml -->
-
-        <?xml version="1.0" charset="UTF-8" ?>
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
                 http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+                http://symfony.com/schema/dic/swiftmailer
+                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
             <swiftmailer:config>
                 <!-- all email addresses matching these regexes will be delivered
@@ -178,7 +178,7 @@ by adding the ``delivery_whitelist`` option:
 
         // app/config/config_dev.php
         $container->loadFromExtension('swiftmailer', array(
-            'delivery_addresses'  => array("dev@example.com"),
+            'delivery_addresses' => array("dev@example.com"),
             'delivery_whitelist' => array(
                 // all email addresses matching these regexes will be delivered
                 // like normal, as well as being sent to dev@example.com

form/action_method.rst

@@ -56,7 +56,7 @@ form, you can use ``setAction()`` and ``setMethod()``:
         $formFactory = $formFactoryBuilder->getFormFactory();
 
         $form = $formFactory->createBuilder(FormType::class, $task)
-            ->setAction($this->generateUrl('target_route'))
+            ->setAction('...')
             ->setMethod('GET')
             ->add('task', TextType::class)
             ->add('dueDate', DateType::class)
@@ -108,7 +108,7 @@ options:
         $formFactory = $formFactoryBuilder->getFormFactory();
 
         $form = $formFactory->create(TaskType::class, $task, array(
-            'action' => $this->generateUrl('target_route'),
+            'action' => '...',
             'method' => 'GET',
         ));
 

form/multiple_buttons.rst

@@ -31,3 +31,10 @@ querying if the "Save and add" button was clicked::
 
         return $this->redirectToRoute($nextAction);
     }
+
+Or you can get the button's name by using the
+:method:`Symfony\\Component\\Form\\Form::getClickedButton` method of the form::
+
+    if ($form->getClickedButton() && 'saveAndAdd' === $form->getClickedButton()->getName()) {
+        // ...
+    }

logging/monolog_email.rst

@@ -143,6 +143,44 @@ then passes them onto the nested handler in one go, but only if the records are
 unique over a given period of time (60 seconds by default). If the records are
 duplicates they are simply discarded. Adding this handler reduces the amount of
 notifications to a manageable level, specially in critical failure scenarios.
+You can adjust the time period using the ``time`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config_prod.yml
+        monolog:
+            handlers:
+                # ...
+                deduplicated:
+                    type: deduplication
+                    # the time in seconds during which duplicate entries are discarded (default: 60)
+                    time: 10
+                    handler: swift
+
+    .. code-block:: xml
+
+        <!-- app/config/config_prod.xml -->
+
+        <!-- time: the time in seconds during which duplicate entries are discarded (default: 60) -->
+        <monolog:handler name="deduplicated"
+            type="deduplication"
+            time="10"
+            handler="swift" />
+
+    .. code-block:: php
+
+        // app/config/config_prod.php
+        $container->loadFromExtension('monolog', array(
+            'handlers' => array(
+                // ...
+                'deduplicated' => array(
+                    'type'    => 'deduplication',
+                    // the time in seconds during which duplicate entries are discarded (default: 60)
+                    'time' => 10,
+                    'handler' => 'swift',
+                 )
 
 The messages are then passed to the ``swift`` handler. This is the handler that
 actually deals with emailing you the error. The settings for this are

profiler/storage.rst

@@ -50,7 +50,7 @@ uses MySQL as the storage for the profiler with a lifetime of one hour:
         // ...
         $container->loadFromExtension('framework', array(
             'profiler' => array(
-                'dsn'      => 'mysql:host=localhost;dbname=%database_name%',
+                'dsn' => 'mysql:host=localhost;dbname=%database_name%',
                 'username' => '%database_user',
                 'password' => '%database_password%',
                 'lifetime' => 3600,