Using Environment Variables in Enabled Locales

Contributed by Nicolas Grekas in #63121

The framework.enabled_locales configuration option used to require a hard-coded list of locales. In Symfony 8.1 you can use environment variables in this list directly. Empty values are filtered out automatically, so you can declare a fixed number of slots and leave some of them empty:

# config/packages/translation.yaml
framework:
    enabled_locales:
        - '%env(LOCALE_1)%'
        - '%env(LOCALE_2)%'
        - '%env(LOCALE_3)%'
        - '%env(LOCALE_4)%'

This is useful when the list of enabled locales depends on the deployment environment. For example, different tenants may enable different subsets of languages without requiring a separate configuration file per environment.

Translated Placeholder on Expanded Choice Fields

Contributed by Eyüp Can Akman in #63727

When a ChoiceType is rendered as a group of radio buttons or checkboxes (expanded: true), its placeholder label used the choice_translation_domain option for translation.

This caused problems with EntityType, whose choice_translation_domain defaults to false. As a result, TranslatableMessage placeholders were never translated even when an explicit translation_domain was configured.

In Symfony 8.1, placeholders for expanded choice fields now use translation_domain, matching the behavior of non-expanded <select> fields:

use Symfony\Component\Translation\TranslatableMessage;
use Symfony\Bridge\Doctrine\Form\Type\EntityType;

$form = $this->createForm(EntityType::class, null, [
    'class' => Country::class,
    'expanded' => true,
    // this placeholder is now translated using the 'forms' domain.
    'placeholder' => new TranslatableMessage('select_a_country', [], 'forms'),
    'translation_domain' => 'forms',
]);

New LocaleFallbackProvider Class

Contributed by Matthias Pigulla in #45553

Applications with many regional locales often need to compute locale fallback chains consistently across different services and components.

Symfony resolves these fallback chains by following ICU parent mappings, shortening locale sub-tags, and finally appending any configured fallback locales. Until now, this logic lived inside the Translator class.

In Symfony 8.1, this logic is extracted into a dedicated reusable LocaleFallbackProvider class:

use Symfony\Component\Translation\LocaleFallbackProvider;

$provider = new LocaleFallbackProvider(['en']);
$fallbacks = $provider->computeFallbackLocales('es_AR');
// ['es_419', 'es', 'en']

The class also provides a static helper to validate locale strings. It throws an InvalidArgumentException when the locale contains invalid characters:

LocaleFallbackProvider::validateLocale($locale);

Support for XLIFF Versions 2.1 and 2.2

Contributed by Alexandre Daubois in #63455

Symfony previously accepted only XLIFF 1.2 and 2.0 files. Translation files declaring version="2.1" or version="2.2" were rejected even though their structure is fully compatible with XLIFF 2.0.

This could become an issue when using newer localization platforms or translation tooling that already generate XLIFF 2.1 or 2.2 files by default. Symfony 8.1 now accepts these newer version numbers transparently:

<?xml version="1.0" encoding="UTF-8" ?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0"
    version="2.2" srcLang="en" trgLang="fr">
    <file id="f1">
        <unit id="welcome">
            <segment>
                <source>Welcome</source>
                <target>Bienvenue</target>
            </segment>
        </unit>
    </file>
</xliff>

Support for XLIFF PGS Module

Contributed by Alexandre Daubois in #63465

XLIFF 2.2 introduces the PGS module (Plural, Gender and Select), which allows translators to express plural, gender, and select variations directly inside XLIFF files.

Symfony 8.1 understands these attributes, converts them internally to ICU MessageFormat, and registers the result in the +intl-icu translation domain. This means the translations work transparently with trans():

<?xml version="1.0" encoding="UTF-8" ?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0"
    xmlns:pgs="urn:oasis:names:tc:xliff:pgs:1.0"
    version="2.2" srcLang="en" trgLang="fr">
    <file id="f1">
        <unit id="file_deleted" pgs:switch="plural:file_count">
            <segment id="s1" pgs:case="0">
                <source>You deleted no file.</source>
                <target>Vous n'avez supprimé aucun fichier.</target>
            </segment>
            <segment id="s2" pgs:case="1">
                <source>You deleted one file.</source>
                <target>Vous avez supprimé un fichier.</target>
            </segment>
            <segment id="s3" pgs:case="other">
                <source>You deleted <ph id="1" disp="file_count"/> files.</source>
                <target>Vous avez supprimé <ph id="1" disp="file_count"/> fichiers.</target>
            </segment>
        </unit>
    </file>
</xliff>

The pgs:switch attribute defines the variable name and switch type (plural, gender, or select), while each <segment> uses pgs:case to match a value.

You can also combine multiple switches in a single attribute. For example, pgs:switch="gender:host_gender plural:guest_count". Symfony automatically nests the generated ICU structures as needed.

