Merge branch 'symfony:6.4' into Chris53897-patch-1

Author: Chris53897

_images/components/var_dumper/10-uninitialized.png

@@ -224,11 +224,12 @@ nothing more than a few lines of *glue-code*, so you are not coupling the
 important parts of your application.
 
 .. _best-practice-controller-annotations:
+.. _best-practice-controller-attributes:
 
-Use Attributes or Annotations to Configure Routing, Caching, and Security
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use Attributes to Configure Routing, Caching, and Security
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using attributes or annotations for routing, caching, and security simplifies
+Using attributes for routing, caching, and security simplifies
 configuration. You don't need to browse several files created with different
 formats (YAML, XML, PHP): all the configuration is just where you  require it,
 and it only uses one format.

best_practices.rst

@@ -123,8 +123,8 @@ Event Listeners                                      ``src/EventListener/``
 Configuration (routes, services, etc.)               ``config/``
 Web Assets (CSS, JS, images)                         ``public/``
 Translation files                                    ``translations/``
-Validation (when not using annotations)              ``config/validation/``
-Serialization (when not using annotations)           ``config/serialization/``
+Validation (when not using attributes)               ``config/validation/``
+Serialization (when not using attributes)            ``config/serialization/``
 Templates                                            ``templates/``
 Unit and Functional Tests                            ``tests/``
 ===================================================  ========================================
@@ -163,7 +163,7 @@ If the bundle includes Doctrine ORM entities and/or ODM documents, it's
 recommended to define their mapping using XML files stored in
 ``config/doctrine/``. This allows to override that mapping using the
 :doc:`standard Symfony mechanism to override bundle parts </bundles/override>`.
-This is not possible when using annotations/attributes to define the mapping.
+This is not possible when using attributes to define the mapping.
 
 Tests
 -----

bundles/best_practices.rst

@@ -112,6 +112,28 @@ provides access to the link properties (e.g. ``$link->getMethod()``,
     $link = $crawler->selectLink('Go elsewhere...')->link();
     $client->click($link);
 
+The :method:`Symfony\\Component\\BrowserKit\\AbstractBrowser::click` and
+:method:`Symfony\\Component\\BrowserKit\\AbstractBrowser::clickLink` methods
+can take an optional ``serverParameters`` argument. This
+parameter allows to send additional information like headers when clicking
+on a link::
+
+    use Acme\Client;
+
+    $client = new Client();
+    $client->request('GET', '/product/123');
+
+    // works both with `click()`...
+    $link = $crawler->selectLink('Go elsewhere...')->link();
+    $client->click($link, ['X-Custom-Header' => 'Some data']);
+
+    // ... and `clickLink()`
+    $crawler = $client->clickLink('Go elsewhere...', ['X-Custom-Header' => 'Some data']);
+
+.. versionadded:: 6.4
+
+    The ``serverParameters`` parameter was introduced in Symfony 6.4.
+
 Submitting Forms
 ~~~~~~~~~~~~~~~~
 

components/browser_kit.rst

@@ -30,7 +30,7 @@ an array containing all matches.
 Resource Loaders
 ----------------
 
-For each type of resource (YAML, XML, annotation, etc.) a loader must be
+For each type of resource (YAML, XML, attributes, etc.) a loader must be
 defined. Each loader should implement
 :class:`Symfony\\Component\\Config\\Loader\\LoaderInterface` or extend the
 abstract :class:`Symfony\\Component\\Config\\Loader\\FileLoader` class,

components/config/resources.rst

@@ -243,6 +243,18 @@ Symfony doesn't handle any signal received by the command (not even ``SIGKILL``,
 ``SIGTERM``, etc). This behavior is intended, as it gives you the flexibility to
 handle all signals e.g. to do some tasks before terminating the command.
 
