Symfony version(s) affected

6.3.3

Description

Hi, currently Symfony\Component\Mime\Header\Headers does not allow to set Mime headers in general way: some headers must be strings, some - arrays, but this fact cannot be guessed from the method signature or documentation. We observed this issue only in runtime - when the Symfony\Component\Mime\Header\Headers::addMailboxListHeader(): Argument #2 ($addresses) must be of type array, string given exception reported.

We wrote a common method that sends email with simple signature public function send(string $email, string $subject, string $content, array $headers = []): void;.
We assumed that the $headers is array<string, string> and that array is completely controlled by a client of our library, but at the moment we should have knowledge "which data type do we need to use given header name" and that knowledge is hard-coded inside the private constant Headers::HEADER_CLASS_MAP.

I think it's better to hide that knowledge inside the lybrary code and make client's code more simplier and clear.

How to reproduce

// First, run "composer require symfony/mime"
// Then, execute this file:

<?php
require_once __DIR__.'/vendor/autoload.php';

use Symfony\Component\Mime\Email;

$headers = [
    'x-foo' => 'bar',
    'reply-to' => 'foo@bar.com',
];

$message = (new Email())
    ->from('bar@foo.com')
    ->to('baz@foo.com')
    ->subject('hello')
    ->html('')
;

foreach ($headers as $name => $value) {
    $message->getHeaders()->addTextHeader($name, $value);
    /* when $name == 'reply-to' the Exception "Argument #2 ($addresses) must be of type array, string given" will be thrown */
}

Possible Solution

it's better to check the argument type inside the addHeader method when $method === 'addMailboxListHeader', because it's not clear for the client that calls the addHeader which exact data type have to be used here.
Suggested variant is:

      elseif ($method === 'addMailboxListHeader' && !\is_array($argument)) {
            $argument = [$argument];
        }

Additional Context

No response