Changelog Since Symfony 8.1.0-BETA1

• data #64203 Release v8.1.0-BETA2
• bug #64198 [SecurityBundle] Allow defining security provider factories without config (@hockdudu)
• bug #64189 [FrameworkBundle] Bump Request/Session value resolver priority above EntityValueResolver (@ousamabenyounes)
• bug #64197 [Messenger] Ensure SigningSerializer won't decode before verifying the signature (@nicolas-grekas)
• bug #64195 [Security] Remove the legacy nested unserialize() call from token and exception classes (@nicolas-grekas)
• bug #64196 [Yaml] Reject non-stringables when using "!!binary" (@nicolas-grekas)
• bug #64191 [Inflector][String] Fixed singularize traces > trace (@ruudk)
• bug #64192 [Mailer] Use hash_equals() to compare webhook signatures for AhaSend (@alexandre-daubois)
• bug #64193 [Notifier] Use hash_equals() to compare webhook signatures for Vonage (@alexandre-daubois)
• bug #64180 [Messenger][Amqp] Fix support for RabbitMQ v4 by adding delayed quorum queues (@Jean85)
• bug #64187 [AssetMapper] Warn on missing bare CSS and JSON imports (@ousamabenyounes)
• feature #61936 [Messenger] Allow to respect retry strategy with RecoverableMessageHandlingException (@VincentLanglet)
• bug #64182 [Console] Fix signal handler scoping (@jpollard3)
• bug #64181 [Security] Preserve webserver base URL in HttpUtils::createRequest() (@ousamabenyounes)
• bug #64058 [Process] Ignore array env values before proc_open (@dionisvl)
• bug #64179 [Filesystem] preserve source mode when copying files (@nicolas-grekas)
• bug #64176 [Console] Make ConsoleSectionOutput::overwrite() atomic to fix sections + ProgressIndicator clear (@Amoifr)
• feature #63770 [HttpClient] Add custom DNS resolution using a decorator (@peter17)
• bug #64158 [Form] Fix array_flip() warning in expanded+multiple ChoiceType on partial submit (@SAY-5)
• feature #64156 [Validator] Add findByCodes() to ConstraintViolationListInterface (@michaelthieulin)
• feature #64160 [HttpClient] Add $allowList argument to NoPrivateNetworkHttpClient (@Amoifr)
• feature #64163 [HttpClient] Log stale-if-error fallback in CachingHttpClient (@ousamabenyounes)
• bug #64174 [Scheduler] Use stored checkpoint as base date for debug:scheduler (@ousamabenyounes)
• bug #64153 [Messenger] Drop trace args from FlattenException normalization (@ousamabenyounes)
• bug #64150 [HttpKernel] Use backend-handled request for terminate listeners in HttpCache (@Toflar)
• bug #64172 [WebProfilerBundle] Don’t try to access RawMessage::$headers (@MatTheCat)
• bug #64148 [Dotenv] Don't truncate OS env vars containing $ when $_ENV is unpopulated (@HMAZonderland)
• feature #60298 [Messenger][Amqp] delayed quorum queues (Miquel Fontana, @miquel-angel)
• bug #64167 [Console] Add missing symfony/polyfill-php85 dependency (@Amoifr)
• data #64146 Release v6.4.38
• data #64145 Release v8.0.10
• data #64144 Release v7.4.10

Changelog Since Symfony 8.0.10

• data #64202 Release v8.0.11
• bug #64198 [SecurityBundle] Allow defining security provider factories without config (@hockdudu)
• bug #64189 [FrameworkBundle] Bump Request/Session value resolver priority above EntityValueResolver (@ousamabenyounes)
• bug #64197 [Messenger] Ensure SigningSerializer won't decode before verifying the signature (@nicolas-grekas)
• bug #64195 [Security] Remove the legacy nested unserialize() call from token and exception classes (@nicolas-grekas)
• bug #64196 [Yaml] Reject non-stringables when using "!!binary" (@nicolas-grekas)
• bug #64191 [Inflector][String] Fixed singularize traces > trace (@ruudk)
• bug #64192 [Mailer] Use hash_equals() to compare webhook signatures for AhaSend (@alexandre-daubois)
• bug #64193 [Notifier] Use hash_equals() to compare webhook signatures for Vonage (@alexandre-daubois)
• bug #64180 [Messenger][Amqp] Fix support for RabbitMQ v4 by adding delayed quorum queues (@Jean85)
• bug #64187 [AssetMapper] Warn on missing bare CSS and JSON imports (@ousamabenyounes)
• bug #64182 [Console] Fix signal handler scoping (@jpollard3)
• bug #64181 [Security] Preserve webserver base URL in HttpUtils::createRequest() (@ousamabenyounes)
• bug #64058 [Process] Ignore array env values before proc_open (@dionisvl)
• bug #64179 [Filesystem] preserve source mode when copying files (@nicolas-grekas)
• bug #64176 [Console] Make ConsoleSectionOutput::overwrite() atomic to fix sections + ProgressIndicator clear (@Amoifr)
• bug #64174 [Scheduler] Use stored checkpoint as base date for debug:scheduler (@ousamabenyounes)
• bug #64153 [Messenger] Drop trace args from FlattenException normalization (@ousamabenyounes)
• bug #64150 [HttpKernel] Use backend-handled request for terminate listeners in HttpCache (@Toflar)
• bug #64172 [WebProfilerBundle] Don’t try to access RawMessage::$headers (@MatTheCat)
• bug #64148 [Dotenv] Don't truncate OS env vars containing $ when $_ENV is unpopulated (@HMAZonderland)
• data #64146 Release v6.4.38
• data #64144 Release v7.4.10

