5.4 est la version LTS, et son rôle est de porter autant que possible le jeu de fonctionnalités de 6.0 tout en conservant la compatibilité 5.x. C’est aussi la première version de Symfony qui comprend réellement les fonctionnalités de PHP 8.1.

Support des enums

PHP 8.1 a introduit les enums natifs. Symfony 5.4 les embrasse immédiatement :

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

Le type de formulaire EnumType rend les enums sous forme de listes déroulantes, sans transformateurs personnalisés. Le validateur comprend les backed enums. Le sérialiseur mappe les valeurs d’enum sur leur type de backing et inversement. Trois composants mis à jour d’un coup, ce qui a rendu la migration des bases de code des pseudo-constantes enum vers les vrais enums PHP 8.1 étonnamment fluide.

Cache des voters de sécurité

La CacheableVoterInterface permet aux voters qui s’abstiennent toujours sur un attribut donné de le signaler au système de sécurité, qui peut alors les ignorer lors des vérifications suivantes. Pour les applications avec de nombreux voters, le gain sur les vérifications de permissions s’accumule vite. Petit changement, perceptible en pratique.

Messenger continue de mûrir

Le traitement par batch de Messenger (gérer plusieurs messages en une seule transaction au lieu d’un par un) est maintenant stable. Rate limiting par transport. Les dead letter queues bénéficient de meilleurs outils. Après des années en mode « expérimental », Messenger en 5.4 est enfin la fondation async sur laquelle on peut s’appuyer pour des charges sérieuses.

La Console a eu sa touche Tab

Symfony 5.4 embarque l’autocomplétion shell pour toutes les commandes. Appuyez sur Tab et le shell suggère les noms de commandes, les valeurs d’arguments et les valeurs d’options. Pour les commandes intégrées, ça fonctionne sans configuration. Pour les commandes personnalisées, ajoutez une méthode complete() :

use Symfony\Component\Console\Completion\CompletionInput;
use Symfony\Component\Console\Completion\CompletionSuggestions;

public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
{
    if ($input->mustSuggestOptionValuesFor('format')) {
        $suggestions->suggestValues(['json', 'xml', 'csv']);
    }
}

Pas d’interface requise, juste la méthode et Symfony s’en charge. La communauté a aussi passé en revue toutes les commandes intégrées (debug:router, cache:pool:clear, secrets:remove, lint:twig, et une dizaine d’autres) pour ajouter les compléments avant la sortie.

Les routes peuvent être des alias maintenant

Le composant de routing supporte désormais les alias : une route peut pointer vers une autre. Le cas d’usage évident, c’est renommer une route sans casser tout ce qui génère encore des URLs avec l’ancien nom.

# config/routes.yaml
admin_dashboard:
    path: /admin

# ancien nom conservé pendant la transition
dashboard:
    alias: admin_dashboard
    deprecated:
        package: 'acme/my-bundle'
        version: '2.3'

Générer une URL avec dashboard fonctionne toujours, mais déclenche un avertissement de dépréciation. Des chemins de renommage propres pour les bundles qui doivent maintenir des noms de routes publics tout en avançant.

Les exceptions sont mappées aux codes HTTP dans la config

Avant 5.4, mapper une classe d’exception à un code HTTP signifiait implémenter HttpExceptionInterface ou écrire un listener. Maintenant c’est juste une entrée YAML :

# config/packages/framework.yaml
framework:
    exceptions:
        App\Exception\PaymentRequiredException:
            status_code: 402
            log_level: warning
        App\Exception\MaintenanceException:
            status_code: 503
            log_level: info

L’exception n’a rien à implémenter. Le framework lit la map, définit le code de statut, loggue au niveau configuré. Pratique pour les exceptions métier qui n’ont aucune raison de connaître HTTP.

Deux nouvelles contraintes de validation

5.4 ajoute Cidr et CssColor au composant Validator.

Cidr valide la notation réseau (adresse IP plus masque de sous-réseau) avec un contrôle sur la version IP acceptée et les bornes de la valeur du masque :

