Merge branch '3.2'

* 3.2:
  Expanded the explanation and updated the example
  Update doctrine.rst
  Update console.rst
  [#7452] remove trailing whitespaces
  Added filename references to examples
  Fix Typo $response->setEtag(..)
  Fixed typo
  Replace array with null
  Added a note about the usual cURL certificate problem
  Fixed code syntax issues
  Fix typo
  Replaced tabs with white spaces
  Replace "chapter" by "article" where appropriate
  Minor tweak
  Use statement for InputOption added to example
  Use HTTPS to link to symfony.com when possible
  fixed Backward Compatibility typo
  Update cache_pools.rst
  [DependencyInjection][Fix] Missing RequestStack

Author: xabbuh

_build/_theme/_templates/layout.html

@@ -1,13 +1,13 @@
 {% extends '!layout.html' %}
 
-{% set css_files = ['http://symfony.com/css/compiled/v5/all.css?v=4'] %}
+{% set css_files = ['https://symfony.com/css/compiled/v5/all.css?v=4'] %}
 {# make sure the Sphinx stylesheet isn't loaded #}
 {% set style = '' %}
 {% set isIndex = pagename is index %}
 
 {% block extrahead %}
 {# add JS to support tabs #}
-<script src="http://symfony.com/js/v5/all.js?v=4"></script>
+<script src="https://symfony.com/js/v5/all.js?v=4"></script>
 
 {# pygment's styles are still loaded, undo some unwanted styles #}
 <style>
@@ -48,7 +48,7 @@ <h4>Pull request build</h4>
                     <p>Each pull request of the Symfony Documentation is automatically deployed and hosted on <a href="https://platform.sh">Platform.sh</a>.<br>
                     View this page on <a href="https://symfony.com/doc/current/{{ pagename }}">symfony.com</a>.</p>
                 </div>
-                
+
                 {%- include "globaltoc.html" %}
 
                 {% if not isIndex %}
@@ -81,7 +81,7 @@ <h1 class="content_title">{{ title }}</h1>
                 <a href="{{ next.link|e }}">{{ next.title|striptags|e }} »</a>
             </div>
             {% endif %}
-            
+
             <div id="license">
                 <p>This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">License</a>.</p>
             </div>

best_practices/security.rst

@@ -235,16 +235,15 @@ more advanced use-case, you can always do the same security check in PHP:
 
         if (!$post->isAuthor($this->getUser())) {
             $this->denyAccessUnlessGranted('edit', $post);
-
-	    // or without the shortcut:
-	    //
-	    // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
-	    // ...
-	    //
-	    // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
-	    //    throw $this->createAccessDeniedException();
-	    // }
         }
+        // equivalent code without using the "denyAccessUnlessGranted()" shortcut:
+        //
+        // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+        // ...
+        //
+        // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
+        //    throw $this->createAccessDeniedException();
+        // }
 
         // ...
     }
@@ -398,6 +397,6 @@ If your company uses a user login method not supported by Symfony, you can
 develop :doc:`your own user provider </security/custom_provider>` and
 :doc:`your own authentication provider </security/custom_authentication_provider>`.
 
-.. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`@Security annotation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
+.. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle

components/browser_kit.rst

@@ -188,7 +188,7 @@ into the client constructor::
     $cookieJar = new Cookie('flavor', 'chocolate', strtotime('+1 day'));
 
     // create a client and set the cookies
-    $client = new Client(array(), array(), $cookieJar);
+    $client = new Client(array(), null, $cookieJar);
     // ...
 
 History

components/cache/cache_pools.rst

@@ -344,7 +344,7 @@ item in the cache immediately (it returns ``true`` if the item was saved or
 ``false`` if some error occurred)::
 
     // ...
-    $userFriends = $cache->get('user_'.$userId.'_friends');
+    $userFriends = $cache->getItem('user_'.$userId.'_friends');
     $userFriends->set($user->getFriends());
     $isSaved = $cache->save($userFriends);
 

components/http_foundation.rst

@@ -234,8 +234,8 @@ the
 method tells you if the request contains a session which was started in one of
 the previous requests.
 
-Accessing `Accept-*` Headers Data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Accessing ``Accept-*`` Headers Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can easily access basic data extracted from ``Accept-*`` headers
 by using the following methods:

components/options_resolver.rst

@@ -90,7 +90,7 @@ the ``Mailer`` class makes a mistake?
 .. code-block:: php
 
     $mailer = new Mailer(array(
-        'usernme' => 'johndoe',  // usernAme misspelled 
+        'usernme' => 'johndoe',  // usernAme misspelled
     ));
 
 No error will be shown. In the best case, the bug will appear during testing,
@@ -376,7 +376,7 @@ is thrown::
 For options with more complicated validation schemes, pass a closure which
 returns ``true`` for acceptable values and ``false`` for invalid values::
 
-    
+
     // ...
     $resolver->setAllowedValues('transport', function ($value) {
         // return true or false

components/yaml/yaml_format.rst

@@ -8,7 +8,7 @@ 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
-chapter only describes the minimum set of features needed to use YAML as a
+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

configuration.rst

@@ -95,7 +95,7 @@ specific bundle (i.e. ``FrameworkBundle`` and ``TwigBundle``).
 
 .. sidebar:: Configuration Formats
 
-    Throughout the chapters, all configuration examples will be shown in
+    Throughout the documentation, all configuration examples will be shown in
     three formats (YAML, XML and PHP). YAML is used by default, but you can
     choose whatever you like best. There is no performance difference:
 

configuration/external_parameters.rst

@@ -4,11 +4,11 @@
 How to Set external Parameters in the Service Container
 =======================================================
 
-In the chapter :doc:`/configuration`, you learned how to manage your application
-configuration. At times, it may benefit your application
-to store certain credentials outside of your project code. Database configuration
-is one such example. The flexibility of the Symfony service container allows
-you to easily do this.
+In the article :doc:`/configuration`, you learned how to manage your application
+configuration. At times, it may benefit your application to store certain
+credentials outside of your project code. Database configuration is one such
+example. The flexibility of the Symfony service container allows you to easily
+do this.
 
 Environment Variables
 ---------------------
@@ -22,7 +22,7 @@ will be resolved at runtime (once per request), so that dumped containers can be
 reconfigured dynamically even after being compiled.
 
 For example, if you want to use the value of the ``DATABASE_HOST`` environment
-variable in you service container configuration, you can reference it using
+variable in your service container configuration, you can reference it using
 ``%env(DATABASE_HOST)%`` in your configuration files:
 
 .. configuration-block::

configuration/front_controllers_and_kernel.rst

@@ -144,7 +144,7 @@ This method is responsible for loading the application's
 configuration from the right *environment*.
 
 Environments have been covered extensively
-:doc:`in the previous chapter </configuration/environments>`,
+:doc:`in the previous article </configuration/environments>`,
 and you probably remember that the Symfony Standard Edition comes with three
 of them - ``dev``, ``prod`` and ``test``.
 

console.rst

@@ -57,7 +57,7 @@ method. Then you can optionally define a help message and the
 
             // the full command description shown when running the command with
             // the "--help" option
-            ->setHelp("This command allows you to create users...")
+            ->setHelp('This command allows you to create users...')
         ;
     }
 

console/input.rst

@@ -118,6 +118,9 @@ simply as a boolean flag without a value (e.g.  ``--yell``).
 For example, add a new option to the command that can be used to specify
 how many times in a row the message should be printed::
 
+    // ...
+    use Symfony\Component\Console\Input\InputOption;
+
     $this
         // ...
         ->addOption(

console/verbosity.rst

@@ -68,7 +68,7 @@ verbosity levels::
     These semantic methods are defined in the ``OutputInterface`` starting from
     Symfony 3.0. In previous Symfony versions they are defined in the different
     implementations of the interface (e.g. :class:`Symfony\\Component\\Console\\Output\\Output`)
-    in order to keep backwards compatibility.
+    in order to keep backward compatibility.
 
 When the quiet level is used, all output is suppressed as the default
 :method:`Symfony\\Component\\Console\\Output\\Output::write` method returns

contributing/code/bc.rst

@@ -1,11 +1,11 @@
-Our Backwards Compatibility Promise
-===================================
+Our Backward Compatibility Promise
+==================================
 
 Ensuring smooth upgrades of your projects is our first priority. That's why
-we promise you backwards compatibility (BC) for all minor Symfony releases.
+we promise you backward compatibility (BC) for all minor Symfony releases.
 You probably recognize this strategy as `Semantic Versioning`_. In short,
 Semantic Versioning means that only major releases (such as 2.0, 3.0 etc.) are
-allowed to break backwards compatibility. Minor releases (such as 2.5, 2.6 etc.)
+allowed to break backward compatibility. Minor releases (such as 2.5, 2.6 etc.)
 may introduce new features, but must do so without breaking the existing API of
 that release branch (2.x in the previous example).
 
@@ -14,7 +14,7 @@ that release branch (2.x in the previous example).
     This promise was introduced with Symfony 2.3 and does not apply to previous
     versions of Symfony.
 
-However, backwards compatibility comes in many different flavors. In fact, almost
+However, backward compatibility comes in many different flavors. In fact, almost
 every change that we make to the framework can potentially break an application.
 For example, if we add a new method to a class, this will break an application
 which extended this class and added the same method, but with a different
@@ -63,10 +63,10 @@ sticks to these rules.
 If you implement an interface, we promise that we won't ever break your code.
 
 The following table explains in detail which use cases are covered by our
-backwards compatibility promise:
+backward compatibility promise:
 
 +-----------------------------------------------+-----------------------------+
-| Use Case                                      | Backwards Compatibility     |
+| Use Case                                      | Backward Compatibility      |
 +===============================================+=============================+
 | **If you...**                                 | **Then we guarantee BC...** |
 +-----------------------------------------------+-----------------------------+
@@ -97,10 +97,10 @@ public methods and properties.
     not be accessed by your own code.
 
 To be on the safe side, check the following table to know which use cases are
-covered by our backwards compatibility promise:
+covered by our backward compatibility promise:
 
 +-----------------------------------------------+-----------------------------+
-| Use Case                                      | Backwards Compatibility     |
+| Use Case                                      | Backward Compatibility      |
 +===============================================+=============================+
 | **If you...**                                 | **Then we guarantee BC...** |
 +-----------------------------------------------+-----------------------------+

contributing/code/security.rst

@@ -103,7 +103,7 @@ Security Advisories
 This section indexes security vulnerabilities that were fixed in Symfony
 releases, starting from Symfony 1.0.0:
 
-* May 9, 2016: `CVE-2016-2403: Unauthorized access on a misconfigured Ldap server when using an empty password <http://symfony.com/blog/cve-2016-2403-unauthorized-access-on-a-misconfigured-ldap-server-when-using-an-empty-password>`_ (2.8.0-2.8.5, 3.0.0-3.0.5)
+* May 9, 2016: `CVE-2016-2403: Unauthorized access on a misconfigured Ldap server when using an empty password <https://symfony.com/blog/cve-2016-2403-unauthorized-access-on-a-misconfigured-ldap-server-when-using-an-empty-password>`_ (2.8.0-2.8.5, 3.0.0-3.0.5)
 * May 9, 2016: `CVE-2016-4423: Large username storage in session <https://symfony.com/blog/cve-2016-4423-large-username-storage-in-session>`_ (2.3.0-2.3.40, 2.7.0-2.7.12, 2.8.0-2.8.5, 3.0.0-3.0.5)
 * January 18, 2016: `CVE-2016-1902: SecureRandom's fallback not secure when OpenSSL fails <https://symfony.com/blog/cve-2016-1902-securerandom-s-fallback-not-secure-when-openssl-fails>`_ (2.3.0-2.3.36, 2.6.0-2.6.12, 2.7.0-2.7.8)
 * November 23, 2015: `CVE-2015-8125: Potential Remote Timing Attack Vulnerability in Security Remember-Me Service <https://symfony.com/blog/cve-2015-8125-potential-remote-timing-attack-vulnerability-in-security-remember-me-service>`_ (2.3.35, 2.6.12 and 2.7.7)

contributing/community/releases.rst

@@ -140,10 +140,10 @@ Version  Feature Freeze  Release  End of Maintenance        End of Life
 .. [2] Symfony 2.8 is the last version of the Symfony 2.x branch.
 .. [3] Symfony 3.0 is the first version to use the new release process based on five minor releases.
 
-Backwards Compatibility
------------------------
+Backward Compatibility
+----------------------
 
-Our :doc:`Backwards Compatibility Promise </contributing/code/bc>` is very
+Our :doc:`Backward Compatibility Promise </contributing/code/bc>` is very
 strict and allows developers to upgrade with confidence from one minor version
 of Symfony to the next one.
 

contributing/community/reviews.rst

@@ -22,7 +22,7 @@ status:
 * **Pull Requests**: Pull requests contain code that fixes a bug or implements
   new functionality. Reviews of pull requests ensure that they are implemented
   properly, are covered by test cases, don't introduce new bugs and maintain
-  backwards compatibility.
+  backward compatibility.
 
 Note that **anyone who has some basic familiarity with Symfony and PHP can
 review bug reports and pull requests**. You don't need to be an expert to help.
@@ -140,12 +140,12 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
    * Does the PR contain automated tests? Do those tests cover all relevant
      edge cases?
    * Does the PR contain sufficient comments to easily understand its code?
-   * Does the code break backwards compatibility? If yes, does the PR header say
+   * Does the code break backward compatibility? If yes, does the PR header say
      so?
    * Does the PR contain deprecations? If yes, does the PR header say so? Does
      the code contain ``trigger_error()`` statements for all deprecated
      features?
-   * Are all deprecations and backwards compatibility breaks documented in the
+   * Are all deprecations and backward compatibility breaks documented in the
      latest UPGRADE-X.X.md file? Do those explanations contain "Before"/"After"
      examples with clear upgrade instructions?
 
@@ -210,7 +210,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
 .. _bug reports in need of review: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22Bug%22+label%3A%22Status%3A+Needs+Review%22+
 .. _PRs in need of review: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Apr+label%3A%22Status%3A+Needs+Review%22+
 .. _Contribution Guidelines: https://github.com/symfony/symfony/blob/master/CONTRIBUTING.md
-.. _Symfony's Release Schedule: http://symfony.com/doc/current/contributing/community/releases.html#schedule
+.. _Symfony's Release Schedule: https://symfony.com/doc/current/contributing/community/releases.html#schedule
 .. _Symfony Roadmap: https://symfony.com/roadmap
 .. _Carson Bot: https://github.com/carsonbot/carsonbot
 .. _`Needs Review`: https://github.com/symfony/symfony/labels/Status%3A%20Needs%20Review

contributing/documentation/overview.rst

@@ -126,9 +126,9 @@ memorable name for the new branch (if you are fixing a reported issue, use
 
 .. code-block:: terminal
 
-    $ git checkout -b improve_install_chapter upstream/2.7
+    $ git checkout -b improve_install_article upstream/2.7
 
-In this example, the name of the branch is ``improve_install_chapter`` and the
+In this example, the name of the branch is ``improve_install_article`` and the
 ``upstream/2.7`` value tells Git to create this branch based on the ``2.7``
 branch of the ``upstream`` remote, which is the original Symfony Docs repository.
 
@@ -151,10 +151,10 @@ even remove any content and do your best to comply with the
 
 .. code-block:: terminal
 
-    $ git push origin improve_install_chapter
+    $ git push origin improve_install_article
 
 The ``origin`` value is the name of the Git remote that corresponds to your
-forked repository and ``improve_install_chapter`` is the name of the branch you
+forked repository and ``improve_install_article`` is the name of the branch you
 created previously.
 
 **Step 7.** Everything is now ready to initiate a **pull request**. Go to your
@@ -171,7 +171,7 @@ changes should be applied:
 In this example, the **base fork** should be ``symfony/symfony-docs`` and
 the **base** branch should be the ``2.7``, which is the branch that you selected
 to base your changes on. The **head fork** should be your forked copy
-of ``symfony-docs`` and the **compare** branch should be ``improve_install_chapter``,
+of ``symfony-docs`` and the **compare** branch should be ``improve_install_article``,
 which is the name of the branch you created and where you made your changes.
 
 .. _pull-request-format:
@@ -192,7 +192,7 @@ changes and push the new changes:
 .. code-block:: terminal
 
     $ cd projects/symfony-docs/
-    $ git checkout improve_install_chapter
+    $ git checkout improve_install_article
 
     # ... do your changes
 

contributing/documentation/translations.rst

@@ -4,4 +4,4 @@ Translations
 The Symfony documentation is not officially translated, though some community
 groups still maintain some translations. For more information, see `this blog post`_.
 
-.. _`this blog post`: http://symfony.com/blog/discontinuing-the-symfony-community-translations
+.. _`this blog post`: https://symfony.com/blog/discontinuing-the-symfony-community-translations

contributing/map.rst.inc

@@ -7,7 +7,7 @@
   * :doc:`The Core Team </contributing/code/core_team>`
   * :doc:`Security </contributing/code/security>`
   * :doc:`Tests </contributing/code/tests>`
-  * :doc:`Backwards Compatibility </contributing/code/bc>`
+  * :doc:`Backward Compatibility </contributing/code/bc>`
   * :doc:`Coding Standards</contributing/code/standards>`
   * :doc:`Code Conventions</contributing/code/conventions>`
   * :doc:`Git</contributing/code/git>`