Changelog Since Symfony 7.4.10

• data #64201 Release v7.4.11
• bug #64198 [SecurityBundle] Allow defining security provider factories without config (@hockdudu)
• bug #64189 [FrameworkBundle] Bump Request/Session value resolver priority above EntityValueResolver (@ousamabenyounes)
• bug #64197 [Messenger] Ensure SigningSerializer won't decode before verifying the signature (@nicolas-grekas)
• bug #64195 [Security] Remove the legacy nested unserialize() call from token and exception classes (@nicolas-grekas)
• bug #64196 [Yaml] Reject non-stringables when using "!!binary" (@nicolas-grekas)
• bug #64191 [Inflector][String] Fixed singularize traces > trace (@ruudk)
• bug #64192 [Mailer] Use hash_equals() to compare webhook signatures for AhaSend (@alexandre-daubois)
• bug #64193 [Notifier] Use hash_equals() to compare webhook signatures for Vonage (@alexandre-daubois)
• bug #64180 [Messenger][Amqp] Fix support for RabbitMQ v4 by adding delayed quorum queues (@Jean85)
• bug #64187 [AssetMapper] Warn on missing bare CSS and JSON imports (@ousamabenyounes)
• bug #64182 [Console] Fix signal handler scoping (@jpollard3)
• bug #64181 [Security] Preserve webserver base URL in HttpUtils::createRequest() (@ousamabenyounes)
• bug #64058 [Process] Ignore array env values before proc_open (@dionisvl)
• bug #64179 [Filesystem] preserve source mode when copying files (@nicolas-grekas)
• bug #64176 [Console] Make ConsoleSectionOutput::overwrite() atomic to fix sections + ProgressIndicator clear (@Amoifr)
• bug #64174 [Scheduler] Use stored checkpoint as base date for debug:scheduler (@ousamabenyounes)
• bug #64153 [Messenger] Drop trace args from FlattenException normalization (@ousamabenyounes)
• bug #64150 [HttpKernel] Use backend-handled request for terminate listeners in HttpCache (@Toflar)
• bug #64172 [WebProfilerBundle] Don’t try to access RawMessage::$headers (@MatTheCat)
• bug #64148 [Dotenv] Don't truncate OS env vars containing $ when $_ENV is unpopulated (@HMAZonderland)
• data #64146 Release v6.4.38

Changelog Since Symfony 6.4.38

• data #64200 Release v6.4.39
• bug #64198 [SecurityBundle] Allow defining security provider factories without config (@hockdudu)
• bug #64189 [FrameworkBundle] Bump Request/Session value resolver priority above EntityValueResolver (@ousamabenyounes)
• bug #64195 [Security] Remove the legacy nested unserialize() call from token and exception classes (@nicolas-grekas)
• bug #64196 [Yaml] Reject non-stringables when using "!!binary" (@nicolas-grekas)
• bug #64191 [Inflector][String] Fixed singularize traces > trace (@ruudk)
• bug #64193 [Notifier] Use hash_equals() to compare webhook signatures for Vonage (@alexandre-daubois)
• bug #64180 [Messenger][Amqp] Fix support for RabbitMQ v4 by adding delayed quorum queues (@Jean85)
• bug #64187 [AssetMapper] Warn on missing bare CSS and JSON imports (@ousamabenyounes)
• bug #64182 [Console] Fix signal handler scoping (@jpollard3)
• bug #64181 [Security] Preserve webserver base URL in HttpUtils::createRequest() (@ousamabenyounes)
• bug #64058 [Process] Ignore array env values before proc_open (@dionisvl)
• bug #64179 [Filesystem] preserve source mode when copying files (@nicolas-grekas)
• bug #64176 [Console] Make ConsoleSectionOutput::overwrite() atomic to fix sections + ProgressIndicator clear (@Amoifr)
• bug #64174 [Scheduler] Use stored checkpoint as base date for debug:scheduler (@ousamabenyounes)
• bug #64153 [Messenger] Drop trace args from FlattenException normalization (@ousamabenyounes)
• bug #64150 [HttpKernel] Use backend-handled request for terminate listeners in HttpCache (@Toflar)
• bug #64172 [WebProfilerBundle] Don’t try to access RawMessage::$headers (@MatTheCat)
• bug #64148 [Dotenv] Don't truncate OS env vars containing $ when $_ENV is unpopulated (@HMAZonderland)