#[Assert\Cidr(version: 4, netmaskMin: 16, netmaskMax: 28)]
private string $allowedSubnet;

CssColor valide qu’une chaîne est une couleur CSS valide. Utile pour les éditeurs de thème, la config CMS, ou toute interface qui laisse les utilisateurs choisir des couleurs :

#[Assert\CssColor(
    formats: Assert\CssColor::HEX_LONG,
    message: "La couleur d'accentuation doit être une valeur hex à 6 chiffres.",
)]
private string $accentColor;

Attributs PHP imbriqués pour les contraintes de validation

Symfony 5.2 avait ajouté les contraintes de validation en attributs PHP, mais PHP 8.0 avait une limitation sur les attributs imbriqués. Les contraintes complexes comme All, Collection, ou AtLeastOneOf étaient impossibles à exprimer avec la syntaxe d’attribut seule. PHP 8.1 a levé cette restriction, et 5.4 en tire le meilleur parti :

use Symfony\Component\Validator\Constraints as Assert;

class CartItem
{
    #[Assert\All([
        new Assert\NotNull(),
        new Assert\Range(min: 1),
    ])]
    private array $quantities;

    #[Assert\AtLeastOneOf(
        constraints: [new Assert\Email(), new Assert\Url()],
        message: 'Doit être un email ou une URL valide.',
    )]
    private string $contact;
}

Pas de docblocks d’annotations, pas de mapping XML. Des attributs PHP 8.1 purs, de bout en bout.

Injection de dépendances : trois choses à savoir

Les itérateurs taggués peuvent maintenant être injectés dans des service locators, qui n’acceptaient auparavant que des listes de services explicites. L’autowiring des types union fonctionne quand les deux côtés de l’union résolvent vers le même service, ce qui est courant avec les interfaces du serializer :

public function __construct(
    private NormalizerInterface & DenormalizerInterface $serializer
) {}

#[SubscribedService] remplace l’introspection automatique que ServiceSubscriberTrait faisait implicitement. C’est maintenant un attribut explicite sur les méthodes, ce qui rend la dépendance visible sans aucune magie :

use Symfony\Contracts\Service\Attribute\SubscribedService;

class SomeService implements ServiceSubscriberInterface
{
    #[SubscribedService]
    private function router(): RouterInterface
    {
        return $this->container->get(__METHOD__);
    }
}

Messenger : attributs, état des workers et reset de services

Les handlers Messenger peuvent abandonner MessageHandlerInterface en faveur de #[AsMessageHandler], qui permet aussi de lier un handler à un transport spécifique et de définir sa priorité, sans toucher au YAML :

#[AsMessageHandler(fromTransport: 'async', priority: 10)]
class ProcessOrderHandler
{
    public function __invoke(ProcessOrder $message): void { /* ... */ }
}

L’état des workers est maintenant inspectable via WorkerMetadata dans les event listeners, utile quand vous avez des workers sur plusieurs transports et avez besoin de savoir lequel a déclenché un événement donné.

Les workers longue durée accumulent de l’état entre les messages : buffers de l’entity manager, caches en mémoire, connexions ouvertes. La nouvelle option reset_on_message prend en charge la réinitialisation de tous les services réinitialisables entre les messages :

framework:
    messenger:
        reset_on_message: true

Serializer : collecter les erreurs plutôt que lever

Désérialiser du JSON externe dans un DTO typé levait une exception dès la première discordance de type. L’option COLLECT_DENORMALIZATION_ERRORS change ça : toutes les erreurs de type sont collectées dans une PartialDenormalizationException, pour que vous puissiez retourner un 400 propre avec la liste complète des problèmes par champ :

try {
    $dto = $serializer->deserialize($request->getContent(), OrderDto::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
    ]);
} catch (PartialDenormalizationException $e) {
    return $this->json(
        array_map(fn($err) => ['path' => $err->getPath(), 'expected' => $err->getExpectedTypes()], $e->getErrors()),
        400
    );
}

Le contexte par défaut du serializer peut aussi être défini globalement en YAML, pour ne plus passer les mêmes options à chaque appel.