+.. tip::
+
+    If you need to fetch the signal name from its integer value (e.g. for logging),
+    you can use the
+    :method:`Symfony\\Component\\Console\\SignalRegistry\\SignalMap::getSignalName`
+    method.
+
+    .. versionadded:: 6.4
+
+        The :class:`Symfony\\Component\\Console\\SignalRegistry\\SignalMap` class was
+        introduced in Symfony 6.4.
+
 .. deprecated:: 6.3
 
     In Symfony versions previous to 6.3, all signals (except ``SIGUSR1`` and

components/console/events.rst

@@ -238,6 +238,18 @@ Access the attribute value of the first node of the current selection::
 
     $class = $crawler->filterXPath('//body/p')->attr('class');
 
+.. tip::
+
+    You can define the default value to use if the node or attribute is empty
+    by using the second argument of the ``attr()`` method::
+
+        $class = $crawler->filterXPath('//body/p')->attr('class', 'my-default-class');
+
+    .. versionadded:: 6.4
+
+        The possibility to specify a default value to the ``attr()`` method
+        was introduced in Symfony 6.4.
+
 Extract attribute and/or node values from the list of nodes::
 
     $attributes = $crawler

components/dom_crawler.rst

@@ -263,6 +263,13 @@ on the request's information.
        is passed to it. This step is also specific to the  :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerResolver`
        sub-class used by the Symfony Framework.
 
+.. deprecated:: 6.4
+
+    :class:`Symfony\\Component\\DependencyInjection\\ContainerAwareInterface` and
+    :class:`Symfony\\Component\\DependencyInjection\\ContainerAwareTrait` are
+    deprecated since Symfony 6.4. Dependency injection should be used instead to
+    access the service container.
+
 .. _component-http-kernel-kernel-controller:
 
 3) The ``kernel.controller`` Event

components/http_kernel.rst

@@ -179,6 +179,41 @@ You may convert codes between two-letter alpha2 and three-letter alpha3 codes::
 
     $alpha2Code = Countries::getAlpha2Code($alpha3Code);
 
+Numeric Country Codes
+~~~~~~~~~~~~~~~~~~~~~
+
+The `ISO 3166-1 numeric`_ standard defines three-digit country codes to represent
+countries, dependent territories, and special areas of geographical interest.
+
+The main advantage over the ISO 3166-1 alphabetic codes (alpha-2 and alpha-3) is
+that these numeric codes are independent from the writing system. The alphabetic
+codes use the 26-letter English alphabet, which might be unavailable or difficult
+to use for people and systems using non-Latin scripts (e.g. Arabic or Japanese).
+
+The :class:`Symfony\\Component\\Intl\\Countries` class provides access to these
+numeric country codes::
+
+    use Symfony\Component\Intl\Countries;
+
+    \Locale::setDefault('en');
+
+    $numericCodes = Countries::getNumericCodes();
+    // ('alpha2Code' => 'numericCode')
+    // => ['AA' => '958', 'AD' => '020', ...]
+
+    $numericCode = Countries::getNumericCode('FR');
+    // => '250'
+
+    $alpha2 = Countries::getAlpha2FromNumeric('250');
+    // => 'FR'
+
+    $exists = Countries::numericCodeExists('250');
+    // => true
+
+.. versionadded:: 6.4
+
+    The support for numeric country codes was introduced in Symfony 6.4.
+
 Locales
 ~~~~~~~
 
@@ -435,6 +470,7 @@ Learn more
 .. _`Unicode ISO 15924 Registry`: https://www.unicode.org/iso15924/iso15924-codes.html
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 .. _`ISO 3166-1 alpha-3`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
+.. _`ISO 3166-1 numeric`: https://en.wikipedia.org/wiki/ISO_3166-1_numeric
 .. _`UTC/GMT time offsets`: https://en.wikipedia.org/wiki/List_of_UTC_time_offsets
 .. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time
 .. _`ISO 639-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_639-1

components/intl.rst

@@ -470,16 +470,16 @@ avoid stalled locks::
 
 The ``MongoDbStore`` takes the following ``$options`` (depending on the first parameter type):
 
-=============  ================================================================================================
-Option         Description
-=============  ================================================================================================
-gcProbability  Should a TTL Index be created expressed as a probability from 0.0 to 1.0 (Defaults to ``0.001``)
-gcProbablity   Same as ``gcProbability``, see the deprecation note below
-database       The name of the database
-collection     The name of the collection
-uriOptions     Array of URI options for `MongoDBClient::__construct`_
-driverOptions  Array of driver options for `MongoDBClient::__construct`_
-=============  ================================================================================================
+==============  ================================================================================================
+Option          Description
+==============  ================================================================================================
+gcProbability   Should a TTL Index be created expressed as a probability from 0.0 to 1.0 (Defaults to ``0.001``)
+gcProbablity    Same as ``gcProbability``, see the deprecation note below
+database        The name of the database
+collection      The name of the collection
+uriOptions      Array of URI options for `MongoDBClient::__construct`_
+driverOptions   Array of driver options for `MongoDBClient::__construct`_
+=============   ================================================================================================
 
 .. deprecated:: 6.3
 

components/lock.rst

@@ -410,6 +410,40 @@ instead::
     );
     $process->run();
 
+Executing a PHP Child Process with the Same Configuration
+---------------------------------------------------------
+
+.. versionadded:: 6.4
+
+    The ``PhpSubprocess`` helper was introduced in Symfony 6.4.
+
+When you start a PHP process, it uses the default configuration defined in
+your ``php.ini`` file. You can bypass these options with the ``-d`` command line
+option. For example, if ``memory_limit`` is set to ``256M``, you can disable this
+memory limit when running some command like this:
+``php -d memory_limit=-1 bin/console app:my-command``.
+
+However, if you run the command via the Symfony ``Process`` class, PHP will use
+the settings defined in the ``php.ini`` file. You can solve this issue by using
+the :class:`Symfony\\Component\\Process\\PhpSubprocess` class to run the command::
+
+    use Symfony\Component\Process\Process;
+
+    class MyCommand extends Command
+    {
+        protected function execute(InputInterface $input, OutputInterface $output): int
+        {
+            // the memory_limit (and any other config option) of this command is
+            // the one defined in php.ini instead of the new values (optionally)
+            // passed via the '-d' command option
+            $childProcess = new Process(['bin/console', 'cache:pool:prune']);
+
+            // the memory_limit (and any other config option) of this command takes
+            // into account the values (optionally) passed via the '-d' command option
+            $childProcess = new PhpSubprocess(['bin/console', 'cache:pool:prune']);
+        }
+    }
+
 Process Timeout
 ---------------
 

