Merge branch '7.4' into mailtrap-sandbox7.4

KiloSierraCharlie · web-flow · commit 2b378e22e11f · 2025-08-19T18:21:12.000+01:00
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <p align="center"><a href="https://symfony.com" target="_blank">
-  <img src="https://symfony.com/logos/symfony_black_02.svg">
+    <img src="https://symfony.com/logos/symfony_dynamic_01.svg" alt="Symfony Logo">
 </a></p>
 
 <h3 align="center">
diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst
@@ -188,7 +188,7 @@ the ``tests/`` directory. Tests should follow the following principles:
 .. note::
 
     A test suite must not contain ``AllTests.php`` scripts, but must rely on the
-    existence of a ``phpunit.xml.dist`` file.
+    existence of a ``phpunit.dist.xml`` file.
 
 Continuous Integration
 ----------------------
diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst
@@ -9,7 +9,7 @@ Redis Cache Adapter
     article if you are using it in a Symfony application.
 
 This adapter stores the values in-memory using one (or more) `Redis server`_
-of `Valkey`_ server instances.
+or `Valkey`_ server instances.
 
 Unlike the :doc:`APCu adapter </components/cache/adapters/apcu_adapter>`, and similarly to the
 :doc:`Memcached adapter </components/cache/adapters/memcached_adapter>`, it is not limited to the current server's
diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst
@@ -285,6 +285,7 @@ Make final                                                                No
 Move to parent class                                                      Yes
 :ref:`Add argument without a default value <add-argument-public-method>`  No
 :ref:`Add argument with a default value <add-argument-public-method>`     No              :ref:`[7] <note-7>` :ref:`[8] <note-8>`
+Rename argument                                                           Yes             :ref:`[10] <note-10>`
 Remove argument                                                           No              :ref:`[3] <note-3>`
 Add default value to an argument                                          No              :ref:`[7] <note-7>` :ref:`[8] <note-8>`
 Remove default value of an argument                                       No
@@ -304,6 +305,7 @@ Make public                                                               No
 Move to parent class                                                      Yes
 :ref:`Add argument without a default value <add-argument-public-method>`  No
 :ref:`Add argument with a default value <add-argument-public-method>`     No              :ref:`[7] <note-7>` :ref:`[8] <note-8>`
+Rename argument                                                           Yes             :ref:`[10] <note-10>`
 Remove argument                                                           No              :ref:`[3] <note-3>`
 Add default value to an argument                                          No              :ref:`[7] <note-7>` :ref:`[8] <note-8>`
 Remove default value of an argument                                       No              :ref:`[7] <note-7>`
@@ -320,6 +322,7 @@ Change name                                                               Yes
 Make public or protected                                                  Yes
 Add argument without a default value                                      Yes
 Add argument with a default value                                         Yes
+Rename argument                                                           Yes
 Remove argument                                                           Yes
 Add default value to an argument                                          Yes
 Remove default value of an argument                                       Yes
diff --git a/create_framework/unit_testing.rst b/create_framework/unit_testing.rst
@@ -14,7 +14,7 @@ using `PHPUnit`_. At first, install PHPUnit as a development dependency:
 
     $ composer require --dev phpunit/phpunit:^11.0
 
-Then, create a PHPUnit configuration file in ``example.com/phpunit.xml.dist``:
+Then, create a PHPUnit configuration file in ``example.com/phpunit.dist.xml``:
 
 .. code-block:: xml
 
diff --git a/mailer.rst b/mailer.rst
diff --git a/routing.rst b/routing.rst
@@ -279,10 +279,10 @@ given value:
     .. code-block:: yaml
 
         # config/routes.yaml
-        tools:
-            path:       /tools
-            controller: App\Controller\DefaultController::developerTools
-            env:        dev
+        when@dev:
+            tools:
+                path: /tools
+                controller: App\Controller\DefaultController::developerTools
 
     .. code-block:: xml
 
@@ -293,9 +293,9 @@ given value:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="tools" path="/tools" controller="App\Controller\DefaultController::developerTools">
-                <env>dev</env>
-            </route>
+            <when env="dev">
+                <route id="tools" path="/tools" controller="App\Controller\DefaultController::developerTools"/>
+            </when>
         </routes>
 
     .. code-block:: php
@@ -305,10 +305,11 @@ given value:
         use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
         return function (RoutingConfigurator $routes): void {
-            $routes->add('tools', '/tools')
-                ->controller([DefaultController::class, 'developerTools'])
-                ->env('dev')
-            ;
+            if('dev' === $routes->env()) {
+                $routes->add('tools', '/tools')
+                    ->controller([DefaultController::class, 'developerTools'])
+                ;
+            }
         };
 
 .. _routing-matching-expressions:
diff --git a/serializer.rst b/serializer.rst
@@ -1476,10 +1476,14 @@ normalizers (in order of priority):
     to read and write in the object. This allows it to access properties
     directly or using getters, setters, hassers, issers, canners, adders and
     removers. Names are generated by removing the ``get``, ``set``,
-    ``has``, ``is``, ``add`` or ``remove`` prefix from the method name and
+    ``has``, ``is``, ``can``, ``add`` or ``remove`` prefix from the method name and
     transforming the first letter to lowercase (e.g. ``getFirstName()`` ->
     ``firstName``).
 
+    .. versionadded:: 7.4
+
+        Support for the ``can`` prefix was introduced in Symfony 7.4.
+
     During denormalization, it supports using the constructor as well as
     the discovered methods.
 
diff --git a/serializer/encoders.rst b/serializer/encoders.rst
@@ -205,6 +205,10 @@ These are the options available on the :ref:`serializer context <serializer-cont
 ``cdata_wrapping_pattern`` (default: ``/[<>&]/``)
     A regular expression pattern to determine if a value should be wrapped
     in a CDATA section.
+``cdata_wrapping_name_pattern`` (default: ``false``)
+    A regular expression pattern that defines the names of fields whose values
+    should always be wrapped in a CDATA section, even if their contents don't
+    require it. Example: ``'/(firstname|lastname)/'``
 ``ignore_empty_attributes`` (default: ``false``)
     If set to true, ignores all attributes with empty values in the generated XML
 
@@ -216,6 +220,10 @@ These are the options available on the :ref:`serializer context <serializer-cont
 
     The ``ignore_empty_attributes`` option was introduced in Symfony 7.3.
 
+.. versionadded:: 7.4
+
+    The ``cdata_wrapping_name_pattern`` option was introduced in Symfony 7.4.
+
 Example with a custom ``context``::
 
     use Symfony\Component\Serializer\Encoder\XmlEncoder;
diff --git a/serializer/streaming_json.rst b/serializer/streaming_json.rst
@@ -541,6 +541,16 @@ When callables are not enough, you can use a service implementing the
     The ``getStreamValueType()`` method must return the value's type as it will
     appear in the JSON stream.
 