Négociation de langue intégrée

Deux nouvelles options du framework gèrent l’en-tête Accept-Language sans listeners personnalisés :

framework:
    enabled_locales: ['en', 'fr', 'de']
    set_locale_from_accept_language: true
    set_content_language_from_locale: true

Avec ça en place, Symfony lit la langue préférée du navigateur, choisit la meilleure correspondance parmi enabled_locales, définit la locale de la requête, et ajoute un en-tête Content-Language à la réponse. L’attribut de route {_locale} a toujours la priorité quand il est présent.

Traduction : extraction, pas mise à jour

La commande translation:update est renommée en translation:extract. L’ancien nom reste comme déprécié. La distinction compte : la commande n’écrit jamais dans une base de données, elle extrait les chaînes traduisibles des fichiers source. Le nouveau nom dit enfin ce qu’elle fait.

lint:xliff gagne aussi une option --format=github qui sort les erreurs en annotations GitHub Actions, pour que les échecs de lint de traduction apparaissent en commentaires de revue de PR plutôt que de se noyer dans les logs.

Raccourcis du contrôleur élagués

Trois raccourcis d’AbstractController sont dépréciés : getDoctrine(), dispatchMessage(), et la méthode générique get() pour récupérer des services arbitraires du container. La direction, c’est l’injection par constructeur explicite. Pour getDoctrine() en particulier :

// avant
$em = $this->getDoctrine()->getManager();

// après — injecter directement
public function __construct(private EntityManagerInterface $em) {}

Request::get() est aussi déprécié. Il cherchait dans les attributs de route, la query string et le corps POST dans un ordre non documenté, ce qui était une excellente façon d’obtenir des résultats surprenants. Utilisez $request->query->get(), $request->request->get(), ou $request->attributes->get() et soyez explicite sur la provenance de la valeur.

La classe utilitaire Path

Le composant Filesystem reçoit une classe Path portée depuis webmozart/path-util. Elle gère les cas tordus que dirname() et realpath() ratent :

use Symfony\Component\Filesystem\Path;

Path::canonicalize('../config/../config/services.yaml'); // '../config/services.yaml'
Path::getDirectory('C:/');                               // 'C:/' (dirname() retourne '.')
Path::getLongestCommonBasePath([
    '/var/www/project/src/Controller/FooController.php',
    '/var/www/project/src/Controller/BarController.php',
    '/var/www/project/src/Entity/User.php',
]);
// '/var/www/project/src'

Utile dès que votre code manipule des chemins qui traversent les frontières des OS ou qui contiennent des segments relatifs.

Les petites choses qui s’accumulent

debug:dotenv montre quels fichiers .env ont été chargés et quelle valeur chaque variable résout. La première chose qu’on cherche quand un comportement spécifique à un environnement déraille.

Le composant String ajoute trimPrefix() et trimSuffix() pour retirer des préfixes ou suffixes connus sans écrire un calcul de substr :

u('file-image-0001.png')->trimPrefix('file-');    // 'image-0001.png'
u('template.html.twig')->trimSuffix('.twig');      // 'template.html'

DomCrawler reçoit innerText(), qui retourne uniquement le texte direct d’un nœud, à l’exclusion des éléments enfants. text() retourne tout y compris le texte imbriqué ; innerText() retourne uniquement le contenu propre du nœud. Petite différence, mais ça compte quand on fait du scraping.

Le composant RateLimiter étend son support des intervalles avec perMonth() et perYear(), pour les applications qui ont besoin de limiter des événements sur des fenêtres plus longues : envois de newsletters, remises à zéro de quotas API, limites de forfaits annuels.

Le composant Finder respecte maintenant les fichiers .gitignore dans tous les sous-répertoires quand vous appelez ignoreVCSIgnored(true), pas seulement à la racine. Les règles des répertoires enfants supplantent celles des parents, exactement comme git lui-même.

La fenêtre LTS