components/process.rst

@@ -289,6 +289,7 @@ for each format:
     $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
 
 .. _component-serializer-attributes-groups-annotations:
+.. _component-serializer-attributes-groups-attributes:
 
 Then, create your groups definition:
 
@@ -436,8 +437,8 @@ Ignoring Attributes
 All attributes are included by default when serializing objects. There are two
 options to ignore some of those attributes.
 
-Option 1: Using ``@Ignore`` Annotation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Option 1: Using ``#[Ignore]`` Attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. configuration-block::
 
@@ -881,6 +882,20 @@ The Serializer component provides several built-in normalizers:
     Also it can denormalize ``uuid`` or ``ulid`` strings to :class:`Symfony\\Component\\Uid\\Uuid`
     or :class:`Symfony\\Component\\Uid\\Ulid`. The format does not matter.
 
+:class:`Symfony\\Component\\Serializer\\Normalizer\\TranslatableNormalizer`
+    This normalizer converts objects that implement
+    :class:`Symfony\\Contracts\\Translation\\TranslatableInterface` into
+    translated strings, using the
+    :method:`Symfony\\Contracts\\Translation\\TranslatableInterface::trans`
+    method. You can define the locale to use to translate the object by
+    setting the ``TranslatableNormalizer::NORMALIZATION_LOCALE_KEY`` serializer
+    context option.
+
+    .. versionadded:: 6.4
+
+        The :class:`Symfony\\Component\\Serializer\\Normalizer\\TranslatableNormalizer`
+        was introduced in Symfony 6.4.
+
 .. note::
 
     You can also create your own Normalizer to use another structure. Read more at
@@ -998,6 +1013,22 @@ context to pass in these options using the key ``json_encode_options`` or
 
     $this->serializer->serialize($data, 'json', ['json_encode_options' => \JSON_PRESERVE_ZERO_FRACTION]);
 
+These are the options available:
+
+===============================  =========================================================================================================== ================================
+Option                           Description                                                                                                 Default
+===============================  ==========================================================================================================  ================================
+``json_decode_associative``      If set to true returns the result as an array, returns a nested ``stdClass`` hierarchy otherwise.           ``false``
+``json_decode_detailed_errors``  If set to true, exceptions thrown on parsing of JSON are more specific. Requires `seld/jsonlint`_ package.  ``false``
+``json_encode_options``          `$flags`_ passed to :phpfunction:`json_decode` function.                                                    ``0``
+``json_decode_options``          `$flags`_ passed to :phpfunction:`json_encode` function.                                                    ``\JSON_PRESERVE_ZERO_FRACTION``
+``json_decode_recursion_depth``  Sets maximum recursion depth.                                                                               ``512``
+===============================  ==========================================================================================================  ================================
+
+.. versionadded:: 6.4
+
+    The support of ``json_decode_detailed_errors`` was introduced in Symfony 6.4.
+
 The ``CsvEncoder``
 ~~~~~~~~~~~~~~~~~~
 
@@ -1827,3 +1858,5 @@ Learn more
 .. _`RFC 4122`: https://tools.ietf.org/html/rfc4122
 .. _`PHP reflection`: https://php.net/manual/en/book.reflection.php
 .. _`data URI`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
+.. _seld/jsonlint: https://github.com/Seldaek/jsonlint
+.. _$flags: https://www.php.net/manual/en/json.constants.php

components/serializer.rst

@@ -572,7 +572,7 @@ commands to learn about all their options):
     # generate 1 ULID with a specific timestamp
     $ php bin/console ulid:generate --time="2021-02-02 14:00:00"
 
-    # generate 2 ULIDs and ouput them in RFC4122 format
+    # generate 2 ULIDs and output them in RFC4122 format
     $ php bin/console ulid:generate --count=2 --format=rfc4122
 
 In addition to generating new UIDs, you can also inspect them with the following

components/uid.rst

@@ -114,6 +114,10 @@ If you use annotations instead of attributes, it's also required to call
         ->addDefaultDoctrineAnnotationReader() // add this only when using annotations
         ->getValidator();
 
+.. deprecated:: 6.4
+
+    Annotations are deprecated since Symfony 6.4, use attributes instead.
+
 To disable the annotation loader after it was enabled, call
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
 

components/validator/resources.rst

@@ -461,6 +461,24 @@ then its dump representation::
 
 .. image:: /_images/components/var_dumper/09-cut.png
 
+.. code-block:: php
+
+    class Foo
+    {
+        // $foo is uninitialized, which is different from being null
+        private int|float $foo;
+        public ?string $baz = null;
+    }
+
+    $var = new Foo();
+    dump($var);
+
+.. image:: /_images/components/var_dumper/10-uninitialized.png
+
+.. versionadded:: 6.4
+
+    Displaying uninitialized variables information was introduced in Symfony 6.4.
+
 .. _var-dumper-advanced:
 
 Advanced Usage