+.. tip::
+
+    The ``$options`` argument of the ``transform()`` method includes a special
+    option called ``_current_object`` which gives access to the object holding
+    the current property (or ``null`` if there's none).
+
+    .. versionadded:: 7.4
+
+        The ``_current_object`` option was introduced in Symfony 7.4.
+
 To use this transformer in a class, configure the ``#[ValueTransformer]`` attribute::
 
     // src/Dto/Dog.php
diff --git a/setup/symfony_cli.rst b/setup/symfony_cli.rst
@@ -155,7 +155,7 @@ Enabling PHP-FPM
     PHP-FPM must be installed locally for the Symfony server to utilize.
 
 When the server starts, it checks for ``web/index_dev.php``, ``web/index.php``,
-``public/app_dev.php``, ``public/app.php`` in that order. If one is found, the
+``public/app_dev.php``, ``public/app.php``, ``public/index.php`` in that order. If one is found, the
 server will automatically start with PHP-FPM enabled. Otherwise the server will
 start without PHP-FPM and will show a ``Page not found`` page when trying to
 access a ``.php`` file in the browser.
diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst
@@ -114,7 +114,7 @@ done!
 
     .. code-block:: xml
 
-        <!-- phpunit.xml.dist -->
+        <!-- phpunit.dist.xml -->
         <phpunit>
             <!-- ... -->
 
diff --git a/testing.rst b/testing.rst
@@ -55,16 +55,16 @@ This command automatically runs your application tests. Each test is a
 PHP class ending with "Test" (e.g. ``BlogControllerTest``) that lives in
 the ``tests/`` directory of your application.
 
-PHPUnit is configured by the ``phpunit.xml.dist`` file in the root of your
-application. The default configuration provided by Symfony Flex will be
-enough in most cases. Read the `PHPUnit documentation`_ to discover all
-possible configuration options (e.g. to enable code coverage or to split
-your test into multiple "test suites").
+PHPUnit is configured by the ``phpunit.dist.xml`` file in the root of your
+application (in PHPUnit versions older than 10, the file is named ``phpunit.xml.dist``).
+The default configuration provided by Symfony Flex will be enough in most cases.
+Read the `PHPUnit documentation`_ to discover all possible configuration options
+(e.g. to enable code coverage or to split your test into multiple "test suites").
 
 .. note::
 
     :ref:`Symfony Flex <symfony-flex>` automatically creates
-    ``phpunit.xml.dist`` and ``tests/bootstrap.php``. If these files are
+    ``phpunit.dist.xml`` and ``tests/bootstrap.php``. If these files are
     missing, you can try running the recipe again using
     ``composer recipes:install phpunit/phpunit --force -v``.
 
@@ -81,7 +81,7 @@ By convention, the ``tests/`` directory should replicate the directory
 of your application for unit tests. So, if you're testing a class in the
 ``src/Form/`` directory, put the test in the ``tests/Form/`` directory.
 Autoloading is automatically enabled via the ``vendor/autoload.php`` file
-(as configured by default in the ``phpunit.xml.dist`` file).
+(as configured by default in the ``phpunit.dist.xml`` file).
 
 You can run tests using the ``bin/phpunit`` command:
 
@@ -386,11 +386,14 @@ Now, enable it as a PHPUnit extension:
 
 .. code-block:: xml
 
-    <!-- phpunit.xml.dist -->
+    <!-- phpunit.dist.xml -->
     <phpunit>
         <!-- ... -->
 
         <extensions>
+            <!-- use this with PHPUnit 10 or newer -->
+            <bootstrap class="DAMA\DoctrineTestBundle\PHPUnit\PHPUnitExtension"/>
+            <!-- use this with legacy PHPUnit versions older than 10 -->
             <extension class="DAMA\DoctrineTestBundle\PHPUnit\PHPUnitExtension"/>
         </extensions>
     </phpunit>
diff --git a/testing/bootstrap.rst b/testing/bootstrap.rst
@@ -35,11 +35,11 @@ You can modify this file to add custom logic:
 .. note::
 
     If you don't use Symfony Flex, make sure this file is configured as
-    bootstrap file in your ``phpunit.xml.dist`` file:
+    bootstrap file in your ``phpunit.dist.xml`` file:
 
     .. code-block:: xml
 
-        <!-- phpunit.xml.dist -->
+        <!-- phpunit.dist.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <phpunit
             bootstrap="tests/bootstrap.php"
diff --git a/testing/end_to_end.rst b/testing/end_to_end.rst
@@ -76,12 +76,16 @@ When using the extension in conjunction with the ``PANTHER_ERROR_SCREENSHOT_DIR`
 environment variable, tests using the Panther client that fail or error (after the
 client is created) will automatically get a screenshot taken to help debugging.
 
-To register the Panther extension, add the following lines to ``phpunit.xml.dist``:
+To register the Panther extension, add the following lines to ``phpunit.dist.xml``
+(in legacy PHPUnit versions older than 10, the file is named ``phpunit.xml.dist``):
 
 .. code-block:: xml
 
-    <!-- phpunit.xml.dist -->
+    <!-- phpunit.dist.xml -->
     <extensions>
+        <!-- use this with PHPUnit 10 or newer -->
+        <bootstrap class="Symfony\Component\Panther\ServerExtension"/>
+        <!-- use this with legacy PHPUnit versions older than 10 -->
         <extension class="Symfony\Component\Panther\ServerExtension"/>
     </extensions>
 
@@ -868,12 +872,12 @@ Another option is to create a file called ``tests/router.php`` and add the follo
 
     require $script;
 
-Then declare it as a router for Panther server in ``phpunit.xml.dist`` using the
+Then declare it as a router for Panther server in ``phpunit.dist.xml`` using the
 ``PANTHER_WEB_SERVER_ROUTER`` environment variable:
 
 .. code-block:: xml
 
-    <!-- phpunit.xml.dist -->
+    <!-- phpunit.dist.xml -->
     <phpunit>
         <!-- ... -->
         <php>
diff --git a/translation.rst b/translation.rst
@@ -52,6 +52,12 @@ First, run this command to install the translator before using it:
 
     $ composer require symfony/translation
 
+Symfony includes several internationalization polyfills (``symfony/polyfill-intl-icu``,
+``symfony/polyfill-intl-messageformatter``, etc.) that allow you to use translation
+features even without the `PHP intl extension`_. However, these polyfills only
+support English translations, so you must install the PHP ``intl`` extension
+when translating into other languages.
+
 .. _translation-configuration:
 
 Configuration
@@ -1694,6 +1700,7 @@ Learn more
 .. _`ICU MessageFormat`: https://unicode-org.github.io/icu/userguide/format_parse/messages/
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+.. _`PHP intl extension`: https://php.net/book.intl
 .. _`Translatable Extension`: https://github.com/doctrine-extensions/DoctrineExtensions/blob/main/doc/translatable.md
 .. _`Custom Language Name setting`: https://docs.lokalise.com/en/articles/1400492-uploading-files#custom-language-codes
 .. _`ICU resource bundle`: https://github.com/unicode-org/icu-docs/blob/main/design/bnf_rb.txt
