Merge remote-tracking branch 'upstream/3.3' into 3.3

Author: javiereguiluz

best_practices/business-logic.rst

@@ -121,7 +121,7 @@ Now you can use the custom slugger in any controller class, such as the
         // $slugger = $this->get('app.slugger');
 
         if ($form->isSubmitted() && $form->isValid()) {
-            $slug = $this->get('app.slugger')->slugify($post->getTitle());
+            $slug = $slugger->slugify($post->getTitle());
             $post->setSlug($slug);
 
             // ...

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>(),
                 );
 
@@ -406,9 +407,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``
@@ -418,8 +419,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
@@ -455,3 +455,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

@@ -349,9 +349,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

@@ -400,8 +400,6 @@ Now, register this class as a Doctrine listener:
             <!-- ... -->
 
             <service id="AppBundle\EventListener\BrochureUploaderListener">
-                <argument type="service" id="app.brochure_uploader"/>
-
                 <tag name="doctrine.event_listener" event="prePersist"/>
                 <tag name="doctrine.event_listener" event="preUpdate"/>
             </service>

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`_).
@@ -207,6 +208,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>
@@ -154,15 +155,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
@@ -177,7 +177,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