Merge branch '6.4' into 7.0

* 6.4:
  minor
  [CS] Fix more nullable types
  [Testing] Update nullable types
  Reword
  Refactor Request object documentation and redefine method logic

Author: OskarStark

components/expression_language.rst

@@ -385,7 +385,7 @@ or by using the second argument of the constructor::
 
         class ExpressionLanguage extends BaseExpressionLanguage
         {
-            public function __construct(CacheItemPoolInterface $cache = null, array $providers = [])
+            public function __construct(?CacheItemPoolInterface $cache = null, array $providers = [])
             {
                 // prepends the default provider to let users override it
                 array_unshift($providers, new StringExpressionLanguageProvider());

components/serializer.rst

@@ -118,7 +118,7 @@ exists in your project::
             $this->sportsperson = $sportsperson;
         }
 
-        public function setCreatedAt(\DateTimeInterface $createdAt = null): void
+        public function setCreatedAt(?\DateTimeInterface $createdAt = null): void
         {
             $this->createdAt = $createdAt;
         }
@@ -723,7 +723,7 @@ When serializing, you can set a callback to format a specific object property::
     $encoder = new JsonEncoder();
 
     // all callback parameters are optional (you can omit the ones you don't use)
-    $dateCallback = function (object $innerObject, object $outerObject, string $attributeName, string $format = null, array $context = []): string {
+    $dateCallback = function (object $innerObject, object $outerObject, string $attributeName, ?string $format = null, array $context = []): string {
         return $innerObject instanceof \DateTime ? $innerObject->format(\DateTime::ISO8601) : '';
     };
 
@@ -1574,7 +1574,7 @@ having unique identifiers::
     $classMetadataFactory = new ClassMetadataFactory(new AttributeLoader());
 
     // all callback parameters are optional (you can omit the ones you don't use)
-    $maxDepthHandler = function (object $innerObject, object $outerObject, string $attributeName, string $format = null, array $context = []): string {
+    $maxDepthHandler = function (object $innerObject, object $outerObject, string $attributeName, ?string $format = null, array $context = []): string {
         return '/foos/'.$innerObject->id;
     };
 

controller/error_pages.rst

@@ -216,7 +216,7 @@ contents, create a new Normalizer that supports the ``FlattenException`` input::
 
     class MyCustomProblemNormalizer implements NormalizerInterface
     {
-        public function normalize($exception, string $format = null, array $context = []): array
+        public function normalize($exception, ?string $format = null, array $context = []): array
         {
             return [
                 'content' => 'This is my custom problem normalizer.',
@@ -227,7 +227,7 @@ contents, create a new Normalizer that supports the ``FlattenException`` input::
             ];
         }
 
-        public function supportsNormalization($data, string $format = null, array $context = []): bool
+        public function supportsNormalization($data, ?string $format = null, array $context = []): bool
         {
             return $data instanceof FlattenException;
         }

form/dynamic_form_modification.rst

@@ -455,7 +455,7 @@ The type would now look like::
                 ])
             ;
 
-            $formModifier = function (FormInterface $form, Sport $sport = null): void {
+            $formModifier = function (FormInterface $form, ?Sport $sport = null): void {
                 $positions = null === $sport ? [] : $sport->getAvailablePositions();
 
                 $form->add('position', EntityType::class, [
@@ -487,7 +487,7 @@ The type would now look like::
                     $formModifier($event->getForm()->getParent(), $sport);
                 }
             );
-            
+
             // by default, action does not appear in the <form> tag
             // you can set this value by passing the controller route
             $builder->setAction($options['action']);

http_client.rst

@@ -1772,7 +1772,7 @@ If you want to extend the behavior of a base HTTP client, you can use
     class MyExtendedHttpClient implements HttpClientInterface
     {
         public function __construct(
-            private HttpClientInterface $decoratedClient = null
+            private ?HttpClientInterface $decoratedClient = null
         ) {
             $this->decoratedClient ??= HttpClient::create();
         }
@@ -1788,7 +1788,7 @@ If you want to extend the behavior of a base HTTP client, you can use
             return $response;
         }
 
-        public function stream($responses, float $timeout = null): ResponseStreamInterface
+        public function stream($responses, ?float $timeout = null): ResponseStreamInterface
         {
             return $this->decoratedClient->stream($responses, $timeout);
         }

messenger.rst

@@ -2538,7 +2538,7 @@ provided in order to ease the declaration of these special handlers::
     {
         use BatchHandlerTrait;
 
-        public function __invoke(MyMessage $message, Acknowledger $ack = null): mixed
+        public function __invoke(MyMessage $message, ?Acknowledger $ack = null): mixed
         {
             return $this->handle($message, $ack);
         }

messenger/custom-transport.rst

@@ -51,7 +51,7 @@ Here is a simplified example of a database transport::
          */
         public function __construct(
             private FakeDatabase $db,
-            SerializerInterface $serializer = null,
+            ?SerializerInterface $serializer = null,
         ) {
             $this->serializer = $serializer ?? new PhpSerializer();
         }

notifier.rst

@@ -770,7 +770,7 @@ and its ``asChatMessage()`` method::
         ) {
         }
 
-        public function asChatMessage(RecipientInterface $recipient, string $transport = null): ?ChatMessage
+        public function asChatMessage(RecipientInterface $recipient, ?string $transport = null): ?ChatMessage
         {
             // Add a custom subject and emoji if the message is sent to Slack
             if ('slack' === $transport) {

profiler.rst

@@ -281,7 +281,7 @@ request::
 
     class RequestCollector extends AbstractDataCollector
     {
-        public function collect(Request $request, Response $response, \Throwable $exception = null): void
+        public function collect(Request $request, Response $response, ?\Throwable $exception = null): void
         {
             $this->data = [
                 'method' => $request->getMethod(),

reference/constraints/File.rst

@@ -40,7 +40,7 @@ type. The ``Author`` class might look as follows::
     {
         protected File $bioFile;
 
-        public function setBioFile(File $file = null): void
+        public function setBioFile(?File $file = null): void
         {
             $this->bioFile = $file;
         }

reference/constraints/Image.rst

@@ -35,7 +35,7 @@ would be a ``file`` type. The ``Author`` class might look as follows::
     {
         protected File $headshot;
 
-        public function setHeadshot(File $file = null): void
+        public function setHeadshot(?File $file = null): void
         {
             $this->headshot = $file;
         }

reference/forms/types/collection.rst

@@ -160,7 +160,7 @@ the value is removed from the collection. For example::
 
     $builder->add('users', CollectionType::class, [
         // ...
-        'delete_empty' => function (User $user = null): bool {
+        'delete_empty' => function (?User $user = null): bool {
             return null === $user || empty($user->getFirstName());
         },
     ]);

routing/custom_route_loader.rst

@@ -271,7 +271,7 @@ you do. The resource name itself is not actually used in the example::
     {
         private bool $isLoaded = false;
 
-        public function load($resource, string $type = null): RouteCollection
+        public function load($resource, ?string $type = null): RouteCollection
         {
             if (true === $this->isLoaded) {
                 throw new \RuntimeException('Do not add the "extra" loader twice');
@@ -298,7 +298,7 @@ you do. The resource name itself is not actually used in the example::
             return $routes;
         }
 
-        public function supports($resource, string $type = null): bool
+        public function supports($resource, ?string $type = null): bool
         {
             return 'extra' === $type;
         }
@@ -443,7 +443,7 @@ configuration file - you can call the
 
     class AdvancedLoader extends Loader
     {
-        public function load($resource, string $type = null): RouteCollection
+        public function load($resource, ?string $type = null): RouteCollection
         {
             $routes = new RouteCollection();
 
@@ -457,7 +457,7 @@ configuration file - you can call the
             return $routes;
         }
 
-        public function supports($resource, string $type = null): bool
+        public function supports($resource, ?string $type = null): bool
         {
             return 'advanced_extra' === $type;
         }

security/access_denied_handler.rst

@@ -38,7 +38,7 @@ unauthenticated user tries to access a protected resource::
         ) {
         }
 
-        public function start(Request $request, AuthenticationException $authException = null): RedirectResponse
+        public function start(Request $request, ?AuthenticationException $authException = null): RedirectResponse
         {
             // add a custom flash message and redirect to the login page
             $request->getSession()->getFlashBag()->add('note', 'You have to login in order to access this page.');

security/login_link.rst

@@ -283,7 +283,7 @@ This will send an email like this to the user:
 
         class CustomLoginLinkNotification extends LoginLinkNotification
         {
-            public function asEmailMessage(EmailRecipientInterface $recipient, string $transport = null): ?EmailMessage
+            public function asEmailMessage(EmailRecipientInterface $recipient, ?string $transport = null): ?EmailMessage
             {
                 $emailMessage = parent::asEmailMessage($recipient, $transport);
 

serializer/custom_normalizer.rst

@@ -35,7 +35,7 @@ normalization process::
         ) {
         }
 
-        public function normalize($topic, string $format = null, array $context = []): array
+        public function normalize($topic, ?string $format = null, array $context = []): array
         {
             $data = $this->normalizer->normalize($topic, $format, $context);
 
@@ -47,7 +47,7 @@ normalization process::
             return $data;
         }
 
-        public function supportsNormalization($data, string $format = null, array $context = []): bool
+        public function supportsNormalization($data, ?string $format = null, array $context = []): bool
         {
             return $data instanceof Topic;
         }

testing.rst

@@ -555,13 +555,13 @@ returns a ``Crawler`` instance.
 
 The full signature of the ``request()`` method is::
 
-    request(
+    public function request(
         string $method,
         string $uri,
         array $parameters = [],
         array $files = [],
         array $server = [],
-        string $content = null,
+        ?string $content = null,
         bool $changeHistory = true
     ): Crawler
 
@@ -960,7 +960,7 @@ Response Assertions
     Asserts that the response was successful (HTTP status is 2xx).
 ``assertResponseStatusCodeSame(int $expectedCode, string $message = '')``
     Asserts a specific HTTP status code.
-``assertResponseRedirects(string $expectedLocation = null, int $expectedCode = null, string $message = '')``
+``assertResponseRedirects(?string $expectedLocation = null, ?int $expectedCode = null, string $message = '')``
     Asserts the response is a redirect response (optionally, you can check
     the target location and status code). The excepted location can be either
     an absolute or a relative path.
@@ -969,10 +969,10 @@ Response Assertions
 ``assertResponseHeaderSame(string $headerName, string $expectedValue, string $message = '')``/``assertResponseHeaderNotSame(string $headerName, string $expectedValue, string $message = '')``
     Asserts the given header does (not) contain the expected value on the
     response, e.g. ``assertResponseHeaderSame('content-type', 'application/octet-stream');``.
-``assertResponseHasCookie(string $name, string $path = '/', string $domain = null, string $message = '')``/``assertResponseNotHasCookie(string $name, string $path = '/', string $domain = null, string $message = '')``
+``assertResponseHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')``/``assertResponseNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')``
     Asserts the given cookie is present in the response (optionally
     checking for a specific cookie path or domain).
-``assertResponseCookieValueSame(string $name, string $expectedValue, string $path = '/', string $domain = null, string $message = '')``
+``assertResponseCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = '')``
     Asserts the given cookie is present and set to the expected value.
 ``assertResponseFormatSame(?string $expectedFormat, string $message = '')``
     Asserts the response format returned by the
@@ -993,10 +993,10 @@ Request Assertions
 Browser Assertions
 ..................
 
-``assertBrowserHasCookie(string $name, string $path = '/', string $domain = null, string $message = '')``/``assertBrowserNotHasCookie(string $name, string $path = '/', string $domain = null, string $message = '')``
+``assertBrowserHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')``/``assertBrowserNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')``
     Asserts that the test Client does (not) have the given cookie set
     (meaning, the cookie was set by any response in the test).
-``assertBrowserCookieValueSame(string $name, string $expectedValue, string $path = '/', string $domain = null, string $message = '')``
+``assertBrowserCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = '')``
     Asserts the given cookie in the test Client is set to the expected
     value.
 ``assertThatForClient(Constraint $constraint, string $message = '')``
@@ -1047,18 +1047,18 @@ Crawler Assertions
 Mailer Assertions
 .................
 
-``assertEmailCount(int $count, string $transport = null, string $message = '')``
+``assertEmailCount(int $count, ?string $transport = null, string $message = '')``
     Asserts that the expected number of emails was sent.
-``assertQueuedEmailCount(int $count, string $transport = null, string $message = '')``
+``assertQueuedEmailCount(int $count, ?string $transport = null, string $message = '')``
     Asserts that the expected number of emails was queued (e.g. using the
     Messenger component).
 ``assertEmailIsQueued(MessageEvent $event, string $message = '')``/``assertEmailIsNotQueued(MessageEvent $event, string $message = '')``
     Asserts that the given mailer event is (not) queued. Use
-    ``getMailerEvent(int $index = 0, string $transport = null)`` to
+    ``getMailerEvent(int $index = 0, ?string $transport = null)`` to
     retrieve a mailer event by index.
 ``assertEmailAttachmentCount(RawMessage $email, int $count, string $message = '')``
     Asserts that the given email has the expected number of attachments. Use
-    ``getMailerMessage(int $index = 0, string $transport = null)`` to
+    ``getMailerMessage(int $index = 0, ?string $transport = null)`` to
     retrieve a specific email by index.
 ``assertEmailTextBodyContains(RawMessage $email, string $text, string $message = '')``/``assertEmailTextBodyNotContains(RawMessage $email, string $text, string $message = '')``
     Asserts that the text body of the given email does (not) contain the

translation.rst

@@ -963,6 +963,25 @@ the framework:
 This ``default_locale`` is also relevant for the translator, as shown in the
 next section.
 
+Selecting the Language Preferred by the User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your application supports multiple languages, the first time a user visits your
+site it's common to redirect them to the best possible language according to their
+preferences. This is achieved with the ``getPreferredLanguage()`` method of the
+:ref:`Request object <controller-request-argument>`::
+
+    // get the Request object somehow (e.g. as a controller argument)
+    $request = ...
+    // pass an array of the locales (their script and region parts are optional) supported
+    // by your application and the method returns the best locale for the current user
+    $locale = $request->getPreferredLanguage(['pt', 'fr_Latn_CH', 'en_US'] );
+
+Symfony finds the best possible language based on the locales passed as argument
+and the value of the ``Accept-Language`` HTTP header. If it can't find a perfect
+match between them, this method returns the first locale passed as argument
+(that's why the order of the passed locales is important).
+
 .. _translation-fallback:
 
 Fallback Translation Locales

validation/custom_constraint.rst

@@ -27,7 +27,7 @@ First you need to create a Constraint class and extend :class:`Symfony\\Componen
             public string $mode = 'strict';
 
             // all configurable options must be passed to the constructor
-            public function __construct(string $mode = null, string $message = null, array $groups = null, $payload = null)
+            public function __construct(?string $mode = null, ?string $message = null, ?array $groups = null, $payload = null)
             {
                 parent::__construct([], $groups, $payload);
 
@@ -243,9 +243,9 @@ define those options as public properties on the constraint class::
 
         public function __construct(
             $mandatoryFooOption,
-            string $message = null,
-            bool $optionalBarOption = null,
-            array $groups = null,
+            ?string $message = null,
+            ?bool $optionalBarOption = null,
+            ?array $groups = null,
             $payload = null,
             array $options = []
         ) {