Merge branch '5.1' into 5.2

* 5.1: (31 commits)
  Fix package name for OvhCloud notifier
  Fix wrong key name
  Enhancement: Streamline workflow
  GitHub Actions: use docker container for CI build
  Bus restricting with Interfaces
  Security: add example code which Maker Bundle generated
  [symfony#14550] Reduce nr of lines used for exception
  Section method only in ConsoleOutputInterface
  Added a new troubleshooting section in the maintainer guide
  Removed duplicated line
  Complete documentation about mailer integration
  [symfony#14083] Revert mailer.headers option in 4.4 - 5.1
  Removed 4.3 versionadded directive
  [symfony#14565] Minor formatting fixes
  Updated getParent() description with the why/when (thanks javier!)
  [Form] Added explicit `getParent()` call in types inheritance mechanism
  Added PHP types to the DI related articles
  Added PHP types to the Form related articles
  Added PHP types to the Doctrine related articles
  Tweak
  ...

Author: OskarStark

.github/workflows/ci.yaml

@@ -1,3 +1,5 @@
+name: CI
+
 on:
     push:
         branches-ignore:
@@ -6,83 +8,73 @@ on:
         branches-ignore:
             - 'github-comments'
 
-name: CI
-
 jobs:
-    build:
-        name: Build
+    sphinx-build:
+        name: Build (Sphinx)
 
         runs-on: ubuntu-latest
 
+        container: python:3.7-alpine
+
         steps:
             -   name: "Checkout"
                 uses: actions/checkout@v2
 
-            -   name: "Set up Python 3.7"
-                uses: actions/setup-python@v1
-                with:
-                    python-version: '3.7' # Semantic version range syntax or exact version of a Python version
-
             -   name: "Display Python version"
                 run: python -c "import sys; print(sys.version)"
 
-            -   name: "Install Sphinx dependencies"
-                run: sudo apt-get install python-dev build-essential
+            -   name: "Install Sphinx"
+                run: pip install --user sphinx
 
-            -   name: "Cache pip"
-                uses: actions/cache@v2
-                with:
-                    path: ~/.cache/pip
-                    key: ${{ runner.os }}-pip-${{ hashFiles('_build/.requirements.txt') }}
-                    restore-keys: |
-                        ${{ runner.os }}-pip-
+            -   name: "Install dependencies"
+                run: apk add --no-cache git make
 
-            -   name: "Install Sphinx + requirements via pip"
+            -   name: "Install custom requirements via pip"
                 run: pip install -r _build/.requirements.txt
 
             -   name: "Build documentation"
                 run: make -C _build SPHINXOPTS="-nqW -j auto" html
 
-    build-php:
-        name: Symfony doc builder
+    symfony-docs-builder-build:
+        name: Build (symfony/docs-builder)
 
         runs-on: ubuntu-latest
 
         continue-on-error: true
 
         steps:
-            - name: "Checkout"
-              uses: actions/checkout@v2
-
-            - name: "Set-up PHP"
-              uses: shivammathur/setup-php@v2
-              with:
-                  php-version: 7.2
-                  coverage: none
-                  tools: "composer:v2"
-
-            - name: Get composer cache directory
-              id: composercache
-              working-directory: _build
-              run: echo "::set-output name=dir::$(composer config cache-files-dir)"
-
-            - name: Cache dependencies
-              uses: actions/cache@v2
-              with:
-                  path: ${{ steps.composercache.outputs.dir }}
-                  key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
-                  restore-keys: ${{ runner.os }}-composer-
-
-            - name: "Install dependencies"
-              working-directory: _build
-              run: composer install --prefer-dist --no-progress
-
-            - name: "Build the docs"
-              working-directory: _build
-              run: php build.php -vvv
+            -   name: "Checkout"
+                uses: actions/checkout@v2
+
+            -   name: "Set-up PHP"
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 7.2
+                    coverage: none
+                    tools: "composer:v2"
+
+            -   name: Get composer cache directory
+                id: composercache
+                working-directory: _build
+                run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+            -   name: Cache dependencies
+                uses: actions/cache@v2
+                with:
+                    path: ${{ steps.composercache.outputs.dir }}
+                    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+                    restore-keys: ${{ runner.os }}-composer-
+
+            -   name: "Install dependencies"
+                working-directory: _build
+                run: composer install --prefer-dist --no-progress
+
+            -   name: "Build the docs"
+                working-directory: _build
+                run: php build.php -vvv
 
     doctor-rst:
-        name: DOCtor-RST
+        name: Lint (DOCtor-RST)
 
         runs-on: ubuntu-latest
 

README.markdown

@@ -11,9 +11,9 @@ Symfony documentation, please read
 [Contributing to the Documentation](https://symfony.com/doc/current/contributing/documentation/overview.html)
 
 > **Note**
-> All pull requests must be based off of the **3.4** branch,
-> unless you're documenting a feature that was introduced *after* Symfony 3.4
-> (e.g. in Symfony 4.4), **not** the master or older branches.
+> All pull requests must be based off of the **4.4** branch,
+> unless you're documenting a feature that was introduced *after* Symfony 4.4
+> (e.g. in Symfony 5.2), **not** the ``5.x`` or older branches.
 
 SymfonyCloud
 ------------

_build/maintainer_guide.rst

@@ -335,6 +335,23 @@ in the tree as follows:
     $ git push origin
     $ git push upstream
 
+Merging in the wrong branch
+...........................
+
+A Pull Request was made against ``5.x`` but it should be merged in ``5.1`` and you
+forgot to merge as ``gh merge NNNNN -s 5.1`` to change the merge branch. Solution:
+
+.. code-block:: terminal
+
+    $ git checkout 5.1
+    $ git cherry-pick <SHA OF YOUR MERGE COMMIT> -m 1
+    $ git checkout 5.x
+    $ git revert <SHA OF YOUR MERGE COMMIT> -m 1
+    # now continue with the normal "upmerging"
+    $ git checkout 5.2
+    $ git merge 5.1
+    $ ...
+
 .. _`symfony/symfony-docs`: https://github.com/symfony/symfony-docs
 .. _`Symfony Docs team`: https://github.com/orgs/symfony/teams/team-symfony-docs
 .. _`Symfony's respectful review comments`: https://symfony.com/doc/current/contributing/community/review-comments.html

components/cache/adapters/filesystem_adapter.rst

@@ -50,11 +50,9 @@ and cache root path as constructor parameters::
 
 .. note::
 
-    Since Symfony 3.4, this adapter implements
-    :class:`Symfony\\Component\\Cache\\PruneableInterface`, enabling manual
-    :ref:`pruning of expired cache items <component-cache-cache-pool-prune>` by
-    calling its ``prune()`` method.
-
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
+    enabling manual :ref:`pruning of expired cache items <component-cache-cache-pool-prune>`
+    by calling its ``prune()`` method.
 
 .. _filesystem-tag-aware-adapter:
 

components/cache/adapters/pdo_doctrine_dbal_adapter.rst

@@ -44,7 +44,7 @@ your code.
 
 .. note::
 
-    Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
     allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
     calling its ``prune()`` method.
 

components/cache/adapters/php_files_adapter.rst

@@ -63,7 +63,7 @@ directory path as constructor arguments::
 
 .. note::
 
-    Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
     allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
     calling its ``prune()`` method.
 

components/cache/cache_invalidation.rst

@@ -87,7 +87,7 @@ your fronts and have very fast invalidation checks::
 
 .. note::
 
-    Since Symfony 3.4, :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`
+    :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`
     implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
     enabling manual
     :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by

console.rst

@@ -187,16 +187,24 @@ called "output sections". Create one or more of these sections when you need to
 clear and overwrite the output information.
 
 Sections are created with the
-:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method,
-which returns an instance of
+:method:`ConsoleOutput::section() <Symfony\\Component\\Console\\Output\\ConsoleOutput::section>`
+method, which returns an instance of
 :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`::
 
+    // ...
+    use Symfony\Component\Console\Output\ConsoleOutputInterface;
+
     class MyCommand extends Command
     {
         protected function execute(InputInterface $input, OutputInterface $output)
         {
+            if (!$output instanceof ConsoleOutputInterface) {
+                throw new \LogicException('This command accepts only an instance of "ConsoleOutputInterface".');
+            }
+
             $section1 = $output->section();
             $section2 = $output->section();
+
             $section1->writeln('Hello');
             $section2->writeln('World!');
             // Output displays "Hello\nWorld!\n"

contributing/code/bc.rst

@@ -72,7 +72,7 @@ backward compatibility promise:
 +-----------------------------------------------+-----------------------------+
 | Type hint against the interface               | Yes                         |
 +-----------------------------------------------+-----------------------------+
-| Call a method                                 | Yes                         |
+| Call a method                                 | Yes [10]_                   |
 +-----------------------------------------------+-----------------------------+
 | **If you implement the interface and...**     | **Then we guarantee BC...** |
 +-----------------------------------------------+-----------------------------+
@@ -114,13 +114,13 @@ covered by our backward compatibility promise:
 +-----------------------------------------------+-----------------------------+
 | Access a public property                      | Yes                         |
 +-----------------------------------------------+-----------------------------+
-| Call a public method                          | Yes                         |
+| Call a public method                          | Yes [10]_                   |
 +-----------------------------------------------+-----------------------------+
 | **If you extend the class and...**            | **Then we guarantee BC...** |
 +-----------------------------------------------+-----------------------------+
 | Access a protected property                   | Yes                         |
 +-----------------------------------------------+-----------------------------+
-| Call a protected method                       | Yes                         |
+| Call a protected method                       | Yes [10]_                   |
 +-----------------------------------------------+-----------------------------+
 | Override a public property                    | Yes                         |
 +-----------------------------------------------+-----------------------------+
@@ -445,4 +445,8 @@ Turn static into non static                         No
 
 .. [9] Allowed for the ``void`` return type.
 
+.. [10] Parameter names are not part of the compatibility promise. Using
+        PHP 8's named arguments feature might break your code when upgrading to
+        newer Symfony versions.
+
 .. _`Semantic Versioning`: https://semver.org/

contributing/code/pull_requests.rst

@@ -124,24 +124,24 @@ Choose the right Branch
 Before working on a PR, you must determine on which branch you need to
 work:
 
-* ``3.4``, if you are fixing a bug for an existing feature or want to make a
+* ``4.4``, if you are fixing a bug for an existing feature or want to make a
   change that falls into the :doc:`list of acceptable changes in patch versions
   </contributing/code/maintenance>` (you may have to choose a higher branch if
   the feature you are fixing was introduced in a later version);
 
 * ``5.x``, if you are adding a new feature.
 
   The only exception is when a new :doc:`major Symfony version </contributing/community/releases>`
-  (4.0, 5.0, etc.) comes out every two years. Because of the
+  (5.0, 6.0, etc.) comes out every two years. Because of the
   :ref:`special development process <major-version-development>` of those versions,
-  you need to use the previous minor version for the features (e.g. use ``3.4``
-  instead of ``4.0``, use ``4.4`` instead of ``5.0``, etc.)
+  you need to use the previous minor version for the features (e.g. use ``4.4``
+  instead of ``5.0``, use ``5.4`` instead of ``6.0``, etc.)
 
 .. note::
 
     All bug fixes merged into maintenance branches are also merged into more
     recent branches on a regular basis. For instance, if you submit a PR
-    for the ``3.4`` branch, the PR will also be applied by the core team on
+    for the ``4.4`` branch, the PR will also be applied by the core team on
     the ``5.x`` branch.
 
 Create a Topic Branch
@@ -154,18 +154,18 @@ topic branch:
 
     $ git checkout -b BRANCH_NAME 5.x
 
-Or, if you want to provide a bug fix for the ``3.4`` branch, first track the remote
-``3.4`` branch locally:
+Or, if you want to provide a bug fix for the ``4.4`` branch, first track the remote
+``4.4`` branch locally:
 
 .. code-block:: terminal
 
-    $ git checkout --track origin/3.4
+    $ git checkout --track origin/4.4
 
-Then create a new branch off the ``3.4`` branch to work on the bug fix:
+Then create a new branch off the ``4.4`` branch to work on the bug fix:
 
 .. code-block:: terminal
 
-    $ git checkout -b BRANCH_NAME 3.4
+    $ git checkout -b BRANCH_NAME 4.4
 
 .. tip::
 
@@ -285,7 +285,7 @@ while to finish your changes):
 
 .. tip::
 
-    Replace ``5.x`` with the branch you selected previously (e.g. ``3.4``)
+    Replace ``5.x`` with the branch you selected previously (e.g. ``4.4``)
     if you are working on a bug fix.
 
 When doing the ``rebase`` command, you might have to fix merge conflicts.
@@ -312,8 +312,8 @@ You can now make a pull request on the ``symfony/symfony`` GitHub repository.
 
 .. tip::
 
-    Take care to point your pull request towards ``symfony:3.4`` if you want
-    the core team to pull a bug fix based on the ``3.4`` branch.
+    Take care to point your pull request towards ``symfony:4.4`` if you want
+    the core team to pull a bug fix based on the ``4.4`` branch.
 
 To ease the core team work, always include the modified components in your
 pull request message, like in:
@@ -403,7 +403,7 @@ Rework your Pull Request
 
 Based on the feedback on the pull request, you might need to rework your
 PR. Before re-submitting the PR, rebase with ``upstream/5.x`` or
-``upstream/3.4``, don't merge; and force the push to the origin:
+``upstream/4.4``, don't merge; and force the push to the origin:
 
 .. code-block:: terminal
 

contributing/community/releases.rst

@@ -7,7 +7,7 @@ release and maintain its different versions.
 Symfony releases follow the `semantic versioning`_ strategy and they are
 published through a *time-based model*:
 
-* A new **Symfony patch version** (e.g. 4.4.9, 5.0.9, 5.1.1) comes out roughly every
+* A new **Symfony patch version** (e.g. 4.4.12, 5.1.9) comes out roughly every
   month. It only contains bug fixes, so you can safely upgrade your applications;
 * A new **Symfony minor version** (e.g. 4.4, 5.1) comes out every *six months*:
   one in *May* and one in *November*. It contains bug fixes and new features, but
@@ -53,7 +53,7 @@ Maintenance
 
 Starting from the Symfony 3.x branch, the number of minor versions is limited to
 five per branch (X.0, X.1, X.2, X.3 and X.4). The last minor version of a branch
-(e.g. 3.4, 4.4, 5.4) is considered a **long-term support version** and the other
+(e.g. 4.4, 5.4) is considered a **long-term support version** and the other
 ones are considered **standard versions**:
 
 =======================  =====================  ================================
@@ -87,17 +87,17 @@ learn more about how deprecations are handled in Symfony.
 .. _major-version-development:
 
 This deprecation policy also requires a custom development process for major
-versions (4.0, 5.0, 6.0, etc.) In those cases, Symfony develops at the same time
-two versions: the new major one (e.g. 4.0) and the latest version of the
-previous branch (e.g. 3.4).
+versions (5.0, 6.0, etc.) In those cases, Symfony develops at the same time
+two versions: the new major one (e.g. 5.0) and the latest version of the
+previous branch (e.g. 4.4).
 
 Both versions have the same new features, but they differ in the deprecated
-features. The oldest version (3.4 in this example) contains all the deprecated
-features whereas the new version (4.0 in this example) removes all of them.
+features. The oldest version (4.4 in this example) contains all the deprecated
+features whereas the new version (5.0 in this example) removes all of them.
 
-This allows you to upgrade your projects to the latest minor version (e.g. 3.4),
+This allows you to upgrade your projects to the latest minor version (e.g. 4.4),
 see all the deprecation messages and fix them. Once you have fixed all those
-deprecations, you can upgrade to the new major version (e.g. 4.0) without
+deprecations, you can upgrade to the new major version (e.g. 5.0) without
 effort, because it contains the same features (the only difference are the
 deprecated features, which your project no longer uses).