Decoupled Controller Attributes

Contributed by Nicolas Grekas in #62850

Until now, controller attributes were always read directly from the controller's source code via reflection. This meant that listeners had no way to modify or replace those attributes at runtime: the attributes effectively belonged to the PHP code, not to the request being processed.

Symfony 8.1 stores controller attributes in a new request attribute named _controller_attributes. The first call to ControllerEvent::getAttributes() populates it from reflection, and subsequent reads (including in later kernel events) reuse the stored value. Listeners can now override attributes for a specific request by calling setController() with a custom set of attributes:

use Symfony\Component\HttpKernel\Attribute\Cache;
use Symfony\Component\HttpKernel\Event\ControllerEvent;

public function onKernelController(ControllerEvent $event): void
{
    // replace the controller's #[Cache] attribute for this request only,
    // without touching the controller's source code
    $attributes = $event->getAttributes();
    $attributes[Cache::class] = [new Cache(maxage: 60, public: true)];

    $event->setController(
        $event->getController(),
        array_merge(...array_values($attributes)),
    );
}

This restores the declarative nature of PHP attributes: the source code defines the defaults, and the rest of the application can adapt them when needed.

Flat List of Controller Attributes

Contributed by Nicolas Grekas in #63090

Symfony 8.1 also simplifies how controller attributes are represented. Instead of always returning them grouped by class name, getAttributes() accepts a new '*' argument to return a flat list of attribute instances in their declaration order:

// get all attributes grouped by class name (default behavior)
$event->getAttributes();
// returns: [Cache::class => [new Cache(...)], IsGranted::class => [new IsGranted(...)], ...]

// get all attributes as a flat list, in declaration order
$event->getAttributes('*');
// returns: [new Cache(...), new IsGranted(...), ...]

// get all attributes of a specific class
$event->getAttributes(Cache::class);
// returns: [new Cache(...), ...]

In addition, ResponseEvent now exposes a public readonly $controllerArgumentsEvent property so response listeners can read the controller attributes that applied to the request without re-reflecting the controller:

use Symfony\Component\HttpKernel\Attribute\Cache;
use Symfony\Component\HttpKernel\Event\ResponseEvent;

public function onKernelResponse(ResponseEvent $event): void
{
    $cacheAttributes = $event->controllerArgumentsEvent?->getAttributes(Cache::class) ?? [];
    // ... act on the response based on the controller's attributes
}

Events Named After Controller Attributes

Contributed by Nicolas Grekas in #63032

Before Symfony 8.1, attribute-based listeners had to subscribe to generic kernel events and manually inspect controller attributes. Symfony 8.1 introduces dedicated events for each controller attribute instead.

The event name follows the convention {kernelEvent}.{AttributeFQCN}, so a #[Cache] attribute triggers the event kernel.controller_arguments.Symfony\Component\HttpKernel\Attribute\Cache (or KernelEvents::CONTROLLER_ARGUMENTS.'.'.Cache::class).

Each event receives a ControllerAttributeEvent object that combines the attribute instance with the underlying kernel event. For example, if you define this custom attribute in your application:

namespace App\Attribute;

#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD)]
final class RateLimit
{
    public function __construct(
        public int $maxRequests = 100,
        public int $periodInSeconds = 60,
    ) {
    }
}

You can apply the attribute to any controller and write the following listener to handle it:

namespace App\EventListener;

use App\Attribute\RateLimit;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\ControllerAttributeEvent;
use Symfony\Component\HttpKernel\KernelEvents;

#[AsEventListener(event: KernelEvents::CONTROLLER_ARGUMENTS.'.'.RateLimit::class)]
final class RateLimitListener
{
    public function __invoke(ControllerAttributeEvent $event): void
    {
        $rateLimit = $event->attribute;       // RateLimit instance
        $request = $event->kernelEvent->getRequest();

        // ... enforce $rateLimit->maxRequests within $rateLimit->periodInSeconds
    }
}

Attribute events are available for all controller-related kernel events. Symfony also preserves attribute declaration order automatically, so listeners compose naturally around controllers.

Symfony optimizes these events internally, dispatching them only when listeners exist and supporting attribute inheritance automatically. Built-in listeners such as CacheAttributeListener, IsGrantedAttributeListener and TemplateAttributeListener have been migrated to this new system.