5.4 reçoit des corrections de bugs jusqu’en novembre 2024 et des correctifs de sécurité jusqu’en novembre 2025. La migration de 5.4 vers 6.4 (la prochaine LTS) est intentionnellement fluide : corrigez les avertissements de dépréciation de 5.4, et le saut vers 6.x devient mécanique.

La couche de dépréciation en 5.4 pointe vers tout ce que 6.0 supprime : les derniers morceaux de l’ancien système de sécurité, ContainerAwareTrait, et quelques patterns legacy de formulaires et de serializer.

Les enums

C’est la nouveauté qui change les bases de code dès la mise à jour. Avant 8.1, les énumérations en PHP se résumaient à des constantes de classe, des chaînes ou des entiers sans rien pour les faire respecter :

// avant : rien n'empêche de passer Status::INVALID
const ACTIVE = 'active';
const INACTIVE = 'inactive';

// après
enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

function activate(Status $status): void { ... }

Les enums PHP sont des objets, pas des scalaires. Ils supportent les méthodes, les interfaces et les constantes. Les backed enums (avec une valeur string ou int) se sérialisent proprement et se mappent naturellement aux colonnes de base de données. Les pure enums (sans type de backing) expriment des concepts métier sans se soucier de la sérialisation.

L’effet immédiat : chaque champ de statut, chaque ensemble fini d’états dans toutes les bases de code que je maintiens est devenu un candidat à l’enum. Le système de types a enfin un moyen natif d’exprimer ce que chaque projet PHP simulait depuis des années.

Les fibers

Les fibers sont une primitive de concurrence coopérative : vous pouvez suspendre et reprendre l’exécution d’une fonction, en cédant le contrôle sans recourir aux threads.

$fiber = new Fiber(function(): void {
    $value = Fiber::suspend('first');
    echo "Repris avec : {$value}\n";
});

$result = $fiber->start();    // 'first'
$fiber->resume('hello');      // "Repris avec : hello"

Les fibers sont la fondation dont les bibliothèques async comme ReactPHP et Amp avaient besoin depuis un moment du côté du runtime. Pour la plupart des développeurs d’applications, l’API directe compte moins que les bibliothèques construites par-dessus, mais comprendre les fibers explique ce que font ces bibliothèques en coulisses.

:pencil2: Les propriétés readonly

8.0 avait apporté la promotion des paramètres du constructeur. 8.1 ajoute readonly :

class User {
    public function __construct(
        public readonly int $id,
        public readonly string $name,
    ) {}
}

Une propriété readonly ne peut être écrite qu’une seule fois, lors de l’initialisation. Après ça, toute écriture lève une Error. Combiné avec la promotion des paramètres, les value objects et les DTOs deviennent concis et signifient réellement ce qu’ils annoncent.

La syntaxe callable de première classe

$fn = strlen(...);
$fn = $this->process(...);
$fn = MyClass::create(...);

... après un callable crée une Closure sans le boilerplate de Closure::fromCallable(). Utile quand on passe des méthodes comme callbacks.

8.1 est précis. Les enums justifient à eux seuls la mise à jour.

Les types d’intersection

Les types union ont débarqué en 8.0. Les types d’intersection suivent en 8.1. Là où un union dit « l’un ou l’autre », une intersection dit « tous à la fois » :

function process(Countable&Iterator $collection): void {
    foreach ($collection as $item) { /* ... */ }
    echo count($collection);
}

Une contrainte : les types d’intersection ne peuvent pas être mélangés avec les types union dans la même déclaration (ça arrivera en 8.2 avec les DNF types). Mais ça débloque déjà une vérification de types précise pour les objets qui doivent satisfaire plusieurs interfaces à la fois, un pattern que les frameworks utilisent constamment et qui devait rester sans typage jusqu’ici.

Le type de retour never

Une fonction qui ne retourne jamais (elle lève toujours une exception ou sort) a maintenant un type pour le dire :

function redirect(string $url): never {
    header("Location: {$url}");
    exit();
}

function fail(string $message): never {
    throw new \RuntimeException($message);
}

