Merge branch 'symfony:5.4' into master

reypm · web-flow · commit e3399dedeee8 · 2022-03-23T07:29:52.000-04:00
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -23,7 +23,7 @@ jobs:
             -   name: "Set-up PHP"
                 uses: shivammathur/setup-php@v2
                 with:
-                    php-version: 8.0
+                    php-version: 8.1
                     coverage: none
                     tools: "composer:v2"
 
@@ -91,7 +91,7 @@ jobs:
           - name: Set-up PHP
             uses: shivammathur/setup-php@v2
             with:
-                php-version: 8.0
+                php-version: 8.1
                 coverage: none
 
           - name: Fetch branch from where the PR started
diff --git a/README.markdown b/README.markdown
@@ -42,4 +42,10 @@ $ composer install
 $ php build.php
 ```
 
-Now you can browse the docs at `_build/output/index.html`
+After generating docs, serve them with the internal PHP server:
+
+```bash
+$ php -S localhost:8000 -t output/
+```
+
+Browse `http://localhost:8000` to read the docs.
diff --git a/_build/build.php b/_build/build.php
@@ -46,6 +46,12 @@
         $result = (new DocBuilder())->build($buildConfig);
 
         if ($result->isSuccessful()) {
+            // fix assets URLs to make them absolute (otherwise, they don't work in subdirectories)
+            foreach (glob($outputDir.'/**/*.html') as $htmlFilePath) {
+                $htmlContents = file_get_contents($htmlFilePath);
+                file_put_contents($htmlFilePath, str_replace('href="assets/', 'href="/assets/', $htmlContents));
+            }
+
             $io->success(sprintf("The Symfony Docs were successfully built at %s", realpath($outputDir)));
         } else {
             $io->error(sprintf("There were some errors while building the docs:\n\n%s\n", $result->getErrorTrace()));
diff --git a/components/filesystem.rst b/components/filesystem.rst
@@ -348,7 +348,7 @@ following rules iteratively until no further processing can be done:
 
 - "." segments are removed;
 - ".." segments are resolved;
-- backslashes ("\") are converted into forward slashes ("/");
+- backslashes ("\\") are converted into forward slashes ("/");
 - root paths ("/" and "C:/") always terminate with a slash;
 - non-root paths never terminate with a slash;
 - schemes (such as "phar://") are kept;
diff --git a/components/runtime.rst b/components/runtime.rst
@@ -53,6 +53,9 @@ the component. This file runs the following logic:
 
 .. caution::
 
+    If you use the Composer ``--no-plugins`` option, the ``autoload_runtime.php``
+    file won't be created.
+
     If you use the Composer ``--no-scripts`` option, make sure your Composer version
     is ``>=2.1.3``; otherwise the ``autoload_runtime.php`` file won't be created.
 
diff --git a/components/string.rst b/components/string.rst
@@ -334,12 +334,11 @@ Methods to Search and Replace
     u('foo')->equalsTo('foo'); // true
 
     // checks if the string content match the given regular expression.
-    // You can pass flags for preg_match() as second argument. If PREG_PATTERN_ORDER
-    // or PREG_SET_ORDER are passed, preg_match_all() will be used.
     u('avatar-73647.png')->match('/avatar-(\d+)\.png/');
-    // result = ['avatar-73647.png', '73647']
-    u('avatar-73647.png')->match('/avatar-(\d+)(-\d+)?\.png/', \PREG_UNMATCHED_AS_NULL);
     // result = ['avatar-73647.png', '73647', null]
+
+    // You can pass flags for preg_match() as second argument. If PREG_PATTERN_ORDER
+    // or PREG_SET_ORDER are passed, preg_match_all() will be used.
     u('206-555-0100 and 800-555-1212')->match('/\d{3}-\d{3}-\d{4}/', \PREG_PATTERN_ORDER);
     // result = [['206-555-0100', '800-555-1212']]
 
diff --git a/configuration.rst b/configuration.rst
@@ -674,6 +674,11 @@ In addition to your own env vars, this ``.env`` file also contains the env vars
 defined by the third-party packages installed in your application (they are
 added automatically by :ref:`Symfony Flex <symfony-flex>` when installing packages).
 
+.. tip::
+
+    Since the ``.env`` file is read and parsed on every request, you don't need to
+    clear the Symfony cache or restart the PHP container if you're using Docker.
+
 .env File Syntax
 ................
 
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
@@ -206,8 +206,12 @@ Naming Conventions
 * Use `snake_case`_ for configuration parameters and Twig template variables
   (e.g. ``framework.csrf_protection``, ``http_status_code``);
 
-* Use namespaces for all PHP classes and `UpperCamelCase`_ for their names (e.g.
-  ``ConsoleLogger``);
+* Use `SCREAMING_SNAKE_CASE`_ for constants (e.g. ``InputArgument::IS_ARRAY``);
+
+* Use `UpperCamelCase`_ for enumeration cases (e.g. ``InputArgumentMode::IsArray``);
+
+* Use namespaces for all PHP classes, interfaces, traits and enums and
+  `UpperCamelCase`_ for their names (e.g. ``ConsoleLogger``);
 
 * Prefix all abstract classes with ``Abstract`` except PHPUnit ``*TestCase``.
   Please note some early Symfony classes do not follow this convention and
@@ -218,6 +222,9 @@ Naming Conventions
 
 * Suffix traits with ``Trait``;
 
+* Don't use a dedicated suffix for classes or enumerations (e.g. like ``Class``
+  or ``Enum``), except for the cases listed below.
+
 * Suffix exceptions with ``Exception``;
 
 * Prefix PHP attributes with ``As`` where applicable (e.g. ``#[AsCommand]``
diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst
@@ -20,12 +20,3 @@ documentation:
 :doc:`License </contributing/documentation/license>`
     Explains the details of the Creative Commons BY-SA 3.0 license used for the
     Symfony Documentation.
-
-.. toctree::
-    :hidden:
-
-    format
-    license
-    overview
-    standards
-    translations
diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst
@@ -49,14 +49,10 @@ In addition, some components and official bundles provide other value resolvers:
 
 :class:`Symfony\\Component\\Security\\Http\\Controller\\UserValueResolver`
     Injects the object that represents the current logged in user if type-hinted
-    with ``UserInterface``. Default value can be set to ``null`` in case
-    the controller can be accessed by anonymous users. It requires installing
-    the :doc:`SecurityBundle </security>`.
-
-``Psr7ServerRequestResolver``
-    Injects a `PSR-7`_ compliant version of the current request if type-hinted
-    with ``RequestInterface``, ``MessageInterface`` or ``ServerRequestInterface``.
-    It requires installing the `SensioFrameworkExtraBundle`_.
+    with ``UserInterface``. You can also type-hint your own ``User`` class but you
+    must then add the ``#[CurrentUser]`` attribute to the argument. Default value
+    can be set to ``null`` in case  the controller can be accessed by anonymous
+    users. It requires installing the :doc:`SecurityBundle </security>`.
 
 Adding a Custom Value Resolver
 ------------------------------
@@ -247,6 +243,13 @@ Otherwise, set a priority lower than ``100`` to make sure the argument resolver
 is not triggered when the ``Request`` attribute is present (for example, when
 passing the user along sub-requests).
 
+To ensure your resolvers are added in the right position you can run the following
+command to see which argument resolvers are present and in which order they run.
+
+.. code-block:: terminal
+    
+    $ php bin/console debug:container debug.argument_resolver.inner --show-arguments
+
 .. tip::
 
     As you can see in the ``UserValueResolver::supports()`` method, the user
@@ -260,5 +263,3 @@ passing the user along sub-requests).
 
 .. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`yield`: https://www.php.net/manual/en/language.generators.syntax.php
-.. _`PSR-7`: https://www.php-fig.org/psr/psr-7/
-.. _`SensioFrameworkExtraBundle`: https://github.com/sensiolabs/SensioFrameworkExtraBundle
diff --git a/controller/upload_file.rst b/controller/upload_file.rst
@@ -199,7 +199,7 @@ There are some important things to consider in the code of the above controller:
 #. A well-known security best practice is to never trust the input provided by
    users. This also applies to the files uploaded by your visitors. The ``UploadedFile``
    class provides methods to get the original file extension
-   (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getExtension`),
+   (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientOriginalExtension`),
    the original file size (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getSize`)
    and the original file name (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientOriginalName`).
    However, they are considered *not safe* because a malicious user could tamper
diff --git a/doctrine.rst b/doctrine.rst
@@ -414,13 +414,13 @@ Take a look at the previous example in more detail:
   *entity manager* object, which is the most important object in Doctrine. It's
   responsible for saving objects to, and fetching objects from, the database.
 
-* **lines 20-23** In this section, you instantiate and work with the ``$product``
+* **lines 18-21** In this section, you instantiate and work with the ``$product``
   object like any other normal PHP object.
 
-* **line 26** The ``persist($product)`` call tells Doctrine to "manage" the
+* **line 24** The ``persist($product)`` call tells Doctrine to "manage" the
   ``$product`` object. This does **not** cause a query to be made to the database.
 
-* **line 29** When the ``flush()`` method is called, Doctrine looks through
+* **line 27** When the ``flush()`` method is called, Doctrine looks through
   all of the objects that it's managing to see if they need to be persisted
   to the database. In this example, the ``$product`` object's data doesn't
   exist in the database, so the entity manager executes an ``INSERT`` query,
diff --git a/doctrine/reverse_engineering.rst b/doctrine/reverse_engineering.rst
@@ -103,7 +103,7 @@ run:
     $ php bin/console make:entity --regenerate App
 
     // generates getter/setter methods for one specific Entity
-    $ php bin/console make:entity --regenerate App\Entity\Country
+    $ php bin/console make:entity --regenerate "App\Entity\Country"
 
 .. note::
 
diff --git a/form/unit_testing.rst b/form/unit_testing.rst
@@ -134,8 +134,8 @@ variable exists and will be available in your form themes::
     the ``KernelTestCase`` instead and use the ``form.factory`` service to
     create the form.
 
-Testings Types Registered as Services
--------------------------------------
+Testing Types Registered as Services
+------------------------------------
 
 Your form may be used as a service, as it depends on other services (e.g. the
 Doctrine entity manager). In these cases, using the above code won't work, as
diff --git a/http_cache.rst b/http_cache.rst
@@ -104,7 +104,7 @@ The kernel will immediately act as a reverse proxy: caching responses
 from your application and returning them to the client.
 
 The proxy has a sensible default configuration, but it can be
-finely tuned via `a set of options <configuration-framework-http_cache>`.
+finely tuned via :ref:`a set of options <configuration-framework-http_cache>`.
 
 When in :ref:`debug mode <debug-mode>`, Symfony automatically adds an
 ``X-Symfony-Cache`` header to the response. You can also use the ``trace_level``
diff --git a/mailer.rst b/mailer.rst
@@ -342,6 +342,7 @@ and create an :class:`Symfony\\Component\\Mime\\Email` object::
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Mailer\MailerInterface;
     use Symfony\Component\Mime\Email;
+    use Symfony\Component\Routing\Annotation\Route;
 
     class MailerController extends AbstractController
     {
diff --git a/messenger.rst b/messenger.rst
@@ -1369,7 +1369,7 @@ in the table.
 Option                   Description                                 Default
 =======================  ==========================================  ======================
 use_notify               Whether to use LISTEN/NOTIFY.               true
-check_delayed_interval   The interval to check for delayed           1000
+check_delayed_interval   The interval to check for delayed           60000
                          messages, in milliseconds.
                          Set to 0 to disable checks.
 get_notify_timeout       The length of time to wait for a            0
diff --git a/profiler.rst b/profiler.rst
@@ -2,8 +2,12 @@ Profiler
 ========
 
 The profiler is a powerful **development tool** that gives detailed information
-about the execution of any request. **Never** enable the profiler in production
-environments as it will lead to major security vulnerabilities in your project.
+about the execution of any request. 
+
+.. caution::
+
+    **Never** enable the profiler in production environments
+    as it will lead to major security vulnerabilities in your project.
 
 Installation
 ------------
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -593,6 +593,41 @@ enabled
 This option can be used to disable CSRF protection on *all* forms. But you
 can also :ref:`disable CSRF protection on individual forms <form-csrf-customization>`.
 
+.. configuration-block::
+
+    .. code-block:: yaml
+    
+        # config/packages/framework.yaml
+        framework:
+            # ...
+            csrf_protection: true
+            
+    .. code-block:: xml
+    
+        <!-- config/packages/framework.xml -->
+        <?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:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            <framework:config>
+                <framework:csrf-protection enabled="true"/>
+            </framework:config>
+        </container>
+        
+    .. code-block:: php
+    
+        // config/packages/framework.php
+        use Symfony\Config\FrameworkConfig;
+        return static function (FrameworkConfig $framework) {
+            $framework->csrfProtection()
+                ->enabled(true)
+            ;
+        };
+
 If you're using forms, but want to avoid starting your session (e.g. using
 forms in an API-only website), ``csrf_protection`` will need to be set to
 ``false``.
@@ -3476,7 +3511,7 @@ a normal workflow or a state machine. Read :doc:`this article </workflow/workflo
 to know their differences.
 
 exceptions
-""""""""""
+~~~~~~~~~~
 
 **type**: ``array``
 
diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst
@@ -268,6 +268,14 @@ URL and process the submitted login credentials.
 Be sure that this URL is covered by your main firewall (i.e. don't create
 a separate firewall just for ``check_path`` URL).
 
+failure_path
+............
+
+**type**: ``string`` **default**: ``/login``
+
+This is the route or path that the user is redirected to after a failed login attempt.
+It can be a relative/absolute URL or a Symfony route name.
+
 use_forward
 ...........
 
diff --git a/reference/constraints/All.rst b/reference/constraints/All.rst
@@ -43,7 +43,7 @@ entry in that array:
 
         use Symfony\Component\Validator\Constraints as Assert;
 
-        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        // IMPORTANT: nested attributes require PHP 8.1 or higher
         class User
         {
             #[Assert\All([
diff --git a/reference/forms/types/enum.rst b/reference/forms/types/enum.rst
@@ -9,7 +9,7 @@ EnumType Field
    The ``EnumType`` form field was introduced in Symfony 5.4.
 
 A multi-purpose field used to allow the user to "choose" one or more options
-defined in a `PHP enumeration`_. It extends the :doc:`ChoiceType </reference/forms/types/enum>`
+defined in a `PHP enumeration`_. It extends the :doc:`ChoiceType </reference/forms/types/choice>`
 field and defines the same options.
 
 +---------------------------+----------------------------------------------------------------------+
diff --git a/reference/forms/types/options/choice_loader.rst.inc b/reference/forms/types/options/choice_loader.rst.inc
@@ -42,9 +42,9 @@ better performance::
 
     class ConstantsType extends AbstractType
     {
-        public static function getExtendedTypes(): iterable
+        public function getParent(): string
         {
-            return [ChoiceType::class];
+            return ChoiceType::class;
         }
 
         public function configureOptions(OptionsResolver $resolver)
diff --git a/security.rst b/security.rst
@@ -28,7 +28,7 @@ creates a ``security.yaml`` configuration file for you:
     # config/packages/security.yaml
     security:
         enable_authenticator_manager: true
-        # https://symfony.com/doc/current/security.html#c-hashing-passwords
+        # https://symfony.com/doc/current/security.html#registering-the-user-hashing-passwords
         password_hashers:
             Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'
         # https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
diff --git a/security/expressions.rst b/security/expressions.rst
@@ -24,7 +24,7 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
         public function index(): Response
         {
             $this->denyAccessUnlessGranted(new Expression(
-                '"ROLE_ADMIN" in role_names or (not is_anonymous() and user.isSuperAdmin())'
+                '"ROLE_ADMIN" in role_names or (is_authenticated() and user.isSuperAdmin())'
             ));
 
             // ...
@@ -78,6 +78,10 @@ Additionally, you have access to a number of functions inside the expression:
     equivalent to using the :ref:`isGranted() method <security-isgranted>`
     from the security service.
 
+.. deprecated:: 5.4
+
+   The ``is_anonymous()`` function is deprecated since Symfony 5.4.
+
 .. sidebar:: ``is_remember_me()`` is different than checking ``IS_AUTHENTICATED_REMEMBERED``
 
     The ``is_remember_me()`` and ``is_fully_authenticated()`` functions are *similar*
diff --git a/security/impersonating_user.rst b/security/impersonating_user.rst
diff --git a/service_container.rst b/service_container.rst
diff --git a/service_container/autowiring.rst b/service_container/autowiring.rst
diff --git a/service_container/configurators.rst b/service_container/configurators.rst
diff --git a/session.rst b/session.rst
diff --git a/testing.rst b/testing.rst