L’avantage concret : les analyseurs statiques peuvent prouver que le code après une fonction never est inatteignable, et les appelants savent qu’il n’y a pas de valeur de retour à gérer. Avant ça, ça vivait dans des docblocks sans enforcement.

Les constantes de classe finales

Avant 8.1, n’importe quelle sous-classe pouvait silencieusement surcharger la constante de classe d’un parent. Maintenant vous pouvez y mettre un terme :

class Base {
    final public const VERSION = '1.0';
}

class Child extends Base {
    // Fatal error: Cannot override final constant Base::VERSION
    public const VERSION = '2.0';
}

Parallèlement, les constantes d’interface sont désormais surchargeables par les classes implémentant l’interface par défaut. Un correctif de comportement qui était incohérent depuis l’introduction des interfaces.

new dans les initialiseurs

Les valeurs par défaut des paramètres étaient autrefois limitées aux scalaires et aux tableaux. 8.1 lève cette restriction :

class Logger {
    public function __construct(
        private Handler $handler = new NullHandler(),
    ) {}
}

function createUser(
    Validator $validator = new DefaultValidator(),
): User { /* ... */ }

Idem pour les arguments d’attributs et les initialiseurs de variables statiques. Ce qui signifie que l’injection de dépendances avec des valeurs par défaut sensées ne nécessite plus une vérification de null et une instanciation paresseuse dans le corps de la méthode.

Le déballage de tableaux avec des clés string

Le déballage de tableau via l’opérateur spread ne fonctionnait qu’avec des tableaux à clés entières avant 8.1. Les clés string fonctionnent aussi maintenant :

$defaults = ['color' => 'red', 'size' => 'M'];
$custom = ['size' => 'L', 'weight' => '200g'];

$merged = [...$defaults, ...$custom];
// ['color' => 'red', 'size' => 'L', 'weight' => '200g']

Les clés ultérieures écrasent les précédentes. Même comportement que array_merge(), mais exprimé inline. La différence de performance est marginale ; la différence de lisibilité, elle, ne l’est pas.

fsync et fdatasync

Deux fonctions qui n’avaient aucune bonne raison d’être absentes d’un langage orienté système de fichiers :

$fp = fopen('/tmp/important.dat', 'w');
fwrite($fp, $data);
fsync($fp);   // vide les buffers OS vers le stockage physique
fclose($fp);

fdatasync() fait la même chose mais saute la synchronisation des métadonnées quand on ne se soucie que de la durabilité des données. Les deux retournent false en cas d’échec. Si vous écrivez quoi que ce soit qui nécessite une sécurité en cas de crash, vous aviez besoin de ça.

Passer null aux paramètres non-nullables des fonctions internes

Un changement plus discret mais aux conséquences réelles : les fonctions internes qui acceptent des chaînes, des entiers, etc. ont toujours avalé silencieusement null et l’ont coercé. En 8.1, ça commence à émettre un avertissement de dépréciation.

str_contains("foobar", null);
// Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated

Ça aligne les fonctions internes sur les fonctions définies par l’utilisateur, qui refusaient déjà les arguments nullable pour des paramètres non-nullables. PHP 9.0 transforme ça en erreur fatale. Si vous passez null dans des fonctions de chaînes, c’est maintenant un meilleur moment pour le corriger que pendant un incident de production.

MySQLi lève des exceptions par défaut

Avant 8.1, MySQLi échouait silencieusement sauf si vous appeliez explicitement mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT). C’est maintenant la valeur par défaut :

// Ceci lève \mysqli_sql_exception en cas d'échec de connexion en 8.1
// Auparavant retournait false et définissait une erreur que vous deviez vérifier manuellement
$connection = new mysqli('localhost', 'user', 'wrong_password', 'db');

Toute base de code qui attrape les erreurs MySQLi en vérifiant les valeurs de retour doit être revue. Les échecs silencieux qui causaient des bugs difficiles à diagnostiquer lèvent maintenant des exceptions, ce qui est le bon comportement, même si ça peut surprendre si vous l’attrapez en pleine mise à jour.