L’opérateur pipe

Les pipelines fonctionnels en PHP ont toujours été un bazar. Enchaîner des transformations nécessitait soit d’imbriquer les appels de fonctions à l’envers, soit de les découper en variables intermédiaires :

// avant — se lit de droite à gauche
$result = array_sum(array_map('strlen', array_filter($strings, 'strlen')));

// ou verbeux mais lisible
$filtered   = array_filter($strings, 'strlen');
$lengths    = array_map('strlen', $filtered);
$result     = array_sum($lengths);

// après — se lit de gauche à droite
$result = $strings
    |> array_filter(?, 'strlen')
    |> array_map('strlen', ?)
    |> array_sum(?);

L’opérateur |> passe la valeur de gauche dans l’expression de droite. Le placeholder ? marque où elle va. Les pipelines se lisent maintenant dans l’ordre où les opérations se produisent : gauche à droite, haut en bas.

Ça se marie bien avec les callables de première classe de PHP 8.1. Les deux fonctionnalités se composent bien :

$result = $input |> trim(...) |> strtolower(...) |> $this->normalize(...);

L’extension URI

Gérer les URIs en PHP a toujours signifié soit se tourner vers une bibliothèque tierce, soit assembler parse_url() (retourne un tableau, pas un objet), http_build_query(), et de la concaténation manuelle de strings.

La nouvelle extension Uri donne une vraie API orientée objet :

$uri = Uri\Uri::parse('https://example.com/path?query=value#fragment');
$modified = $uri->withPath('/new-path')->withQuery('key=val');
echo $modified; // https://example.com/new-path?key=val#fragment

Des objets-valeur immutables, un parsing conforme aux RFC, modifier des composants individuels sans parser et reconstruire la string entière. Attendu depuis longtemps.

#[\NoDiscard]

Un nouvel attribut qui génère un avertissement quand la valeur de retour est ignorée :

#[\NoDiscard("Use the returned collection, the original is unchanged")]
public function filter(callable $fn): static { ... }

Utile pour les méthodes immutables où ignorer la valeur de retour est presque certainement un bug. Courant dans d’autres langages depuis des années, maintenant en PHP où ça appartient.

clone with

Cloner un objet avec des propriétés modifiées sans utiliser de property hooks ni une méthode with() personnalisée :

$updated = clone($point) with { x: 10, y: 20 };

Syntaxe propre pour un pattern que les objets readonly nécessitaient : on clone pour “modifier” puisque la mutation directe n’est pas permise.

PHP 8.5 a une tendance fonctionnelle. L’opérateur pipe et l’extension URI ensemble rendent le code de transformation de données significativement plus lisible. Le langage continue dans une direction cohérente.

Les closures dans les expressions constantes

Une contrainte qui existait depuis PHP 5 : les expressions constantes (arguments d’attributs, valeurs par défaut de propriétés, valeurs par défaut de paramètres, déclarations const) ne pouvaient pas contenir de closures ni de callables de première classe. 8.5 supprime ça.

#[Validate(fn($v) => $v > 0)]
public int $count = 0;

const NORMALIZER = strtolower(...);

class Config {
    public function __construct(
        public readonly Closure $transform = trim(...),
    ) {}
}

C’est la pièce manquante qui rend les attributs vraiment expressifs pour les règles de validation et de transformation. Avant 8.5, il fallait passer des noms de classes ou des références string aux attributs et laisser le framework les retrouver. Maintenant le callable vit directement dans l’attribut.

Les attributs sur les constantes

L’attribut #[\Deprecated] de 8.4 ne pouvait pas être appliqué aux déclarations const. 8.5 ajoute le support des attributs pour les constantes en général :

const OLD_LIMIT = 100;

#[\Deprecated('Use RATE_LIMIT instead', since: '3.0')]
const API_TIMEOUT = 30;

const RATE_LIMIT = 60;

ReflectionConstant, une nouvelle classe de réflexion dans 8.5, expose getAttributes() pour que les outils puissent les lire. Combiné avec les closures dans les expressions constantes, les attributs sur les constantes deviennent une vraie couche de métadonnées pour les valeurs à la compilation.

#[\Override] s’étend aux propriétés

PHP 8.3 a apporté #[\Override] pour les méthodes. 8.5 l’étend aux propriétés :

class Base {
    public string $name = 'default';
}

class Derived extends Base {
    #[\Override]
    public string $name = 'derived';
}

Si la propriété n’existe pas dans le parent, PHP lève une erreur. Particulièrement utile avec les property hooks de 8.4 : on peut maintenant signaler qu’une propriété hookée surcharge intentionnellement celle d’un parent.

La visibilité asymétrique statique

8.4 a introduit la visibilité asymétrique (public private(set)) pour les propriétés d’instance. 8.5 l’apporte aussi aux propriétés static :

class Registry {
    public static private(set) array $items = [];

    public static function register(string $key, mixed $value): void {
        self::$items[$key] = $value;
    }
}

echo Registry::$items['foo']; // lisible
Registry::$items['bar'] = 1; // Error: cannot write outside class

Pattern direct : exposer une collection statique en lecture, bloquer la mutation externe.

La promotion de constructeur pour les propriétés final

La promotion de propriétés dans les constructeurs existe depuis PHP 8.0. Le modificateur final sur les propriétés promuées était la pièce manquante, 8.5 l’ajoute :

class ValueObject {
    public function __construct(
        public final readonly string $id,
        public final readonly string $name,
    ) {}
}

Une sous-classe ne peut pas surcharger $id ni $name avec une propriété du même nom. La combinaison final readonly sur les propriétés promuées rend les objets-valeur aussi verrouillés que possible sans sceller la classe entière.

Les casts dans les expressions constantes

Autre lacune dans les expressions constantes : pas de casts de type. 8.5 les permet :

const PRECISION = (int) 3.7;      // 3
const THRESHOLD = (float) '1.5';  // 1.5
const FLAG = (bool) 1;            // true

Ça semble mineur jusqu’à ce qu’on ait des constantes de configuration dérivées de variables d’environnement qui nécessitent une coercition de type directement à la déclaration.

Les erreurs fatales incluent les backtraces

Avant 8.5, une erreur fatale (mémoire insuffisante, dépassement de pile, erreur de type dans certains contextes) produisait un message sans contexte sur où dans le code ça s’est passé. Trouver la cause signifiait insérer des logs de debug et reproduire.

8.5 ajoute des backtraces à la stack aux messages d’erreur fatale, dans le même format que les backtraces d’exceptions. Une nouvelle directive INI, fatal_error_backtraces, contrôle le comportement. Elle est activée par défaut.

array_first() et array_last()

PHP avait reset() et end() pour accéder au premier et dernier élément d’un tableau depuis PHP 3. Les deux mutent le pointeur interne du tableau (pas sûr à appeler sur une référence), et ils retournent false pour les tableaux vides d’une façon indiscernable d’une valeur false stockée.

$values = [10, 20, 30];

$first = array_first($values);  // 10
$last  = array_last($values);   // 30

$first = array_first([]);       // null

Les nouvelles fonctions retournent null pour les tableaux vides, ne touchent pas le pointeur interne, et fonctionnent sur n’importe quelle expression de tableau sans avoir besoin d’une variable. reset($this->getItems()) était un avertissement de dépréciation en attente de se produire.

get_error_handler() et get_exception_handler()

PHP a set_error_handler() et set_exception_handler(). Obtenir le handler courant nécessitait soit de le stocker soi-même avant de le définir, soit d’appeler set_error_handler(null) et de capturer ce qui revenait, ce qui effaçait aussi le handler au passage.

8.5 ajoute :

$current = get_error_handler();
$current = get_exception_handler();

Pratique dans les chaînes de middleware où on veut envelopper le handler existant sans le perdre, ou dans les tests où on veut vérifier qu’un handler a bien été installé.

IntlListFormatter

Formater une liste avec les conjonctions appropriées à la locale nécessitait toujours un assemblage manuel de strings. 8.5 ajoute IntlListFormatter :

$formatter = new IntlListFormatter('en_US', IntlListFormatter::TYPE_AND);
echo $formatter->format(['apples', 'oranges', 'pears']);
// "apples, oranges, and pears"

$formatter = new IntlListFormatter('fr_FR', IntlListFormatter::TYPE_OR);
echo $formatter->format(['rouge', 'bleu', 'vert']);
// "rouge, bleu ou vert"

La classe enveloppe le ListFormatter d’ICU. Trois types : TYPE_AND, TYPE_OR, TYPE_UNITS. Les constantes de largeur contrôlent si on obtient “et” ou “&”. Gestion de la virgule d’Oxford, placement de conjonction spécifique à la locale, tout géré par ICU.

FILTER_THROW_ON_FAILURE pour filter_var()

filter_var() retourne false en cas d’échec de validation, ce qui produit l’ambiguïté classique false vs null vs 0 quand on filtre des entrées non fiables. Un nouveau flag change ça :

try {
    $email = filter_var($input, FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
} catch (Filter\FilterFailedException $e) {
    // explicitement invalide, pas faussement false
}

Les classes Filter\FilterFailedException et Filter\FilterException sont nouvelles dans 8.5. Le flag ne peut pas être combiné avec FILTER_NULL_ON_FAILURE : les comportements sont mutuellement exclusifs.

Les dépréciations qui nettoient des années de dette technique

L’opérateur backtick (`commande` comme alias de shell_exec()) est déprécié. C’est une syntaxe obscure qui surprend quiconque lit le code et est incohérente avec tous les autres appels de fonctions PHP.

Les noms de cast non canoniques ((boolean), (integer), (double), (binary)) sont dépréciés au profit de leurs formes courtes : (bool), (int), (float), (string). Les formes longues sont non documentées depuis des années ; 8.5 commence la suppression formelle.

Les instructions case terminées par un point-virgule sont dépréciées :

// déprécié
switch ($x) {
    case 1;
        break;
}

// correct
switch ($x) {
    case 1:
        break;
}

La forme avec point-virgule est syntaxiquement valide depuis PHP 4 mais personne ne l’utilise intentionnellement. C’est une faute de frappe que PHP acceptait.

__sleep() et __wakeup() sont dépréciés au profit de __serialize() et __unserialize(), qui retournent et reçoivent des tableaux et se composent correctement avec l’héritage. Les anciennes méthodes avaient une sémantique confuse autour de la visibilité des propriétés.

max_memory_limit plafonne les allocations incontrôlées

Une nouvelle directive INI accessible seulement au démarrage : max_memory_limit. Elle définit un plafond que memory_limit ne peut pas dépasser à l’exécution. Si un script appelle ini_set('memory_limit', '10G') et que max_memory_limit est à 512M, PHP avertit et plafonne la valeur.

Utile dans les environnements d’hébergement partagé, ou partout où on veut s’assurer qu’un bug ou un payload malveillant ne peut pas convaincre PHP d’élever sa propre limite et de dévorer toute la RAM de la machine.

Opcache est toujours présent

Dans 8.5, Opcache est toujours compilé dans le binaire PHP et toujours chargé. L’ancienne situation (Opcache comme extension chargeable qui pouvait ou non être présente selon la configuration de build) est révolue.

On peut toujours le désactiver : opcache.enable=0 fonctionne bien. Ce qui change, c’est la garantie que l’API Opcache (opcache_get_status(), opcache_invalidate(), etc.) est toujours disponible, quelle que soit la façon dont PHP a été compilé. Tout code qui vérifie extension_loaded('opcache') avant d’appeler les fonctions Opcache peut supprimer la vérification.

JSON streamer pour les grandes collections

Le serializer Symfony par défaut construit la réponse complète en mémoire avant de l’écrire dans la sortie. Pour une collection de 10 000 éléments, cela signifie allouer un tableau PHP, le sérialiser en string, et garder les deux en mémoire jusqu’au flush de la réponse. À grande échelle, c’est la source des erreurs OOM qui forcent à ajouter de la pagination partout.

La 4.2 ajoute un encodeur JSON en streaming qui écrit la réponse de façon incrémentale :

api_platform:
    serializer:
        enable_json_streamer: true

Avec le streaming activé, la réponse est écrite directement dans le buffer de sortie au fur et à mesure que chaque élément est sérialisé. L’utilisation mémoire reste approximativement constante quelle que soit la taille de la collection. La contrepartie : on ne peut pas définir de headers de réponse après le début du streaming, et le code de statut HTTP doit être validé avant que le premier octet soit écrit.

ObjectMapper remplace le câblage DTO manuel

La 3.1 avait introduit stateOptions avec DoctrineOrmOptions pour séparer la ressource API de l’entité Doctrine. Le provider recevait des objets entité et le serializer les mappait sur le DTO. Ça fonctionnait, mais le mapping était implicite — le serializer utilisait les noms de propriétés pour faire correspondre les champs, et tout ce qui ne correspondait pas était soit ignoré soit causait une erreur de normalisation.

La 4.2 introduit ObjectMapper, une couche de mapping déclarative entre entités et DTOs :

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    public string $title;
    public string $authorName;
}

L’attribut #[Map] indique à ObjectMapper que BookDto peut être peuplé depuis BookEntity. Les noms de champs sont mis en correspondance par convention ; les inadéquations sont déclarées explicitement au niveau de chaque propriété :

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    #[Map(source: 'author.fullName')]
    public string $authorName;
}

La notation pointée traverse les objets imbriqués. Le mapping s’exécute avant la sérialisation et remplace le comportement implicite de correspondance de propriétés du serializer. Les champs non mappés lèvent une erreur au moment de la configuration, pas à l’exécution.

ObjectMapper fonctionne avec stateOptions :

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
#[Map(source: BookEntity::class)]
class BookDto {}

Le provider récupère les objets BookEntity depuis Doctrine. ObjectMapper les convertit en instances BookDto. Le serializer écrit le DTO. Trois étapes distinctes, chacune avec un contrat clair.

Intégration TypeInfo dans toute la pile

Symfony 7.1 a introduit le composant TypeInfo , une couche unifiée d’introspection des types qui comprend les types union, intersection, les collections génériques et les types nullable à travers la reflection, PHPDoc et la syntaxe PHP 8.x.

La 4.2 remplace la résolution de types interne d’API Platform par TypeInfo. Cela affecte la génération de schémas de filtres, l’inférence de schéma OpenAPI, et la coercition de types du serializer. Le bénéfice visible est que les types qui généraient auparavant des schémas OpenAPI incorrects ou manquants — Collection<int, Book>, list<string>, types intersection — produisent maintenant des schémas précis sans annotations @ApiProperty manuelles.

Autoconfigure #[ApiResource]

Avant la 4.2, ajouter #[ApiResource] à une classe suffisait pour qu’Hugo la découvre uniquement si la classe était dans un chemin scanné par le chargeur de ressources d’API Platform. En dehors de ce chemin, une configuration de service explicite était nécessaire.

La 4.2 se branche sur le système d’autoconfigure de Symfony. Toute classe taguée avec #[ApiResource] est automatiquement enregistrée comme ressource indépendamment de son emplacement, tant qu’elle est dans un répertoire couvert par le scan de composants de Symfony. Aucune entrée dans config/services.yaml nécessaire.

Pour Laravel, l’équivalent utilise l’autoloading du service provider de Laravel — les modèles Eloquent avec #[ApiResource] sont récupérés automatiquement sans enregistrement manuel.

Doctrine ExistsFilter

L’ExistsFilter contraint une collection selon qu’une relation ou un champ nullable est défini :

#[ApiFilter(ExistsFilter::class, properties: ['publishedAt'])]
class Book {}

GET /books?exists[publishedAt]=true retourne les livres où publishedAt n’est pas null. exists[publishedAt]=false retourne les livres où il l’est.

Validation stricte des paramètres de requête

La 3.3 avait introduit la validation des paramètres de requête en opt-in. La 3.4 avait déprécié le comportement permissif. La 4.1 la formalise avec une propriété native strictQueryParameterValidation sur les ressources et opérations : quand elle est à true, les paramètres de requête inconnus renvoient 400.

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    strictQueryParameterValidation: true,
    parameters: [
        new QueryParameter(key: 'utm_source', required: false, schema: ['type' => 'string']),
        new QueryParameter(key: 'feature_flag', required: false, schema: ['type' => 'string']),
    ]
)]
class Book {}

Les paramètres déclarés passent ; les paramètres non déclarés sont rejetés. Pour désactiver la validation stricte sur une opération spécifique quand elle est activée au niveau de la ressource, passer strictQueryParameterValidation: false sur cette opération.

x-apiplatform-tag pour OpenAPI multi-spec

Les grandes APIs ont souvent besoin de plusieurs specs OpenAPI : une par équipe, une par version d’API, une interne et une publique. Avant la 4.1, la spec générée était un seul document, et la diviser nécessitait un post-traitement ou des instances API Platform séparées.

La 4.1 ajoute une extension vendor x-apiplatform-tag (sans s final). On tague les opérations avec des noms de groupes logiques via les extensionProperties d’un objet Operation OpenAPI, puis on demande la spec filtrée sur un ou plusieurs groupes :

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\OpenApi\Factory\OpenApiFactory;
use ApiPlatform\OpenApi\Model\Operation;

#[GetCollection(
    openapi: new Operation(
        extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['public', 'v2']]
    )
)]
class Book {}

Demander /api/docs.json?filter_tags[]=public retourne uniquement les opérations taguées public. La spec complète reste disponible sans filtre. Les groupes n’affectent pas le comportement réel de l’API — c’est uniquement une préoccupation de couche documentation.

Cela rend faisable de maintenir une configuration API Platform unique tout en servant différentes vues de spec à différents consommateurs : un Swagger UI public, un portail partenaire, et un outil interne qui expose les endpoints d’administration.

Authentification HTTP dans Swagger UI

Avant la 4.1, le Swagger UI fourni avec API Platform supportait l’authentification par token Bearer via son dialogue “Authorize”. L’authentification par clé API et HTTP Basic n’étaient pas câblées.

La 4.1 ajoute le support de plusieurs schémas de sécurité dans le document OpenAPI généré. Les schémas de sécurité sont ajoutés en décorant l’OpenApiFactory et en modifiant l’objet components.securitySchemes de la spec. Chaque schéma déclaré apparaît ensuite dans le dialogue “Authorize” de Swagger UI et est appliqué aux requêtes faites depuis l’UI. C’est une amélioration de la documentation et de l’expérience développeur — la logique d’authentification réelle dans votre application n’est pas affectée.

Limites de profondeur et complexité des requêtes GraphQL

La structure de requête récursive de GraphQL rend triviale la construction d’une requête petite en octets mais énorme en coût d’exécution. Sans limites, une requête imbriquée sur quatre niveaux à travers une relation many-to-many peut frapper la base de données des centaines de fois.

La 4.1 ajoute des limites configurables de profondeur et complexité :

api_platform:
    graphql:
        max_query_depth: 10
        max_query_complexity: 100

max_query_depth est le niveau d’imbrication maximum. max_query_complexity assigne un coût à chaque champ et rejette les requêtes dont le coût total dépasse le seuil. Les requêtes qui dépassent l’une ou l’autre limite sont rejetées avant exécution avec une réponse 400.

Il n’y a pas de valeur universellement correcte pour ces limites — elles dépendent de la forme de votre schéma et des patterns de requête attendus. Les valeurs par défaut sont intentionnellement permissives pour éviter de casser des APIs existantes lors de la mise à jour. Les resserrer est un choix de configuration délibéré.

Formats de sortie au niveau opération

La 4.0 et les versions antérieures configuraient les types de contenu acceptés et retournés au niveau de l’API. La 4.1 permet de les restreindre par opération :

use ApiPlatform\Metadata\GetCollection;

#[GetCollection(
    outputFormats: ['jsonld' => ['application/ld+json']],
    inputFormats: ['json' => ['application/json']],
)]
class Book {}

Les opérations qui ne spécifient pas de formats héritent de la configuration au niveau de l’API. C’est utile pour les endpoints qui doivent retourner un format spécifique (une export CSV, un flux binaire) sans changer les défauts pour le reste de l’API.

PostgreSQL embarque une recherche full-text depuis plus de quinze ans. La plateforme tournait déjà sous PostgreSQL. Le hic: le projet utilise Doctrine ORM, et Doctrine ne sait pas nativement ce qu’est un tsvector.

Une bibliothèque communautaire, postgresql-for-doctrine, couvre une partie de cette lacune. Elle enregistre des fonctions DQL basiques comme TO_TSQUERY, TO_TSVECTOR, et l’opérateur de correspondance @@ en tant que pièces atomiques séparées. La fondation était là. Trois choses restaient à construire par-dessus.

Le type que Doctrine n’a jamais vu

La recherche full-text de PostgreSQL repose sur deux types: tsvector (une liste pré-traitée de tokens normalisés) et tsquery (une expression de recherche). On maintient une colonne tsvector, on l’indexe avec GIN, et on interroge avec l’opérateur @@.

Le DBAL de Doctrine ne livre aucun type tsvector. Déclarer #[ORM\Column(type: 'tsvector')] sans l’enregistrer au préalable lève une UnknownColumnTypeException. La solution: un type DBAL personnalisé:

class TsVector extends Type
{
    final public const string DBAL_TYPE = 'tsvector';

    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return self::DBAL_TYPE;
    }

    public function getName(): string
    {
        return self::DBAL_TYPE;
    }

    public function convertToDatabaseValueSQL(string $sqlExpr, AbstractPlatform $platform): string
    {
        return sprintf("to_tsvector('simple', %s)", $sqlExpr);
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
    {
        if (is_array($value) && isset($value['data'])) {
            return $value['data'];
        }

        return is_string($value) ? $value : null;
    }

    public function getMappedDatabaseTypes(AbstractPlatform $platform): array
    {
        return [self::DBAL_TYPE];
    }
}

La méthode intéressante est convertToDatabaseValueSQL(). Doctrine l’appelle pour envelopper le placeholder SQL avant que la valeur n’atteigne la base de données. La valeur écrite devient automatiquement to_tsvector('simple', ?) à la frontière DBAL, sans étape supplémentaire côté appelant.

On enregistre le type dans doctrine.yaml, puis on mappe la colonne sur l’entité:

doctrine:
    dbal:
        types:
            tsvector: App\Doctrine\DBAL\Types\TsVector

#[ORM\Column(type: 'tsvector', nullable: true)]
protected ?string $textSearch = null;

Côté PHP, la valeur est une simple chaîne. La conversion en vrai tsvector se fait invisiblement au niveau DBAL.

Nous avons utilisé le dictionnaire 'simple', qui tokenise sur les espaces et la ponctuation sans stemming spécifique à une langue. La plateforme gère plusieurs langues, et les règles de stemming français auraient cassé l’espagnol. Simple suffit largement pour la phonétique.

Garder la colonne à jour

Une colonne tsvector est une donnée dérivée: elle doit rester synchronisée avec les champs source chaque fois que l’entité change. Un event listener Doctrine s’en charge:

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class MediaTsVectorSubscriber
{
    public function prePersist(PrePersistEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    public function preUpdate(PreUpdateEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    private function updateTextSearch(Media $entity): void
    {
        $entity->setTextSearch(
            sprintf('%s %s', $entity->getTitle(), $entity->getCaption())
        );
    }
}

Avant chaque persist et update, le subscriber concatène les champs qui doivent être recherchables dans textSearch. Doctrine flush la chaîne combinée, le type DBAL l’enveloppe dans to_tsvector('simple', ...), et PostgreSQL stocke la forme tokenisée.

Une subtilité: la valeur côté PHP est "title caption", pas la sortie tsvector réelle. La base affiche 'caption' 'title' (tokens triés), mais l’entité contient une chaîne brute. C’est attendu: la conversion est une responsabilité DBAL, pas PHP. Ça peut dérouter le débogage jusqu’à ce qu’on se souvienne où se situe la frontière.

Étendre DQL avec les opérateurs FTS

Le DQL de Doctrine couvre les opérations SQL courantes, mais tout ce qui est spécifique à PostgreSQL est hors périmètre. C’est là que postgresql-for-doctrine entre en jeu: il enregistre TO_TSQUERY, TO_TSVECTOR, et TSMATCH comme fonctions DQL individuelles. Écrire une requête full-text en DQL sans lui signifierait basculer en SQL natif.

Les fonctions de la bibliothèque sont atomiques, cependant. Chacune correspond à un appel SQL. Exprimer une vérification de correspondance complète en DQL ressemble à TSMATCH(o.textSearch, TO_TSQUERY(:term)). Assez lisible, mais l’équipe voulait quelque chose de plus compact: une seule fonction DQL encodant à la fois l’opérateur de correspondance et le type de requête, y compris websearch_to_tsquery que postgresql-for-doctrine ne fournissait pas.

La solution: des fonctions DQL personnalisées via FunctionNode. On parse la syntaxe DQL, puis on émet du SQL. Toutes les fonctions FTS partagent la même signature à deux arguments, donc une classe abstraite de base gère le parsing:

abstract class TsFunction extends FunctionNode
{
    public PathExpression|Node|null $ftsField = null;
    public PathExpression|Node|null $queryString = null;

    public function parse(Parser $parser): void
    {
        $parser->match(TokenType::T_IDENTIFIER);
        $parser->match(TokenType::T_OPEN_PARENTHESIS);
        $this->ftsField = $parser->StringPrimary();
        $parser->match(TokenType::T_COMMA);
        $this->queryString = $parser->StringPrimary();
        $parser->match(TokenType::T_CLOSE_PARENTHESIS);
    }
}

Chaque classe concrète implémente getSql() pour émettre son expression PostgreSQL:

// e.textSearch @@ websearch_to_tsquery('simple', :term)
class TsWebsearchQueryFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return $this->ftsField->dispatch($sqlWalker)
            ." @@ websearch_to_tsquery('simple', "
            .$this->queryString->dispatch($sqlWalker).')';
    }
}

// ts_rank(e.textSearch, to_tsquery(:term)) pour le tri par pertinence
class TsRankFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ts_rank('
            .$this->ftsField->dispatch($sqlWalker)
            .', to_tsquery('.$this->queryString->dispatch($sqlWalker).'))';
    }
}

doctrine:
    orm:
        entity_managers:
            default:
                dql:
                    string_functions:
                        tswebsearchquery: App\Doctrine\ORM\Query\AST\Functions\TsWebsearchQueryFunction
                        tsrank: App\Doctrine\ORM\Query\AST\Functions\TsRankFunction
                        tsquery: App\Doctrine\ORM\Query\AST\Functions\TsQueryFunction
                        tsplainquery: App\Doctrine\ORM\Query\AST\Functions\TsPlainQueryFunction

websearch_to_tsquery est le bon choix pour la recherche côté utilisateur: les espaces deviennent des AND, les chaînes entre guillemets deviennent des phrases, -mot exclut un terme. Inutile d’apprendre aux utilisateurs à taper interview & président. C’est disponible depuis PostgreSQL 11. Sur les versions antérieures, plainto_tsquery est l’équivalent le plus proche.

Le filtre API Platform et l’index GIN

Avec les fonctions DQL enregistrées, le filtre API Platform est simple. Un AbstractFilter personnalisé appelle directement la fonction DQL dans le QueryBuilder:

class TextSearchFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = []
    ): void {
        if ('textSearch' !== $property || empty($value)) {
            return;
        }

        $queryBuilder
            ->andWhere('tswebsearchquery(o.textSearch, :value) = true')
            ->setParameter(':value', $value);
    }

    public function getDescription(string $resourceClass): array
    {
        return [];
    }
}

On l’applique sur l’entité avec la déclaration d’index:

#[ORM\Index(
    columns: ['text_search'],
    name: 'media_text_search_idx_gin',
    options: ['USING' => 'gin (text_search)']
)]
#[ApiFilter(TextSearchFilter::class, properties: ['textSearch' => 'partial'])]
class Media
{
    // ...
    #[ORM\Column(type: 'tsvector', nullable: true)]
    protected ?string $textSearch = null;
}

L’option USING gin n’est pas négociable. Un index B-tree standard sur une colonne tsvector est inutile: PostgreSQL ne peut pas l’utiliser pour les requêtes @@. GIN (Generalized Inverted Index) fonctionne différemment: il indexe chaque token individuellement, donc les recherches par n’importe quel token sont en O(log n) plutôt que O(n). Sans ça, on a construit un système qui donne l’impression d’être rapide mais qui fait quand même un full table scan.

Un GET /media?textSearch=interview+president touche maintenant l’index GIN et répond en quelques millisecondes quel que soit la taille de la table.

Ce que la répartition ressemblait vraiment

La bibliothèque couvrait les fonctions atomiques bas niveau. Le code personnalisé couvrait les lacunes: un type DBAL tsvector que la bibliothèque ne fournissait pas, des wrappers DQL pratiques combinant @@ et websearch_to_tsquery en un seul appel, et la colle applicative reliant tout ça au système d’événements de Doctrine et à API Platform. Aucune requête native n’a été nécessaire.

La répartition vaut d’être notée en général: postgresql-for-doctrine donne les briques atomiques PostgreSQL, mais il faut quand même les composer en quelque chose que le reste du code peut utiliser sans y penser. Le pattern FunctionNode et le hook convertToDatabaseValueSQL() sont les deux points d’extension qui rendent cette composition propre. Les deux valent d’être connus, quelle que soit la bibliothèque de départ.

Les property hooks

Pendant vingt ans, si on voulait du comportement à l’accès d’une propriété en PHP, il fallait écrire des getters et setters :

class User {
    private string $_name;
    
    public function getName(): string { return $this->_name; }
    public function setName(string $name): void {
        $this->_name = strtoupper($name);
    }
}

PHP 8.4 ajoute des hooks directement sur la propriété :

class User {
    public string $name {
        set(string $name) {
            $this->name = strtoupper($name);
        }
    }
}

On peut définir les hooks get et set indépendamment. Une propriété avec seulement un hook get est calculée à l’accès :

class Circle {
    public float $area {
        get => M_PI * $this->radius ** 2;
    }
    
    public function __construct(public float $radius) {}
}

Pas de stockage backing, pas de méthode getter explicite, support IDE complet. Les interfaces peuvent aussi déclarer des propriétés avec des hooks, ce qui signifie que les contrats peuvent maintenant spécifier un comportement à l’accès aux propriétés, quelque chose qui était tout simplement impossible avant.

La visibilité asymétrique

Une option plus légère pour quand on veut juste une lecture publique et une écriture privée :

class Version {
    public private(set) string $value = '1.0.0';
}

$v = new Version();
echo $v->value;      // fonctionne
$v->value = '2.0';  // Error

Élimine le pattern private $x + public getX() pour les propriétés publiques en lecture seule sans avoir besoin de la sémantique readonly complète.

array_find() et amis

$first = array_find($users, fn($u) => $u->isActive());
$any   = array_any($users, fn($u) => $u->isPremium());
$all   = array_all($users, fn($u) => $u->isVerified());

Ces fonctions existent dans la bibliothèque standard de chaque autre langage depuis des décennies. En PHP, il fallait utiliser array_filter() + accès par index ou écrire une boucle manuelle. Elles existent maintenant : array_find(), array_find_key(), array_any(), array_all().

Instanciation sans parenthèses supplémentaires

// avant
(new MyClass())->method();

// après
new MyClass()->method();

Une restriction syntaxique qui était toujours agaçante et jamais justifiée est supprimée.

Les objets paresseux

Des objets dont l’initialisation est différée jusqu’au premier accès à une propriété :

$user = $reflector->newLazyProxy(fn() => $repository->find($id));
// Pas d'appel en base encore
$user->name; // Maintenant le proxy s'initialise

Le public direct est les auteurs de frameworks ORM et de conteneurs DI, pas les développeurs d’applications. Mais l’effet se fait sentir dans chaque application qui utilise Doctrine ou Symfony : le lazy loading implémenté au niveau du langage plutôt qu’à travers la génération de code.

PHP 8.4 est un langage qui ressemble à peine au PHP 5 avec lequel la plupart d’entre nous avons commencé. Les property hooks en particulier : ce ne sont pas des contournements, ce sont une fonctionnalité de conception.

#[\Deprecated] pour son propre code

PHP émet des notices de dépréciation pour les fonctions intégrées depuis des années. 8.4 permet de câbler le même mécanisme dans son propre code :

class ApiClient {
    #[\Deprecated(
        message: 'Use fetchJson() instead',
        since: '2.0',
    )]
    public function get(string $url): string { ... }
}

Appeler une méthode dépréciée émet maintenant E_USER_DEPRECATED, exactement comme appeler mysql_connect(). Les IDEs le détectent, les analyseurs statiques le signalent, le log d’erreurs le capture. Avant ça, la seule option était un commentaire PHPDoc @deprecated : bien pour les IDEs, complètement invisible pour le moteur.

BcMath\Number rend la précision arbitraire utilisable

Les fonctions bcmath existent en PHP depuis toujours, mais leur API procédurale rend tout chaînage pénible. 8.4 ajoute BcMath\Number, un wrapper objet avec surcharge d’opérateurs :

$a = new BcMath\Number('10.5');
$b = new BcMath\Number('3.2');

$result = $a + $b;             // BcMath\Number('13.7')
$result = $a * $b - new BcMath\Number('1');
echo $result;                  // 32.6

Les opérateurs +, -, *, /, **, % fonctionnent tous. L’objet est immutable. L’échelle se propage automatiquement à travers les opérations. Les calculs financiers, qui nécessitaient des chaînes de bcadd(bcmul(...), ...), se lisent maintenant comme de l’arithmétique.

De nouvelles fonctions procédurales complètent le tableau : bcceil(), bcfloor(), bcround(), bcdivmod().

L’enum RoundingMode remplace les constantes PHP_ROUND_*

round() a toujours pris un $mode entier depuis un ensemble de constantes PHP_ROUND_*. 8.4 les remplace par un enum RoundingMode avec des noms plus propres et quatre modes supplémentaires qui n’étaient pas disponibles avant :

round(2.5, mode: RoundingMode::HalfAwayFromZero);  // 3
round(2.5, mode: RoundingMode::HalfTowardsZero);   // 2
round(2.5, mode: RoundingMode::HalfEven);          // 2 (arrondi du banquier)
round(2.5, mode: RoundingMode::HalfOdd);           // 3

// Les quatre nouveaux modes (disponibles uniquement via l'enum)
round(2.3, mode: RoundingMode::TowardsZero);       // 2
round(2.7, mode: RoundingMode::AwayFromZero);      // 3
round(2.3, mode: RoundingMode::PositiveInfinity);  // 3
round(2.3, mode: RoundingMode::NegativeInfinity);  // 2

Les anciennes constantes PHP_ROUND_* fonctionnent encore. L’enum est la voie à suivre.

Les fonctions de string multibyte qui auraient dû exister

mb_trim(), mb_ltrim(), mb_rtrim() : des fonctions de trim qui respectent les frontières de caractères multibyte, pas juste les espaces ASCII. Aussi nouvelles : mb_ucfirst() et mb_lcfirst() pour la mise en majuscule correcte des strings multibyte.

$s = "\u{200B}hello\u{200B}"; // Espaces de largeur nulle
echo mb_trim($s);              // "hello"
echo mb_ucfirst('über');       // "Über"

Ces fonctions comblent des lacunes présentes depuis que mbstring a été introduit.

request_parse_body() pour les requêtes non-POST

PHP parse automatiquement application/x-www-form-urlencoded et multipart/form-data dans $_POST et $_FILES, mais seulement pour les requêtes POST. Les requêtes PATCH et PUT avec les mêmes types de contenu nécessitaient un parsing manuel avec file_get_contents('php://input') et du code personnalisé.

// Dans un handler PATCH
[$_POST, $_FILES] = request_parse_body();

La fonction retourne un tuple. Même logique de parsing que PHP utilise pour POST, maintenant disponible pour n’importe quelle méthode HTTP.

Une nouvelle API DOM qui suit la spec

L’API DOMDocument existante était construite sur une spec DOM level 3 plus ancienne avec des spécificités PHP superposées. 8.4 ajoute un namespace Dom\ parallèle qui implémente le WHATWG Living Standard :

$doc = Dom\HTMLDocument::createFromString('<p class="lead">Hello</p>');
$p = $doc->querySelector('p');
echo $p->classList;  // "lead"
echo $p->id;         // ""

$doc2 = Dom\HTMLDocument::createFromFile('page.html');

Dom\HTMLDocument parse correctement HTML5, tag soup inclus. Dom\XMLDocument gère le XML strict. Les nouvelles classes sont strictes sur les types, retournent les bons types de nœuds, et exposent des propriétés modernes comme classList, id, className. L’ancien DOMDocument reste, inchangé, pour la compatibilité ascendante.

PDO reçoit des sous-classes spécifiques au driver

PDO::connect() et l’instanciation directe retournent maintenant des sous-classes spécifiques au driver quand elles sont disponibles :

$pdo = PDO::connect('mysql:host=localhost;dbname=test', 'user', 'pass');
// $pdo est maintenant une instance Pdo\Mysql

$pdo = new Pdo\Pgsql('pgsql:host=localhost;dbname=test', 'user', 'pass');

Chaque sous-classe driver (Pdo\Mysql, Pdo\Pgsql, Pdo\Sqlite, Pdo\Firebird, Pdo\Odbc, Pdo\DbLib) peut exposer des méthodes spécifiques au driver sans polluer l’interface PDO de base. Doctrine, Laravel et autres ORMs similaires peuvent maintenant type-hinter contre la classe de driver spécifique quand ils ont besoin d’un comportement spécifique au driver.

OpenSSL reçoit le support des clés modernes

openssl_pkey_new() et les fonctions associées supportent maintenant Curve25519 et Curve448, les courbes elliptiques modernes qui ont remplacé les anciennes courbes NIST dans la plupart des recommandations de sécurité :

$key = openssl_pkey_new(['curve_name' => 'ed25519', 'private_key_type' => OPENSSL_KEYTYPE_EC]);
$details = openssl_pkey_get_details($key);

x25519 et x448 pour l’échange de clés, ed25519 et ed448 pour les signatures. Les quatre fonctionnent maintenant avec openssl_sign() et openssl_verify().

PCRE : lookbehind de longueur variable

La mise à jour de la bibliothèque PCRE2 embarquée (10.44) apporte les assertions lookbehind de longueur variable, quelque chose que les moteurs regex de Perl et Python avaient et que PHP ne pouvait pas faire :

// Correspondre "bar" seulement quand précédé de "foo" ou "foooo"
preg_match('/(?<=foo+)bar/', 'foooobar', $matches);

Les assertions lookbehind nécessitaient auparavant un pattern de largeur fixe. Elles peuvent maintenant correspondre à des patterns de longueur variable. Le modificateur r (PCRE2_EXTRA_CASELESS_RESTRICT) est aussi nouveau : il empêche le mélange de caractères ASCII et non-ASCII dans les correspondances insensibles à la casse, fermant une classe d’attaques de confusion Unicode.

DateTime reçoit les microsecondes et une factory de timestamp

$dt = DateTimeImmutable::createFromTimestamp(1700000000.5);
echo $dt->getMicrosecond(); // 500000

$with_micros = $dt->setMicrosecond(123456);

createFromTimestamp() accepte un float pour une précision sous-seconde. getMicrosecond() et setMicrosecond() complètent l’API pour le composant microseconde qui était à l’intérieur de DateTime mais inaccessible directement.

fpow() pour la conformité IEEE 754

pow(0, -2) en PHP retournait historiquement une valeur définie par l’implémentation. 8.4 déprécie pow() avec une base zéro et un exposant négatif et introduit fpow(), qui suit strictement IEEE 754 : fpow(0, -2) retourne INF, comme le standard le définit :

echo fpow(2.0, 3.0);   // 8.0
echo fpow(0.0, -1.0);  // INF
echo fpow(-1.0, INF);  // 1.0

À retenir dans tout code faisant des calculs mathématiques où la conformité IEEE compte.

Le coût de bcrypt augmente

Le coût par défaut pour password_hash() avec PASSWORD_BCRYPT est passé de 10 à 12. Ça impacte tout code appelant password_hash($pass, PASSWORD_BCRYPT) sans coût explicite. L’objectif est de maintenir le défaut grossièrement à “quelques centaines de millisecondes sur du matériel moderne” à mesure que le matériel devient plus rapide.

Si on stocke des hash bcrypt et qu’on monte sur 8.4, les hash existants restent valides : password_verify() lit le coût depuis le hash lui-même. Les nouveaux hash utilisent le coût 12. password_needs_rehash() retourne true pour les anciens hash si on passe ['cost' => 12], donc on peut les mettre à jour à la prochaine connexion.

Les dépréciations qui comptent

Les paramètres implicitement nullable sont dépréciés. Si un paramètre a un défaut de null, le type doit le dire explicitement :

// Déprécié dans 8.4
function foo(string $s = null) {}

// Correct
function foo(?string $s = null) {}
function foo(string|null $s = null) {}

trigger_error() avec E_USER_ERROR est déprécié : le remplacer par une exception ou exit(). Le niveau E_USER_ERROR a toujours été un hybride maladroit entre une erreur récupérable et une erreur fatale, et personne n’était sûr lequel.

lcg_value() est aussi déprécié. Utiliser Random\Randomizer::getFloat() à la place. Le générateur LCG avait de mauvaises propriétés d’aléatoire et aucun contrôle de graine.

Laravel comme cible de première classe

Depuis sa première release, API Platform était construit sur Symfony. La couche HTTP, les métadonnées, le serializer et le bridge Doctrine supposaient tous le container de Symfony, l’event dispatcher et le cycle de vie des requêtes. Les utilisateurs Laravel pouvaient faire tourner API Platform via un adaptateur léger, mais les filtres, la sécurité et l’intégration Doctrine ne fonctionnaient pas avec Eloquent.

La 4.0 livre un bridge Laravel dédié. Il mappe la couche d’état d’API Platform sur le cycle de vie des requêtes de Laravel, s’intègre directement avec les modèles Eloquent, et se branche sur le système d’autorisation de Laravel :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(
    operations: [new GetCollection(), new Get()]
)]
class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

L’autorisation utilise les policies et gates de Laravel plutôt que les security voters de Symfony. Les opérations exposent un paramètre policy dédié qui correspond à un nom de méthode de policy :

#[Get(policy: 'view')]
class Book extends Model {}

API Platform mappe la valeur de policy vers Gate::allows() de Laravel avec l’instance du modèle. Les policies peuvent aussi être auto-détectées : si un modèle a une classe de policy enregistrée, API Platform infère la bonne méthode (view, viewAny, create, update, delete) selon le type d’opération. Les filtres pour les collections Eloquent couvrent le même périmètre que leurs homologues Doctrine : PartialSearchFilter, EqualsFilter, RangeFilter, OrderFilter, DateFilter, et des variantes de recherche (StartSearchFilter, EndSearchFilter). La pagination, le tri et la validation fonctionnent via les mécanismes natifs de Laravel.

Ce n’est pas un shim de compatibilité. Le bridge Laravel est maintenu aux côtés du bridge Symfony et est couvert par la même suite de tests. Les projets utilisant l’un ou l’autre framework ont la même API de définition des ressources.

PUT supprimé des opérations par défaut

Depuis API Platform 1.0, #[ApiResource] sans tableau operations explicite générait des opérations CRUD incluant PUT. Le handler PUT mettait à jour les ressources existantes et, depuis la 3.1, pouvait aussi les créer via allowCreate: true.

La 4.0 supprime PUT de l’ensemble par défaut. #[ApiResource] génère maintenant GET, POST, PATCH et DELETE. Pour utiliser PUT, il faut le déclarer explicitement :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Put;

#[ApiResource(
    operations: [
        // ... autres opérations
        new Put(),
    ]
)]
class Book {}

La motivation est la clarté sémantique. PATCH remplace PUT pour la plupart des cas d’usage de mise à jour partielle. La sémantique de PUT — remplacer la représentation entière de la ressource — est rarement ce qu’une API implémente réellement, mais le défaut le faisait apparaître dans toutes les APIs à moins de l’enlever activement. Rendre PUT opt-in aligne les défauts sur la façon dont la sémantique HTTP est réellement utilisée en pratique.

PHP 8.2 minimum

La 4.0 abandonne PHP 8.0 et 8.1. PHP 8.2 est le nouveau minimum. La syntaxe de classe readonly, AllowDynamicProperties et les types DNF¹ introduits en 8.2 sont disponibles dans toute la codebase. Aucune fonctionnalité spécifique de 8.2 n’est structurante pour la 4.0 — le bump de version concerne principalement l’abandon du fardeau de maintenance plus ancien.

Symfony 6.4+ et Doctrine ORM 2.17+ minimum

Côté Symfony, la 4.0 requiert Symfony 6.4 ou 7.x et Doctrine ORM 2.17 ou 3.x. Les deux étaient déjà supportés en 3.4. La migration de la 3.4 vers la 4.0 sur la piste Symfony est : résoudre les dépréciations 3.4, vérifier qu’on est sur Symfony 6.4+ et ORM 2.17+, puis mettre à jour. Aucun travail de migration supplémentaire n’est nécessaire si c’est déjà en place.

Ce que la 4.0 n’est pas

La 4.0 n’est pas une nouvelle architecture. Les state providers, processors et le modèle de métadonnées de ressources de la 3.0 sont inchangés. Le bridge Laravel ajoute un nouveau contexte d’exécution mais ne change pas la façon dont les ressources ou les opérations sont déclarées. La séparation est intentionnelle : si la 3.0 était le “quoi”, la 4.0 est le “où”.

BackedEnum comme ressources API

Depuis PHP 8.1, les classes BackedEnum ont un ensemble fixe de cas avec des valeurs de support string ou integer. API Platform 3.4 permet de mettre #[ApiResource] directement sur un BackedEnum :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [new GetCollection()]
)]
enum BookStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

Un endpoint GET /book_statuses retourne la liste des cas. Chaque cas est sérialisé avec son nom et sa valeur. L’endpoint est en lecture seule — les enums sont immuables par nature.

C’est surtout utile pour les consommateurs frontend qui veulent une liste lisible par machine des valeurs valides sans les coder en dur. L’alternative était un contrôleur personnalisé ou une ressource DTO dédiée listant manuellement les valeurs de l’enum.

BackedEnumFilter

Le compagnon des ressources enum est BackedEnumFilter, un nouveau filtre pour les collections Doctrine qui contraint une requête par une propriété BackedEnum :

use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
#[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
class Book
{
    public BookStatus $status;
}

GET /books?status=published filtre la collection aux livres où status est égal à BookStatus::Published. Les valeurs d’enum invalides retournent une réponse 400. Avant ce filtre, on devait soit écrire un filtre personnalisé, soit utiliser SearchFilter et valider la valeur manuellement.

Expressions de sécurité sur les paramètres

La 3.3 avait ajouté la sécurité aux liens et aux propriétés. La 3.4 étend cela aux paramètres de requête. Un paramètre peut déclarer une expression de sécurité qui contrôle s’il est accepté :

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    parameters: [
        new QueryParameter(
            key: 'includeDeleted',
            security: "is_granted('ROLE_ADMIN')"
        ),
    ]
)]
class Book {}

Quand l’expression de sécurité est false, le paramètre est rejeté avec un 403, pas silencieusement ignoré. C’est plus explicite que vérifier le rôle de l’utilisateur dans le provider après avoir reçu le paramètre.

Support DBAL 4 ajouté

La 3.4 ajoute le support de Doctrine DBAL 4, qui apporte des changements au système de types qui affectent la façon dont les types personnalisés et le SQL spécifique à la plateforme fonctionnent. Les filtres Doctrine Orm et les extensions de requête dans API Platform ont été mis à jour pour fonctionner avec la nouvelle API de types DBAL 4.

DBAL 3 (^3.4.0) et DBAL 4 sont supportés simultanément en 3.4. C’est la release à adopter pour migrer vers DBAL 4 tout en restant sur une branche stable API Platform 3.x.

Validateur de paramètres de requête déprécié

La 3.3 avait ajouté le validateur strict de paramètres de requête en opt-in. La 3.4 déprécie l’ancien comportement (paramètres inconnus silencieusement ignorés) en préparation pour rendre la validation stricte la valeur par défaut en 4.0. Les projets qui s’appuient sur des paramètres de requête pass-through ont une release de plus pour les déclarer explicitement.

Dernier arrêt avant la 4.0

La 3.4 est la dernière release 3.x avec de nouvelles fonctionnalités. Tout ce qui était déprécié d’ici la 3.4 disparaît en 4.0. Le chemin de migration de la 3.4 vers la 4.0 est intentionnellement court : résoudre les dépréciations, puis mettre à jour.

Configuration déclarative des headers

Avant la 3.3, définir des headers de réponse personnalisés nécessitait soit un processor personnalisé qui modifiait l’objet réponse, soit un event listener Symfony sur kernel.response. Les deux approches fonctionnaient mais vivaient en dehors de la définition de la ressource.

La 3.3 ajoute un paramètre parameters aux métadonnées d’opération :

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\HeaderParameter;

#[Get(
    parameters: [
        'X-Custom-Header' => new HeaderParameter(description: 'A custom header'),
    ]
)]

Pour les headers qui varient par réponse (comme Cache-Control avec un max-age calculé), le processor peut encore les définir directement sur l’objet réponse. Le paramètre parameters sert principalement à documenter les headers attendus dans la spec OpenAPI et pour les valeurs de headers statiques.

Sécurité des liens sur les sous-ressources

Quand une ressource expose des liens vers des ressources liées, ces liens apparaissent dans la sortie sérialisée indépendamment du fait que l’utilisateur courant puisse accéder à la ressource liée. Cela crée un problème de divulgation : un utilisateur qui peut lire un livre mais pas le profil de son auteur voit quand même l’URI de l’auteur dans la réponse.

La 3.3 ajoute des expressions de sécurité au descripteur Link :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Link;

#[ApiResource]
#[Get]
class Book
{
    #[Link(
        toClass: Author::class,
        security: "is_granted('ROLE_ADMIN')"
    )]
    public Author $author;
}

Le lien est omis de la réponse quand l’expression de sécurité évalue à false. La ressource liée elle-même n’est pas affectée — seulement le fait que la réponse courante inclue la référence à elle.

ApiProperty::security

Le même mécanisme d’expression de sécurité est disponible au niveau propriété via ApiProperty::security. Cela permet de cacher des champs individuels selon l’utilisateur courant sans écrire un normalizer personnalisé :

use ApiPlatform\Metadata\ApiProperty;

class Book
{
    #[ApiProperty(security: "is_granted('ROLE_ADMIN')")]
    public string $internalNote;
}

La propriété est exclue de la sérialisation quand l’expression est false. C’est plus propre qu’un normalizer pour le cas courant de champs conditionnels par rôle.

Webhooks OpenAPI

OpenAPI 3.1 supporte les webhooks — des appels HTTP sortants que votre API fait à des listeners enregistrés — dans le document spec lui-même. Avant la 3.3, il n’y avait pas de moyen de les documenter dans la spec générée par API Platform.

La 3.3 ajoute une classe Webhook à passer au paramètre openapi d’une opération. On déclare une classe PHP dédiée avec #[ApiResource] et on utilise Webhook sur chaque opération pour décrire la forme de l’appel sortant :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Attributes\Webhook;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\PathItem;

#[ApiResource(
    operations: [
        new Post(
            openapi: new Webhook(
                name: 'bookCreated',
                pathItem: new PathItem(
                    post: new Operation(summary: 'Un livre a été créé'),
                ),
            )
        ),
    ]
)]
class BookWebhook {}

Les définitions de webhooks apparaissent dans la spec générée sous la clé webhooks aux côtés des paths réguliers. Swagger UI les affiche dans une section séparée.

Deep linking dans Swagger UI

Swagger UI supporte le deep linking — des URLs mémorisables qui ouvrent directement sur une opération spécifique dans l’interface. Avant la 3.3, l’intégration API Platform n’activait pas cela. La 3.3 active l’option deepLinking de Swagger UI, configurable via swagger_ui_extra_configuration :

api_platform:
    openapi:
        swagger_ui_extra_configuration:
            deepLinking: true

Avec cette option activée, le fragment d’URL se met à jour pendant la navigation dans l’UI, et coller ou partager l’URL ouvre la même opération. Utile quand on écrit de la doc qui pointe directement vers un endpoint spécifique.

Validation stricte des paramètres de requête

La 3.3 renforce le validateur de paramètres de requête : les paramètres non déclarés sur l’opération renvoient maintenant une réponse 400 au lieu d’être silencieusement ignorés. Ce comportement est opt-in :

api_platform:
    validator:
        query_parameter_validation: true

L’intention est de détecter les fautes de frappe et les mauvaises utilisations de l’API tôt. Si vous vous appuyez sur des paramètres de requête pass-through pour une logique personnalisée (logging, feature flags), vous devez les déclarer explicitement sur l’opération avant d’activer cela.

Les constantes de classe typées

Les constantes de classe n’ont jamais été typées depuis leur introduction. PHP 8.3 corrige ça :

interface HasVersion {
    const string VERSION;
}

class App implements HasVersion {
    const string VERSION = '1.0.0';
}

Sans constantes typées, une constante d’interface pouvait être redéfinie avec un type complètement différent dans une classe implémentante sans que rien ne se plaigne. Les constantes typées comblent ce trou, et sur les bases de code pilotées par les interfaces, l’impact est immédiat.

L’accès dynamique aux constantes de classe

Une lacune qui nécessitait un contournement depuis que les constantes existent :

$name = 'STATUS';
echo MyClass::{$name}; // ça marche maintenant

Avant, accéder à une constante avec un nom dynamique signifiait appeler constant('MyClass::STATUS'). La nouvelle syntaxe est cohérente avec la façon dont PHP gère déjà les variables variables et les appels de méthodes dynamiques.

readonly peut maintenant être modifié dans clone

Une limitation spécifique mais vraiment agaçante de 8.1 avec readonly : on ne pouvait pas cloner un objet et changer une propriété readonly. 8.3 ajoute la possibilité de réinitialiser les propriétés readonly pendant le clonage, ce qui rend les value objects immuables utilisables dans beaucoup plus de patterns.

json_validate()

if (json_validate($string)) {
    $data = json_decode($string);
}

Avant 8.3, la seule façon de valider une chaîne JSON était de la décoder et de vérifier les erreurs. json_validate() vérifie sans allouer la structure décodée, ce qui compte quand on a juste besoin de savoir si la chaîne est du JSON valide, pas ce qu’elle contient.

Améliorations du Randomizer

getBytesFromString() génère une chaîne aléatoire composée uniquement de caractères d’un ensemble donné :

$rng = new Random\Randomizer();
$token = $rng->getBytesFromString('abcdefghijklmnopqrstuvwxyz0123456789', 32);

L’approche précédente : str_split, array_map, sélection aléatoire, implode. Ça marchait, mais c’était plus long que ça n’avait le droit d’être.

8.3 est pour les équipes qui adoptent les versions PHP rapidement et veulent les améliorations incrémentales. Les constantes typées seules valent le coup sur toute base de code avec des constantes d’interface.

#[\Override] rend l’héritage explicite

Avant 8.3, rien n’empêchait d’écrire une méthode qu’on croyait surcharger celle d’un parent, alors qu’on avait un typo dans le nom ou que le parent l’avait silencieusement supprimée. Des bugs silencieux, zéro retour du moteur.

class Cache {
    #[\Override]
    public function get(string $key): mixed {
        // Le moteur vérifie que cette méthode existe dans un parent ou une interface
    }
}

Si la méthode n’existe dans aucune classe parente ou interface implémentée, PHP lève une erreur. Même concept que @Override en Java ou override en C#, enfin en PHP.

final sur les méthodes de trait

Les traits ont toujours eu des aspérités dans le modèle OOP de PHP. Un problème spécifique : une classe utilisant un trait pouvait surcharger n’importe laquelle de ses méthodes, sapant les garanties que le trait essayait de fournir. 8.3 laisse le trait lui-même marquer une méthode comme final :

trait Singleton {
    final public static function getInstance(): static {
        // ...
    }
}

Maintenant, une classe utilisant le trait ne peut pas surcharger getInstance(). La garantie tient.

Les classes anonymes peuvent être readonly

PHP 8.1 avait apporté les classes readonly. Les classes anonymes avaient été laissées de côté pour une raison obscure. 8.3 corrige ça :

$point = new readonly class(3, 4) {
    public function __construct(
        public float $x,
        public float $y,
    ) {}
};

Pratique quand on a besoin d’un value object immuable jetable sans la cérémonie de lui donner un nom.

Les initialiseurs de variables statiques acceptent des expressions

Une restriction petite mais ancienne : les initialiseurs de variables statiques n’acceptaient que des expressions constantes, pas d’appels de fonctions. 8.3 lève cette contrainte :

function connection(): PDO {
    static $pdo = new PDO(getenv('DATABASE_URL'));
    return $pdo;
}

L’initialiseur s’exécute une seule fois au premier appel, la variable statique persiste. Faisable avec un test null avant, c’est juste plus propre.

mb_str_pad() existe enfin

str_pad() a toujours été conscient des octets, pas des caractères. Pour les chaînes multibyte (arabe, japonais, caractères accentués) il produisait une sortie incorrecte. 8.3 ajoute enfin la variante multibyte :

$padded = mb_str_pad('日本', 10, '*', STR_PAD_BOTH);

La fonction respecte les limites de caractères, pas les comptages d’octets.

str_increment() et str_decrement()

L’opérateur ++ de PHP sur les chaînes a une histoire de bizarreries : il incrémente les séquences de lettres ('a' → 'b', 'z' → 'aa'), mais -- n’a jamais fonctionné symétriquement. Le comportement était suffisamment surprenant que 8.3 déprécie ++/-- sur les chaînes non alphanumériques et introduit des fonctions explicites :

echo str_increment('a');  // b
echo str_increment('Az'); // Ba
echo str_decrement('b');  // a
echo str_decrement('Ba'); // Az

Les fonctions rendent l’intention évidente et le comportement prévisible.

Random\Randomizer gagne le support des flottants

8.3 comble le côté flottant de l’API Randomizer :

$rng = new Random\Randomizer();

// Un flottant dans [0.0, 1.0)
$f = $rng->nextFloat();

// Un flottant dans une plage spécifique avec contrôle de l'inclusion des bornes
$f = $rng->getFloat(1.5, 3.5, Random\IntervalBoundary::ClosedOpen);

IntervalBoundary est un nouvel enum avec quatre valeurs : ClosedOpen, ClosedClosed, OpenClosed, OpenOpen. C’est important pour la justesse statistique : l’approche naïve avec rand() / getrandmax() ne produit pas une distribution uniforme sur les flottants.

La hiérarchie d’exceptions de Date

Les erreurs de date/heure en PHP levaient des exceptions génériques sans moyen de distinguer “chaîne malformée” de “timezone invalide” sans parser le message. 8.3 ajoute une hiérarchie propre :

try {
    new DateTimeImmutable('not a date');
} catch (DateMalformedStringException $e) {
    // spécifiquement un échec de parsing
} catch (DateException $e) {
    // autres erreurs liées aux dates
}

L’arbre complet : DateError (niveau moteur), DateException (base), avec des sous-classes spécifiques pour timezone invalide, chaîne d’intervalle malformée, chaîne de période malformée, et chaîne de date malformée.

gc_status() en dit plus

gc_status() retourne maintenant huit champs supplémentaires : running, protected, full, buffer_size, et des décompositions temporelles (application_time, collector_time, destructor_time, free_time). Si vous profilez la pression mémoire ou les pauses GC, ces données étaient auparavant inaccessibles sans passer par une extension.

strrchr() gagne un argument de direction

strrchr() (trouver la dernière occurrence d’un caractère, retourner de là jusqu’à la fin) accepte maintenant un booléen $before_needle, alignant son API sur celle de strstr() :

$path = '/var/www/html/index.php';
echo strrchr($path, '/', before_needle: true);  // /var/www/html
echo strrchr($path, '/');                        // /index.php

Une fonction présente dans PHP depuis 1994, enfin cohérente avec sa voisine.

Dépréciations à noter

get_class() et get_parent_class() sans arguments émettent maintenant des avertissements de dépréciation. Les formes sans argument reposaient sur un contexte $this implicite, facile à mal lire. Passez l’objet explicitement.

assert_options() et les constantes ASSERT_* sont dépréciées au profit de la directive INI zend.assertions, qui est le bon outil pour contrôler le comportement des assertions selon les environnements.

Les opérateurs ++/-- sur les chaînes vides et les chaînes non numériques non alphanumériques émettent maintenant des avertissements de dépréciation. Le comportement était un territoire indéfini. 8.3 amorce la migration vers un comportement défini en 9.0.

Protection contre les débordements de pile

Deux nouvelles directives INI : zend.max_allowed_stack_size fixe une limite dure sur la profondeur de pile de PHP, et zend.reserved_stack_size réserve un buffer pour le nettoyage après qu’une limite soit atteinte. Avant 8.3, un code récursif profond pouvait tout simplement crasher au niveau OS. Maintenant PHP l’intercepte et lève une Error avec un message utile.

Les erreurs comme ressources

Avant la 3.2, la gestion des erreurs était en dehors du modèle de ressources. Les exceptions étaient interceptées par un event listener Symfony et converties en réponse, avec un contrôle limité sur la forme de la sortie.

La 3.2 fait des erreurs des classes ApiResource de première classe conformes à la RFC 9457 (Problem Details for HTTP APIs). La classe d’erreur intégrée est ApiPlatform\ApiResource\Error, et on peut créer la sienne :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ApiResource]
#[ErrorResource]
class BookNotFoundError extends \RuntimeException implements ProblemExceptionInterface
{
    public function __construct(private readonly string $bookId)
    {
        parent::__construct("Book $bookId not found");
    }

    public function getType(): string
    {
        return '/errors/book-not-found';
    }
}

Quand cette exception est levée n’importe où dans la couche d’état, API Platform l’intercepte, la sérialise comme une réponse Problem Detail, et génère un schéma OpenAPI approprié pour elle. Le type d’erreur, le titre, le détail et le statut font tous partie du contrat de la ressource — pas des chaînes codées en dur dans un listener.

Les sous-ressources sans les contournements

Les sous-ressources existaient en 2.x mais ont été supprimées en 3.0 parce qu’elles étaient étroitement couplées à l’ancien modèle de data provider et ne pouvaient pas être proprement mappées à la nouvelle architecture orientée opération. La 3.2 les réintroduit d’une façon qui s’intègre.

Une sous-ressource est une ressource accessible via l’URI d’une ressource parente. En 3.2, elle est déclarée directement sur la ressource enfant en utilisant uriTemplate :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: [
                'bookId' => new Link(fromClass: Book::class),
            ],
        ),
    ]
)]
class Review
{
    // ...
}

Le descripteur Link rend la relation explicite. Le provider reçoit bookId dans $uriVariables et peut l’utiliser pour délimiter la requête. Pas d’inférence magique, pas de jointures implicites — la structure d’URI et l’accès aux données sont tous les deux déclarés.

canonical_uri_template pour plusieurs chemins d’accès

Quand une ressource est accessible via plusieurs URI (un endpoint direct et un endpoint de sous-ressource), OpenAPI doit savoir quelle URI est canonique pour les liens $ref. La 3.2 utilise le uriTemplate de niveau supérieur sur ApiResource comme URI canonique par défaut. Pour plus de contrôle, l’option canonical_uri_template peut être passée via extraProperties sur n’importe quelle opération pour la définir explicitement.

#[ApiResource(
    uriTemplate: '/reviews/{id}',
    operations: [
        new Get(),
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: ['bookId' => new Link(fromClass: Book::class)],
        ),
    ]
)]
class Review {}

La spec OpenAPI générée utilise l’URI canonique pour les références de schéma, gardant le document cohérent quand une ressource apparaît sous plusieurs chemins.

Types union et intersection

La 3.2 ajoute le support des types union et intersection PHP dans la couche de métadonnées. Une propriété déclarée comme Book|Magazine génère un schéma oneOf approprié dans OpenAPI. C’était auparavant non supporté — on devait tomber sur un mixed non typé ou annoter la propriété manuellement.

Les event listeners rendus optionnels

Le dernier shim de compatibilité venu de la 2.x était la possibilité d’utiliser les event listeners Symfony sur les événements kernel.request et kernel.view pour intercepter le flux de données d’API Platform. La 3.2 ne les supprime pas, mais introduit un moyen de s’en passer : passer event_listeners_backward_compatibility_layer: false dans la configuration d’API Platform désactive entièrement les hooks basés sur les événements. Le remplacement est un provider ou processor décoré par un autre provider ou processor. Le hook basé sur les événements était avec état, dépendant de l’ordre, et court-circuitait entièrement le contexte d’opération. Les providers décorés reçoivent l’objet opération et peuvent appeler le provider interne quand ils sont prêts.

Le modèle d’état est maintenant complet

La 3.0 a introduit l’architecture. La 3.1 a ajouté la séparation ressource/entité. La 3.2 ferme les lacunes restantes : les erreurs ont un contrat de ressource, les sous-ressources ont un modèle de déclaration propre, et la couche d’état couvre désormais tous les points d’extension que les event listeners géraient autrefois. Les shims 2.x existent encore, mais s’en passer n’est plus qu’une ligne de configuration.

La séparation ressource/entité

En 2.x, API Platform fonctionnait mieux quand votre ressource API et votre modèle de persistance étaient la même classe. Utiliser un DTO comme surface API était possible via le système Input/Output DTO, mais ce système a été supprimé en 3.0 — il compliquait le modèle d’état sans apporter suffisamment de bénéfices.

La 3.1 le remplace par quelque chose de plus propre. Le paramètre stateOptions d’une opération accepte un objet DoctrineOrmOptions qui pointe vers une entité différente :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\State\Options;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
class BookDto
{
    public string $title;
    public string $author;
}

Le provider reçoit les objets BookEntity de Doctrine et la couche de sérialisation les mappe sur BookDto. Les filtres Doctrine, la pagination et le tri fonctionnent tous sur BookEntity. La surface API expose BookDto. Les deux peuvent évoluer indépendamment.

Ça compte plus qu’il n’y paraît. Votre modèle de persistance accumule des champs internes, des relations et des colonnes qui n’ont aucune raison d’apparaître dans votre API. Avant la 3.1, on les exposait quand même ou on construisait un normaliseur élaboré pour les cacher. Maintenant on déclare ce que l’API expose comme classe distincte et on laisse le framework gérer la correspondance.

Un PUT conforme à la spec

Depuis la version 1.0, le handler PUT d’API Platform mettait à jour des ressources existantes. Créer une ressource via PUT — ce que la spec HTTP autorise explicitement — n’était pas supporté. La 3.1 ajoute la création basée sur l’uriTemplate :

#[Put(
    uriTemplate: '/books/{id}',
    allowCreate: true,
)]

Avec allowCreate: true, un PUT vers une URI qui n’existe pas crée la ressource au lieu de retourner une 404. L’identifiant vient de l’URI, pas du corps de la requête. C’est ce que la RFC 9110 décrit pour PUT : “Si la ressource cible n’a pas de représentation courante et que le PUT en crée une avec succès, le serveur d’origine DOIT informer le user agent en envoyant une réponse 201 (Created).”

C’est un petit paramètre, mais il ouvre API Platform à des cas d’usage — création idempotente, identifiants assignés par le client — qui nécessitaient auparavant un contrôleur personnalisé.

Les erreurs de dénormalisation collectées, pas jetées

Avant la 3.1, les erreurs de désérialisation s’arrêtaient au premier problème. Envoyer un corps de requête avec cinq champs invalides renvoyait une erreur sur le premier. On le corrigeait, on renvoyait, on trouvait le deuxième. À répéter cinq fois.

La 3.1 ajoute une option collect_denormalization_errors sur l’opération qui change ce comportement :

#[Post(collectDenormalizationErrors: true)]

Avec cette option activée, API Platform intercepte toutes les erreurs de type et les violations de contraintes pendant la désérialisation et les retourne sous forme de liste structurée dans la réponse, formatée de la même façon que les erreurs de validation. Un seul aller-retour, une vue complète.

ApiResource::openapi remplace openapiContext

L’ancien paramètre openapiContext acceptait un tableau brut fusionné dans le schéma OpenAPI généré — pratique mais non typé. La 3.1 introduit un paramètre openapi de premier ordre qui accepte un objet OpenApiOperation :

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;

#[Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'Créer un livre',
            required: true,
        ),
        summary: 'Créer une nouvelle entrée livre',
    )
)]

L’ancien tableau openapiContext fonctionne encore mais est déprécié. La nouvelle approche est typée, compatible avec l’autocomplétion IDE, et se valide à la construction plutôt qu’à la génération du schéma. Les backed enums PHP 8.1 obtiennent également une génération de schéma OpenAPI correcte en 3.1 — un champ typé comme backed enum produit un schéma avec des valeurs enum et le type correct, sans annotation supplémentaire.

Le pattern est clair

La 3.0 a établi l’architecture. La 3.1 montre ce que cette architecture permet : une séparation propre ressource/entité sans système DTO parallèle, une sémantique HTTP correcte selon la RFC, un meilleur rapport d’erreurs. Aucune de ces fonctionnalités n’aurait été aussi propre à implémenter sur le modèle data provider de la 2.x. Les features de la 3.1 sont la première preuve que la réécriture était la bonne décision.

Les propriétés dynamiques dépréciées

PHP a toujours permis d’ajouter des propriétés à des objets sans les déclarer dans la classe :

class User {}
$user = new User();
$user->name = 'Alice'; // aucune déclaration, aucune erreur... jusqu'ici

En 8.2, ça déclenche un avertissement de dépréciation. En PHP 9.0, ce sera une erreur fatale. Le délai de grâce existe, mais le compteur tourne.

La logique est solide : les propriétés dynamiques sont une source classique de typos qui passent silencieusement (écrivez $user->nmae et PHP crée simplement une nouvelle propriété au lieu de se plaindre). Des déclarations explicites rendent le contrat de la classe lisible et donnent aux outils matière à travailler.

La migration est essentiellement mécanique : déclarez les propriétés, ou posez #[AllowDynamicProperties] sur les classes legacy que vous ne pouvez pas encore toucher.

Les classes readonly

8.1 avait ajouté readonly sur les propriétés individuelles. 8.2 l’ajoute sur la déclaration de classe elle-même :

readonly class Point {
    public function __construct(
        public float $x,
        public float $y,
        public float $z,
    ) {}
}

Toutes les propriétés promues et déclarées explicitement deviennent readonly automatiquement. Les value objects (coordonnées, montants monétaires, identifiants) sont la cible évidente. La syntaxe est propre et l’intention se lit clairement.

Une contrainte : les classes readonly ne peuvent pas avoir de propriétés non typées, ce qui était déjà une mauvaise idée avec readonly de toute façon.

Les types DNF

Les types en Forme Normale Disjonctive permettent de combiner types union et types intersection :

function process(Countable&Iterator|null $collection): void { ... }

(Countable&Iterator)|null : un objet qui implémente les deux interfaces, ou null. Cela couvre des expressions de type que les unions de 8.0 et les intersections de 8.1 approchaient chacune sans pouvoir les représenter ensemble.

L’extension Random

Une extension Random dédiée remplace les fonctions éparpillées rand(), mt_rand(), random_int() par une API orientée objet :

$rng = new Random\Randomizer();
$rng->getInt(1, 100);
$rng->shuffleArray($items);

Les moteurs sont interchangeables : Mersenne Twister, PCG64, Xoshiro256StarStar, ou CryptoSafeEngine pour les contextes sensibles à la sécurité. Même code, moteur déterministe avec seed dans les tests, moteur cryptographique en production.

8.2 est une version de consolidation. La dépréciation des propriétés dynamiques est la seule décision à prendre maintenant.

null, false, et true comme types autonomes

PHP avait les types nullable depuis 7.1 et les types union depuis 8.0, mais null comme déclaration de type autonome n’était pas valide. 8.2 corrige ça :

function alwaysNull(): null {
    return null;
}

function disabled(): false {
    return false;
}

function enabled(): true {
    return true;
}

false et true comme types autonomes sont utiles quand on veut être précis sur ce qu’une fonction peut réellement retourner. C’est étroit mais juste : une fonction qui retourne false en cas d’échec et une chaîne en cas de succès devrait déclarer string|false, et maintenant les deux côtés de cette union sont de vrais types.

Les constantes dans les traits

Les traits pouvaient contenir des propriétés et des méthodes. Les constantes étaient le trou dans la raquette. 8.2 le comble :

trait Timestamps {
    public const DATE_FORMAT = 'Y-m-d H:i:s';

    public function formatCreatedAt(): string {
        return $this->createdAt->format(self::DATE_FORMAT);
    }
}

class Article {
    use Timestamps;
}

echo Article::DATE_FORMAT; // 'Y-m-d H:i:s'

La constante appartient à la classe qui utilise le trait, pas au trait lui-même, donc on ne peut pas accéder à Timestamps::DATE_FORMAT directement. Comportement de scope attendu, cohérent avec le fonctionnement des méthodes de trait.

#[SensitiveParameter]

Les stack traces ont toujours été un risque : les arguments de fonction sont loggés verbatim, ce qui veut dire que les mots de passe et les tokens se retrouvent dans les logs d’erreur et les dashboards de monitoring. 8.2 ajoute un attribut pour stopper ça :

function authenticate(
    string $user,
    #[\SensitiveParameter] string $password,
): bool {
    // si ça lève une exception, la stack trace affiche :
    // authenticate('alice', Object(SensitiveParameterValue))
    return hash('sha256', $password) === getStoredHash($user);
}

La valeur du paramètre dans la trace est remplacée par un objet SensitiveParameterValue. Un attribut, zéro excuse pour ne pas l’ajouter sur chaque fonction qui touche à des credentials.

Les syntaxes d’interpolation de chaînes dépréciées

Deux façons d’interpoler des expressions dans des chaînes sont dépréciées en 8.2 :

$name = 'world';

// Celles-ci sont dépréciées :
echo "Hello ${name}";       // utiliser "$name" ou "{$name}"
echo "Hello ${getName()}";  // utiliser "{$this->getName()}"

Les formes ${...} créaient une ambiguïté entre les variables variables et les expressions. La syntaxe plus propre {$...} a toujours été là et fait la même chose. C’est essentiellement un travail de recherche-remplacement sur les bases de code qui ont adopté les formes dépréciées par habitude.

utf8_encode() et utf8_decode() dépréciées

Ces deux fonctions sont dépréciées en 8.2 et disparaissent en 9.0. Leur comportement a toujours été plus étroit que ce que les noms suggéraient : utf8_encode() convertit ISO-8859-1 en UTF-8, pas “n’importe quel encodage en UTF-8”.

// Déprécié en 8.2 :
$utf8 = utf8_encode($latin1String);

// Utiliser à la place :
$utf8 = mb_convert_encoding($latin1String, 'UTF-8', 'ISO-8859-1');

mb_convert_encoding() ou iconv() gèrent le cas général. Si vous traitez vraiment des entrées en Latin-1, le remplacement est direct.

Les fonctions de chaîne indépendantes de la locale

Plusieurs fonctions de chaîne variaient silencieusement leur comportement selon la locale système, produisant des résultats différents en production par rapport à un container de dev. En 8.2, elles sont indépendantes de la locale et ne gèrent que l’ASCII :

// strtolower, strtoupper, stristr, stripos, strripos,
// lcfirst, ucfirst, ucwords, str_ireplace font maintenant une conversion
// de casse ASCII uniquement.
// Pour un comportement sensible à la locale, utiliser les équivalents mb_* :
$lowered = mb_strtolower($text, 'UTF-8');

C’est un correctif de cohérence. Si votre code reposait sur le comportement sensible à la locale de ces fonctions, il était déjà cassé sur des systèmes avec des configurations de locale différentes. 8.2 rend le comportement déterministe partout, ce qui est ce qu’on voulait vraiment.

str_split() sur une chaîne vide

Un changement de comportement discret à noter :

// PHP 8.1 : str_split('') === ['']
// PHP 8.2 : str_split('') === []

Le nouveau comportement a plus de sens : découper rien ne produit rien. Si vous vérifiez count(str_split($input)), une entrée vide ne produit plus un count de 1.

L’ancien modèle avait une fuite conceptuelle. DataProviderInterface et DataPersisterInterface étaient appelés pour chaque requête HTTP, mais le provider recevait le contexte de l’opération comme un indice — pas comme un contrat. Un provider de collection et un provider d’item étaient des interfaces distinctes, mais les deux vivaient dans le même seau mental : “choses qui retournent des données.” La couche HTTP savait ce qui était demandé ; le provider devait reconstruire cette connaissance à partir d’indices passés dans le tableau $context.

La 3.0 inverse le modèle. Les opérations sont déclarées en premier. L’accès aux données est câblé aux opérations.

Les state providers remplacent les data providers

L’ancien DataProviderInterface a disparu. Le remplaçant est ProviderInterface :

use ApiPlatform\State\ProviderInterface;
use ApiPlatform\Metadata\Operation;

class BookProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->repository->findAll();
        }

        return $this->repository->find($uriVariables['id']);
    }
}

La différence n’est pas syntaxique. En 2.x, on enregistrait un provider et API Platform l’appelait pour toute ressource correspondante. En 3.0, on lie un provider à une opération spécifique. Le provider n’a plus à deviner ce qui l’a déclenché — l’objet opération qu’il reçoit est le contrat.

Les state processors remplacent les data persisters

DataPersisterInterface avait le même problème côté écriture : une seule classe gérant la création, la mise à jour et la suppression, les distinguant en inspectant la méthode HTTP ou l’état de l’objet. ProcessorInterface reçoit l’opération comme argument typé :

use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\Metadata\Operation;

class BookProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        $this->entityManager->persist($data);
        $this->entityManager->flush();

        return $data;
    }
}

Plus utile encore : on peut lier un processor différent par opération. L’opération de suppression en reçoit un qui supprime. L’opération de création en reçoit un qui valide et stocke. Pas de switch, pas d’inspection de méthode, pas de classe partagée qui essaie d’être trois choses à la fois.

Les opérations déclarées explicitement en attributs PHP 8.1

L’autre moitié de la 3.0 est la couche de métadonnées. Les annotations Doctrine sont remplacées par des attributs natifs PHP 8.1, et chaque opération est déclarée explicitement sur la classe ressource :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new GetCollection(provider: BookProvider::class),
        new Get(provider: BookProvider::class),
        new Post(processor: BookProcessor::class),
    ]
)]
class Book
{
    // ...
}

C’est plus verbeux que @ApiResource avec ses valeurs par défaut magiques. C’est aussi explicite. On sait exactement quelles opérations HTTP existent pour cette ressource, ce qui récupère les données, ce qui les écrit, et où vit la logique. Les valeurs par défaut de la 2.x étaient pratiques jusqu’au jour où il fallait en surcharger une sans réussir à déterminer quel service décorer sans lire le code source.

PHP 8.1 n’était pas un hasard

L’exigence stricte pour PHP 8.1 est structurante. Les callables de première classe rendent l’enregistrement des filtres plus propre. L’immuabilité des métadonnées d’opération est assurée par un pattern de clonage (méthodes withX()) qui s’appuie sur les arguments nommés et les propriétés de constructeur promues — des fondations PHP 8.0 sur lesquelles l’architecture s’appuie massivement.

Plus concrètement : l’expression complète de l’architecture 3.0 — opérations typées, providers scopés à l’opération, métadonnées explicites — avait besoin de la 8.1 pour ne pas ressembler à des contournements. Abandonner PHP 7.x et 8.0 n’était pas une décision de nettoyage.

La migration est un vrai travail

Le passage de 2.x à 3.0 n’est pas un simple bump de version. Chaque DataProvider devient un ProviderInterface. Chaque DataPersister devient un ProcessorInterface. Les annotations deviennent des attributs. Les normaliseurs et filtres personnalisés peuvent nécessiter une restructuration. Le guide de mise à jour documente tout cela, mais “documenté” ne veut pas dire “rapide.”

Ce qu’on obtient de l’autre côté est une architecture qui passe à l’échelle sans la complexité ambiante de la 2.x : plus besoin de deviner quelle interface implémenter, plus de chaînes $this->supports(), plus de valeurs par défaut invisibles qui surchargent silencieusement la config explicite.

La 3.0 est l’API Platform qu’on concevrait de zéro en sachant ce qu’on sait après des années de 2.x. Le prix est la migration. Le numéro de version est honnête là-dessus.

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.

JIT

Le compilateur Just-In-Time était l’annonce principale. La réalité en production est plus nuancée : pour les applications web typiques (requêtes en base, appels HTTP, rendu de templates) les gains sont modestes, parce que ces workloads sont limités par les I/O, pas par le calcul. Là où le JIT brille vraiment, c’est le code intensif en CPU : manipulation d’images, transformation de données, calcul mathématique.

Pour la plupart des applications web, l’amélioration de performance vient du travail sur le moteur en général dans 8.0, pas du JIT spécifiquement. Vaut quand même la peine de l’activer : ça ne coûte rien sur les workloads I/O-bound.

Les expressions match

switch a trois problèmes : il utilise la comparaison souple, il tombe en cascade par défaut, et il ne peut pas être utilisé comme expression. match règle les trois :

$result = match($status) {
    'active', 'pending' => 'processing',
    'done'             => 'finished',
    default            => throw new \UnexpectedValueException($status),
};

Comparaison stricte. Pas de cascade. Expression qui retourne une valeur. Un match non exhaustif lève une exception. Après une semaine avec match, j’ai arrêté d’écrire des switch.

Les arguments nommés

array_slice(array: $users, offset: 0, length: 10, preserve_keys: true);

Les arguments nommés permettent de passer les arguments dans n’importe quel ordre et d’en sauter des optionnels. Le gain évident : la lisibilité sur les fonctions avec plusieurs flags booléens. Le gain moins évident : les arguments nommés survivent aux mises à jour de PHP même quand l’ordre des paramètres change, parce qu’on nomme ce qu’on veut dire.

Les attributs

Place aux docblock annotations (le style @Route, @ORM\Column sur lequel les frameworks se sont appuyés pendant des années), bienvenue à la syntaxe PHP de première classe :

#[Route('/users', methods: ['GET'])]
#[IsGranted('ROLE_ADMIN')]
public function list(): Response { ... }

Les attributs sont validés par le moteur, pas parsés depuis des strings. Le support IDE fonctionne directement, sans magie de plugin. Pour les utilisateurs de Symfony et Doctrine, c’est le vrai gain quotidien de PHP 8.0.

La promotion de constructeur

class User {
    public function __construct(
        public readonly int $id,
        public string $name,
        private ?string $email = null,
    ) {}
}

Propriétés déclarées et assignées en une ligne dans la signature du constructeur. Le gain de refactoring le plus immédiat dans 8.0 : chaque classe de données que j’ai touchée depuis la mise à jour fait moitié moins de lignes qu’avant.

L’opérateur nullsafe

$city = $user?->getAddress()?->getCity()?->getName();

null à n’importe quel point de la chaîne court-circuite le reste et retourne null. L’alternative était des null checks imbriqués ou une chaîne de retours anticipés. Ça se compose naturellement.

Les types union

Les arguments nommés rendent les signatures de fonctions plus explicites au site d’appel. Les types union les rendent plus honnêtes au site de déclaration :

function processInput(int|float|string $value): string|int
{
    if (is_string($value)) {
        return strlen($value);
    }
    return (int) round($value);
}

L’union int|float|string est un OU littéral. Le moteur l’impose à l’entrée et à la sortie. Avant 8.0, “ce paramètre accepte int ou float” vivait dans un docblock que rien n’imposait. Il y a aussi null comme composant de type : ?string est juste du sucre syntaxique pour string|null, les deux sont valides.

Un cas spécial : false. PHP a un tas de fonctions natives qui retournent une valeur typée en cas de succès et false en cas d’échec. Le système de types de 8.0 accommode ça : array|false, string|false. C’est une reconnaissance honnête que la codebase ne peut pas être réécrite du jour au lendemain.

Le type de retour static

static comme type de retour était possible de manière informelle via les docblocks, mais 8.0 le rend officiel. La distinction entre self et static compte dans l’héritage :

class Builder {
    protected array $config = [];

    public function set(string $key, mixed $value): static {
        $this->config[$key] = $value;
        return $this;
    }
}

class SpecialBuilder extends Builder {}

$result = (new SpecialBuilder())->set('foo', 'bar');
// $result est SpecialBuilder, pas Builder

Avec self comme type de retour, cette chaîne retournerait Builder, cassant les interfaces fluides dans les sous-classes. static fait fonctionner correctement les APIs fluides à travers les hiérarchies d’héritage sans surcharges manuelles.

Le type mixed

mixed était une convention de docblock pendant des années. 8.0 en fait un vrai type qui apparaît dans les signatures :

function debug(mixed $value): void {
    var_dump($value);
}

Il accepte tout : null, objets, ressources, scalaires, tableaux. Sémantiquement c’est la même chose que n’avoir aucune déclaration de type, mais c’est explicite plutôt qu’absent. La différence entre “ce paramètre est non typé” et “ce paramètre accepte intentionnellement n’importe quoi.” Vaut la peine de l’utiliser quand on écrit un utilitaire généraliste qui serait malhonnête avec un type plus étroit.

throw comme expression

Avant 8.0, throw était une instruction. Ça semble une distinction pédante jusqu’à ce qu’on tombe sur les endroits où on veut vraiment une expression :

// Dans un ternaire :
$value = $input ?? throw new \InvalidArgumentException('input required');

// Dans une arrow function :
$getId = fn(User $u) => $u->id ?? throw new \RuntimeException('no id');

// Dans un bras match (qui est déjà une expression) :
$status = match($code) {
    200     => 'ok',
    404     => 'not found',
    default => throw new \UnexpectedValueException("unknown code: $code"),
};

Le dernier est particulièrement utile : un match sans default lancera UnhandledMatchError automatiquement, mais parfois on veut contrôler le type d’exception et le message.

catch sans variable

Petite amélioration de qualité de vie. Quand on attrape une exception mais qu’on n’utilise pas réellement l’objet, 8.0 permet d’omettre la variable :

try {
    $result = $cache->get($key);
} catch (CacheMissException) {
    $result = $this->compute($key);
}

Avant 8.0, il fallait écrire catch (CacheMissException $e) et ensuite soit utiliser $e soit vivre avec l’avertissement IDE sur la variable inutilisée. Aucune des deux options n’était satisfaisante.

Les fonctions string qui auraient dû exister depuis des années

Trois fonctions que chaque développeur PHP a écrites manuellement au moins une fois :

str_contains('hello world', 'world');  // true
str_starts_with('hello world', 'hell'); // true
str_ends_with('hello world', 'world'); // true

Avant 8.0, les approches habituelles étaient strpos() !== false, strncmp(), ou substr() ===, qui nécessitent toutes de s’arrêter pour se souvenir de la sémantique. Ces nouvelles fonctions sont juste directes et lisibles. Pas de regex, pas d’arithmétique d’offset.

Un tri stable

Les fonctions de tri de PHP n’étaient pas stables avant 8.0. “Pas stable” signifie que les éléments qui se comparent comme égaux pouvaient se retrouver dans n’importe quel ordre les uns par rapport aux autres. En pratique, ça causait des bugs subtils dans le code UI qui avait besoin d’un ordre cohérent, une pagination qui changeait entre les chargements, et des tests qui ne passaient que par chance.

8.0 garantit la stabilité à travers toutes les fonctions de tri : sort(), usort(), array_multisort(), et le reste. Les éléments égaux conservent leur position relative originale. C’est le comportement que la plupart des gens supposaient déjà être là.

WeakMap

7.4 apportait WeakReference pour les objets simples. 8.0 apporte WeakMap : une map où les clés (des objets) et leurs données associées peuvent être ramassées par le GC quand aucune autre référence à l’objet-clé n’existe :

class RequestCache {
    private WeakMap $cache;

    public function __construct() {
        $this->cache = new WeakMap();
    }

    public function get(Request $request): Response {
        return $this->cache[$request] ??= $this->compute($request);
    }
}

Dès que $request n’est plus référencé ailleurs, l’entrée disparaît de la map. Pas de nettoyage manuel nécessaire. C’est le bon pattern pour la mémoïsation et les caches de propriétés calculées où on ne veut pas être la seule raison qu’un objet reste vivant.

Les nouveaux types d’exception

ValueError est levée quand une fonction reçoit le bon type mais une valeur invalide, par opposition à TypeError qui se déclenche sur les mauvais types :

array_chunk([], -5); // ValueError: array_chunk(): Argument #2 ($length) must be greater than 0

Avant 8.0, beaucoup de ces cas étaient des warnings qui retournaient false ou null. Maintenant ils lèvent des exceptions. Le moteur est plus strict, ce qui signifie qu’on attrape les problèmes plus tôt plutôt que d’obtenir des résultats bizarres quelque part en aval.

get_debug_type() et fdiv()

Deux fonctions utilitaires à connaître.

get_debug_type() retourne une représentation string normalisée de n’importe quelle valeur, pratique pour les messages d’erreur :

get_debug_type(1);          // "int"
get_debug_type(1.0);        // "float"
get_debug_type(null);       // "null"
get_debug_type(new Foo());  // "Foo" (pas "object")
get_debug_type([]);         // "array"

La différence avec gettype() : elle retourne les noms de classes pour les objets et utilise des noms normalisés ("int" pas "integer"). Exactement ce qu’on veut pour construire un message d’exception qui dit ce qu’on a reçu versus ce qu’on attendait.

fdiv() effectue une division en virgule flottante suivant IEEE 754, ce qui signifie que la division par zéro retourne INF, -INF, ou NAN au lieu d’un warning :

fdiv(10, 0);   // INF
fdiv(-10, 0);  // -INF
fdiv(0, 0);    // NAN

Les changements qui cassent des choses

8.0 inclut aussi quelques changements qui ne sont pas des fonctionnalités, ce sont des corrections.

Le plus important : 0 == "foo" est maintenant false. En PHP 7, comparer un entier à une string non numérique castait la string en 0, donc 0 == "n'importe-quoi-non-numérique" s’évaluait à true. C’était une source persistante de bugs et de maux de tête de sécurité. PHP 8 l’inverse : l’entier est casté en string à la place :

var_dump(0 == "foo");  // bool(false) en 8.0, bool(true) en 7.x
var_dump(0 == "");     // bool(false) en 8.0, bool(true) en 7.x
var_dump(0 == "0");    // bool(true) dans les deux ("0" est numérique)

Si on s’appuyait sur ça intentionnellement, on savait déjà que c’était douteux. Si on ne savait pas qu’on s’en appuyait, 8.0 va trouver ces chemins de code.

Plusieurs fonctions qui retournaient des ressources retournent maintenant des objets propres : curl_init() retourne un CurlHandle, imagecreate() retourne un GdImage, xml_parser_create() retourne un XMLParser. Le code qui vérifie is_resource($curl) va casser, parce que is_resource() retourne false pour ces objets. La correction consiste à vérifier contre false (la valeur de retour en cas d’échec) plutôt que de vérifier le type du cas de succès.

PHP 8.0 est le genre de version où les fonctionnalités se renforcent mutuellement. Les attributs se marient bien avec la promotion de constructeur. Match s’associe naturellement avec les types union. Les fonctions string réduisent le bruit qui cachait l’intention. Les corrections sont parfois cassantes, mais elles poussent le langage vers une cohérence qu’il aurait dû avoir depuis des années.

Les supprimer naïvement n’était pas une option. “Garder les 50 dernières” perd tout contexte historique pour les articles qui n’ont pas été touchés depuis un an. “Garder une par jour” perd tous les détails pour le contenu qui est activement édité. Ce dont on avait besoin, c’était une distribution qui correspondait à la façon dont les révisions sont réellement utilisées : couverture dense pour l’historique récent, couverture clairsemée pour l’ancien.

C’est une distribution logarithmique. Et la construire nécessitait du SQL brut.

Pourquoi les stratégies simples échouent

L’attrait d’une fenêtre fixe est évident : garder les N révisions les plus récentes et supprimer le reste. C’est une ligne de SQL et zéro maths. Le problème, c’est qu’elle traite une révision d’hier et une révision d’il y a trois ans comme également précieuses, ce qu’elles ne sont pas. Un éditeur qui ouvre un article de 2017 n’a pas besoin de ses 50 dernières versions ; il pourrait avoir besoin d’une par trimestre. Un article qui a été publié ce matin pourrait avoir besoin de chaque sauvegarde de la dernière heure.

Une stratégie temporelle (une révision par jour calendaire) a le problème inverse : elle est trop agressive pour le contenu actif. Si un article reçoit 30 sauvegardes entre 09h00 et 10h00, toutes sauf une disparaissent. Ce n’est pas de l’histoire, c’est de l’effacement.

Ni l’une ni l’autre ne peut exprimer “garder plus de détails pour le contenu récent, moins pour le vieux”. Cette relation est logarithmique.

L’idée de score

L’algorithme assigne à chaque révision un score basé sur son âge, puis garde seulement une révision par bucket de score. La formule de score produit des valeurs hautes et bien espacées pour les révisions récentes, et des valeurs petites et regroupées pour les anciennes.

L’expression centrale, simplifiée, ressemble à ça :

(
  ln( EXTRACT(epoch FROM (now() - created_at)) )
  /
  ( EXTRACT(epoch FROM (now() - created_at)) / 6000 )
)
* ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
* 1000

Soit s l’âge en secondes. La formule est grossièrement ln(s) / s * C, où le logarithme au numérateur et s au dénominateur font diminuer le résultat rapidement à mesure que s augmente.

Converti en entier, l’effet est le suivant : une révision sauvegardée il y a 10 minutes pourrait scorer 8432, une sauvegardée il y a 11 minutes score 8431. Elles sont dans des buckets différents. Une révision d’il y a six mois score 2, une d’il y a huit mois score aussi 2. Même bucket. La window function choisit ensuite la révision la plus récente de chaque bucket et supprime le reste.

Le résultat est automatique : les sauvegardes récentes sont toutes gardées parce que chacune a un score distinct ; les anciennes sont élagées parce que beaucoup partagent le même score.

La tentative DQL qui n’a pas abouti

Les window functions ne font pas partie de DQL. Le langage de requête de Doctrine n’a pas de syntaxe pour OVER, PARTITION BY ou ROW_NUMBER(). Avant de passer au SQL brut, l’équipe a essayé de les ajouter.

L’approche FunctionNode fonctionne pour les fonctions SQL simples, comme on l’avait déjà vu avec la FTS. Un nœud RowNumber émettant ROW_NUMBER() est trivial :

class RowNumber extends FunctionNode
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ROW_NUMBER()';
    }
}

La partie plus difficile est OVER(PARTITION BY ... ORDER BY ...). Un nœud de fonction Over a été ébauché, avec un nœud AST PartitionByClause personnalisé pour gérer la clause PARTITION BY :

class Over extends FunctionNode
{
    protected ?PartitionByClause $partitionByClause = null;
    protected ?OrderByClause $orderByClause = null;

    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'OVER('
            .($this->partitionByClause
                ? $this->partitionByClause->dispatch($sqlWalker)
                : ($this->orderByClause
                    ? $this->orderByClause->dispatch($sqlWalker)
                    : ''))
            .')';
    }
}

Ça n’a jamais été terminé. Les classes ont été livrées marquées @deprecated et “NOT TESTED YET”. Le problème est la composabilité : FunctionNode de DQL fonctionne bien pour les fonctions qui apparaissent dans les clauses WHERE ou les expressions SELECT. Une window function comme ROW_NUMBER() OVER (PARTITION BY ...) est une structure différente : elle apparaît dans une position SELECT, modifie la sémantique de la requête englobante, et exige que le parseur gère PARTITION BY comme une extension de la grammaire DQL. Rendre ça suffisamment robuste pour être fiable en production est un investissement significatif. Passer à DBAL et écrire le SQL directement a pris un après-midi.

La requête, couche par couche

L’implémentation finale est trois requêtes imbriquées :

DELETE FROM revision
WHERE iri = ?
AND id NOT IN (
    SELECT id FROM (
        SELECT
            row_number() OVER (
                PARTITION BY num, iri
                ORDER BY num DESC, created_at DESC
            ) AS lines,
            *
        FROM (
            SELECT
                (
                    ( ln( EXTRACT(epoch FROM (now() - created_at)) )
                      / ( EXTRACT(epoch FROM (now() - created_at)) / 6000 ) )
                    * ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
                    * 1000
                )::numeric::integer AS num,
                *
            FROM revision
            WHERE iri = ?
            ORDER BY created_at DESC
        ) AS lst
    ) AS rst
    WHERE lines = 1
);

Requête intérieure : calcule num, le score entier, pour chaque révision de l’IRI donnée. Les lignes sont triées par created_at DESC à ce stade.

Requête intermédiaire : exécute ROW_NUMBER() OVER (PARTITION BY num, iri ORDER BY num DESC, created_at DESC). Dans chaque bucket de score (num), les révisions sont numérotées à partir de 1 dans l’ordre décroissant d’âge. La révision la plus récente de chaque bucket obtient lines = 1.

Filtre extérieur : ne garde que les lignes lines = 1, une révision par bucket de score.

DELETE : supprime chaque révision pour cet IRI qui n’est pas dans l’ensemble gardé.

Le PARTITION BY num, iri est redondant sur l’IRI (toute la requête est déjà filtrée sur un IRI), mais rend l’intention explicite et garde la logique correcte si la requête est un jour réutilisée dans un contexte plus large.

La méthode est appelée depuis une requête complémentaire qui identifie quels IRIs ont accumulé plus qu’un seuil de révisions :

public function getIrisWithMoreRevisionThan(int $maxRevisionsCount, int $limit = 0, ?int $retencyDay = null): array
{
    $queryBuilder = $this
        ->createQueryBuilder('revision')
        ->select('revision.iri')
        ->groupBy('revision.iri')
        ->having('COUNT(1) > :maxRevisions')
        ->orderBy('COUNT(1)', Order::Descending->value)
        ->setParameter('maxRevisions', $maxRevisionsCount);

    // ...

    return array_column($queryBuilder->getQuery()->getResult(), 'iri');
}

Les deux méthodes tournent ensemble dans un nettoyage planifié : trouver les IRIs au-dessus du seuil, élaguer chacun.

Le câbler à une commande planifiée

La requête d’élagage ne s’exécute pas dans une requête HTTP. Elle tourne derrière une commande Symfony, appelée sur un planning.

La commande prend quelques options pour contrôler son agressivité :

#[AsCommand('app:purge:revision', 'Remove useless revisions')]
final class PurgeRevisionCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addOption('max-revisions', 'm', InputOption::VALUE_REQUIRED,
                'Seuil de révisions au-dessus duquel un IRI est élaguée', 30)
            ->addOption('limit', 'l', InputOption::VALUE_REQUIRED,
                'Nombre max d\'IRIs à traiter par exécution')
            ->addOption('delay', 'w', InputOption::VALUE_REQUIRED,
                'Délai en secondes entre chaque IRI')
            ->addOption('retencyDay', 'r', InputOption::VALUE_OPTIONAL,
                'Ne traiter que les IRIs dont la dernière révision est plus vieille que N jours');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $iris = $this->revisionRepository->getIrisWithMoreRevisionThan(
            (int) $input->getOption('max-revisions'),
            (int) $input->getOption('limit'),
            (int) $input->getOption('retencyDay'),
        );

        foreach ($iris as $iri) {
            $totalDeleted += $this->revisionRepository->deleteOldRevisionForIri($iri);
            usleep((int) $input->getOption('delay') * 1_000_000);
        }

        return Command::SUCCESS;
    }
}

L’option --delay mérite attention : sur une base de données chargée, marteler une centaine d’instructions DELETE dos à dos peut provoquer de la contention de verrous. Un petit sleep entre les itérations empêche l’élagage d’entrer en concurrence avec le trafic de production.

La commande tourne derrière deux entrées crontab avec des seuils différents :

# Horaire : garder 30 révisions par IRI, traiter 100 IRIs par exécution
0 * * * * php bin/console app:purge:revision --max-revisions 30 --limit 100

# Nocturne : pour le contenu non touché depuis un an, garder seulement 3
0 0 * * * php bin/console app:purge:revision --max-revisions 3 --limit 100 --retencyDay 365

La stratégie à deux niveaux est importante. Le job horaire garde 30 révisions par IRI, ce qui est un plafond raisonnable pour le contenu activement édité. Le job nocturne cible seulement les IRIs non mis à jour depuis plus d’un an et n’en garde que 3. Un article qui n’a pas bougé depuis douze mois n’a pas besoin de trente versions dans son historique.

Ce que ça donne en pratique

Un article sauvegardé 200 fois gardera typiquement 20 à 30 révisions après élagage : la plupart des sauvegardes récentes, quelques-unes du mois dernier, une ou deux de chaque trimestre de l’année précédente. Le décompte exact dépend de la distribution d’âge des sauvegardes, pas d’un plafond arbitraire.

Un article mis à jour pour la dernière fois il y a deux ans pourrait se retrouver avec 5 ou 6 révisions. Les modifications récentes sont toutes là ; l’ancien historique est compressé mais pas effacé.

Ce n’est pas un historique parfait. C’est un historique utile.

La frontière entre DQL et SQL brut

La tentative window function n’est pas un échec à cacher. C’est une donnée utile : FunctionNode fonctionne bien pour les fonctions scalaires dans les positions WHERE et SELECT, mais composer une expression complète ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) en DQL est plus difficile qu’il n’y paraît. L’extension de grammaire, les nœuds AST, l’intégration du SQL walker : c’est une quantité non triviale de code pour quelque chose que le SQL natif gère en trois lignes.

La frontière pratique est grossièrement celle-ci : si une fonctionnalité PostgreSQL correspond à un appel de fonction d’arité fixe, le DQL personnalisé convient. Si elle nécessite une nouvelle syntaxe de clause (frames de fenêtre, CTEs, lateral joins), le DBAL natif est généralement le meilleur compromis.

Les propriétés typées

C’est la grande nouveauté. Depuis PHP 7.0, on pouvait typer les paramètres de fonctions et les valeurs de retour. Mais les propriétés de classe ? Toujours non typées :

class User {
    public int $id;
    public string $name;
    public ?DateTimeInterface $deletedAt;
}

7.4 change ça. Les propriétés typées font respecter les types à l’affectation, pas seulement au niveau des sites d’appel. Les classes deviennent auto-documentées d’une façon que les docblocks n’ont jamais vraiment réussi à faire, et le moteur attrape les erreurs de type avant qu’elles ne se propagent dans la moitié de la stack.

Une subtilité : les propriétés typées sont uninitialized par défaut (pas null). Accéder à une propriété non initialisée lève une Error. C’est un piège classique : ?string n’implique pas un défaut de null. Il faut encore un = null explicite pour ça.

Les arrow functions

Les closures en PHP ont toujours nécessité d’importer explicitement les variables de la portée extérieure avec use :

$multiplier = 3;
$fn = fn($x) => $x * $multiplier; // pas besoin de use()

Les arrow functions capturent automatiquement la portée englobante. Expression unique, retour implicite, pas de boilerplate. Elles ne remplacent pas les closures complètes pour la logique complexe, mais pour les callbacks courts, elles éliminent une catégorie de bruit qui s’accumulait depuis des années.

Le préchargement opcache

Pour les setups PHP-FPM à longue durée de vie, le préchargement permet à un script de charger et compiler des fichiers PHP en mémoire opcache au démarrage du serveur. Ces fichiers sont disponibles pour toutes les requêtes sans overhead de compilation.

Le gain varie selon l’application. Sur les grands frameworks où les mêmes fichiers sont chargés à chaque requête, c’est réel. Sur les petites applications, négligeable. Vaut la peine de benchmarker avant d’ajouter la complexité de configuration.

Les petites choses qui s’accumulent

Les fonctionnalités mentionnées en passant méritent plus qu’une ligne. L’opérateur d’affectation null-coalescente ??= résout un pattern suffisamment agaçant à écrire à chaque fois, mais jamais assez pour se donner la peine de l’abstraire :

$config['timeout'] ??= 30;
// équivalent à : $config['timeout'] = $config['timeout'] ?? 30;

L’opérateur spread dans les littéraux de tableau fait ce qu’on attend de la version pour les appels de fonctions — dépacker un itérable dans un littéral de tableau :

$defaults = ['color' => 'blue', 'size' => 'M'];
$options = ['size' => 'L', ...$defaults, 'weight' => 1.2];
// ['size' => 'M', 'color' => 'blue', 'weight' => 1.2]

Note : les clés string n’étaient pas supportées dans 7.4 pour le dépaquet de tableau. Ça viendra plus tard.

Les types de retour covariants et les types de paramètres contravariants comblent un vide qui rendait certains patterns d’héritage inutilement maladroits. Une classe enfant peut maintenant affiner son type de retour vers un sous-type de celui du parent, sans erreur fatale :

class Producer {
    public function get(): Iterator {}
}
class ChildProducer extends Producer {
    public function get(): ArrayIterator {} // ArrayIterator implémente Iterator
}

Lire des nombres à 3h du matin

Le séparateur de littéraux numériques est une de ces fonctionnalités dont on ne sait pas qu’on la voulait jusqu’à la première fois qu’on écrit une grande constante et qu’on perd immédiatement le sens de l’ordre de grandeur :

$earthMass    = 5_972_168_000_000_000_000_000_000; // kg
$lightSpeed   = 299_792_458;                        // m/s
$planck       = 6.626_070_15e-34;                  // J·s
$hexMask      = 0xFF_EC_D5_08;
$binaryFlags  = 0b0001_1111_0010_0000;

L’underscore est purement syntaxique. Le moteur le supprime avant de parser la valeur. On peut le mettre n’importe où entre les chiffres, bien que la convention suive le groupement naturel du système numérique utilisé.

Référencer sans posséder

WeakReference permet de tenir une référence à un objet sans empêcher le ramasse-miettes de le détruire. Le cas d’usage : les caches et registres — on veut savoir qu’un objet est vivant, mais on ne veut pas être la raison qu’il reste vivant :

$object = new HeavyObject();
$ref = WeakReference::create($object);

var_dump($ref->get()); // object(HeavyObject)

unset($object);

var_dump($ref->get()); // NULL — le GC l'a collecté

Avant 7.4, il y avait WeakRef via une extension, et certains frameworks faisaient des tours de passe-passe avec SplObjectStorage qui ne se comportaient pas tout à fait pareil. La classe native est juste directe.

La sérialisation sans surprise

La sérialisation personnalisée d’objets avant 7.4 passait par l’interface Serializable : implémenter serialize() et unserialize(), retourner une string, reconstruire depuis elle. Le problème est que serialize() déclenchait __sleep(), unserialize() déclenchait __wakeup(), et l’interaction entre ces hooks était fragile, surtout dans les hiérarchies d’héritage.

7.4 introduit __serialize() et __unserialize(), qui travaillent avec des tableaux plutôt que des strings et n’interagissent pas avec les anciens hooks :

class Session {
    private string $token;
    private \DateTime $createdAt;

    public function __serialize(): array {
        return ['token' => $this->token, 'created' => $this->createdAt->getTimestamp()];
    }

    public function __unserialize(array $data): void {
        $this->token = $data['token'];
        $this->createdAt = (new \DateTime())->setTimestamp($data['created']);
    }
}

Quand les nouvelles et anciennes méthodes coexistent sur la même classe, __serialize() gagne. L’ancienne interface Serializable est dépréciée dans 8.1.

Ce que la bibliothèque standard a discrètement reçu

mb_str_split() fait ce que str_split() fait mais correctement pour les strings multibyte. Le manque était franchement embarrassant pour un langage utilisé dans autant de locales que PHP :

mb_str_split('héllo', 1); // ['h', 'é', 'l', 'l', 'o']
str_split('héllo', 1);    // ['h', 'Ã', '©', 'l', 'l', 'o'] — cassé

strip_tags() accepte maintenant un tableau de tags autorisés, ce qui est plus propre que le format string qu’il fallait passer auparavant :

strip_tags($html, ['p', 'br', 'strong']); // était : '<p><br><strong>'

proc_open() accepte maintenant un tableau de commandes, contournant complètement l’interprétation par le shell. Même idée que subprocess de Python avec shell=False. À retenir quand on passe des arguments fournis par l’utilisateur à un processus externe.

Le chapitre FFI

L’extension Foreign Function Interface a atterri dans 7.4 après avoir passé du temps dans une branche feature. Elle permet à PHP d’appeler des fonctions C natives en chargeant une bibliothèque partagée et en déclarant les signatures :

$ffi = FFI::cdef("int strlen(const char *s);", "libc.so.6");
var_dump($ffi->strlen("hello")); // int(5)

Les applications pratiques sont étroites mais réelles : appeler des API de plateforme sans binding PHP, wrapper du code C critique pour les performances sans écrire une extension complète, ou juste jouer avec des bibliothèques natives directement. Ce n’est pas un remplacement des extensions propres en production, mais ça supprime la barrière “écrire une extension C” pour l’exploration.

Ce qui a été déprécié

Quelques choses qui auraient dû être nettoyées depuis longtemps ont finalement reçu le traitement dépréciation dans 7.4.

Les ternaires imbriqués sans parenthèses ont toujours été ambigus. PHP les évaluait de gauche à droite alors que pratiquement tous les autres langages avec un ternaire évaluent de droite à gauche :

// Était ambigu, maintenant déprécié :
$a ? $b : $c ? $d : $e;

// Rendre explicite :
($a ? $b : $c) ? $d : $e;

L’accès par offset avec accolades pour les strings et tableaux — $str{0} au lieu de $str[0] — est déprécié et supprimé dans 8.0. C’était toujours un alias, jamais une fonctionnalité distincte.

implode() avec l’ordre d’arguments inversé (tableau en premier, colle en second) est déprécié. La fonction a accepté les deux ordres depuis le début, ce qui était une erreur. L’ordre correct est implode(string $separator, array $array).

Ce qui arrive ensuite

7.4 est la dernière version 7.x. Les dépréciations sont principalement du déblayage pour les suppressions dans 8.0. Le backlog de RFCs pour 8.0 est substantiel : JIT, attributs, arguments nommés, expressions match. 7.4 est un bon endroit où atterrir en attendant que tout ça arrive.

Heredoc et nowdoc flexibles

Jusqu’à 7.3, le marqueur de fermeture d’un heredoc devait être en colonne zéro. Ce qui forçait une désindentation maladroite dans du code par ailleurs bien formaté :

// avant
$html = <<<HTML
    <div>
        <p>Hello</p>
    </div>
HTML; // devait être en colonne 0, moche

// après
$html = <<<HTML
    <div>
        <p>Hello</p>
    </div>
    HTML;

Le marqueur de fermeture peut désormais être indenté pour correspondre au code environnant, et cette indentation est retirée du contenu. Ça paraît cosmétique. Ce n’est pas le cas. Les heredocs dans des contextes imbriqués (méthodes de classe, conditions) étaient visuellement dissonants avant. Maintenant ils s’intègrent.

array_key_first() et array_key_last()

Ce contournement existait depuis toujours :

$first = array_keys($array)[0];

7.3 ajoute les helpers évidents :

$first = array_key_first($array);
$last  = array_key_last($array);

Et is_countable() pour vérifier proprement avant d’appeler count() sur quelque chose qui n’implémente peut-être pas Countable. Des fonctions qui auraient dû exister depuis des années.

PCRE2

Le moteur d’expressions régulières a migré de PCRE vers PCRE2. Largement invisible pour les patterns existants, mais PCRE2 est activement maintenu et gère mieux les cas limites. L’impact pratique principal : certains patterns qui produisaient auparavant un comportement indéfini lancent maintenant des erreurs. C’est le bon comportement, même si ça surprend lors du premier upgrade.

Virgules finales dans les appels de fonctions

7.2 autorisait les virgules finales dans les imports de namespaces groupés. 7.3 étend ça aux appels de fonctions et de méthodes :

$result = array_merge(
    $defaults,
    $overrides,
    $extras, // plus besoin de retirer cette virgule avant la parenthèse fermante
);

Ça compte surtout pour les appels multiligne. Ajouter ou retirer un argument ne nécessite plus de toucher à la ligne adjacente. Les diffs restent honnêtes, les rebases deviennent un peu moins douloureux.

Assignments par référence dans la déstructuration de tableaux

La déstructuration de tableaux a gagné la capacité de capturer des références plutôt que des copies :

$data = ['Alice', 42];

[&$name, $age] = $data;

$name = 'Bob';
var_dump($data[0]); // string(3) "Bob"

Les références imbriquées fonctionnent aussi :

[$a, [&$b]] = [1, [2]];

Plus de niche que les virgules finales, mais le bon outil quand on a besoin d’aliaser profondément dans une structure sans un tas d’assignations intermédiaires.

instanceof avec des littéraux est maintenant légal

Avant, utiliser instanceof avec un littéral à gauche était une erreur de parsing. 7.3 le rend valide :

var_dump(null instanceof stdClass); // bool(false)

Ça retourne toujours false, ce qui est exactement correct. L’avantage, c’est que du code qui construit conditionnellement une valeur puis vérifie son type n’a plus besoin d’extraire la valeur dans une variable au préalable. Utile dans le code généré et les helpers de test.

json_decode() et json_encode() peuvent maintenant lever des exceptions

Avant 7.3, les erreurs JSON étaient silencieuses à moins de penser à vérifier json_last_error(). Facile à oublier, facile à rater :

$data = json_decode($response);
if (json_last_error() !== JSON_ERROR_NONE) {
    // la plupart des gens oubliaient cette partie
}

7.3 ajoute JSON_THROW_ON_ERROR :

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
// lève JsonException sur une entrée malformée

JsonException étend RuntimeException. Attrapez-la spécifiquement ou laissez-la se propager. Ça aurait dû fonctionner comme ça dès le début.

setcookie() avec un tableau d’options

L’ancienne signature de setcookie() est un vestige : sept arguments positionnels, dont la plupart qu’on laisse à leurs valeurs par défaut juste pour atteindre celui qu’on veut vraiment. 7.3 ajoute une forme alternative qui prend un tableau associatif :

setcookie('session', $token, [
    'expires'  => time() + 3600,
    'path'     => '/',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax',
]);

L’option samesite est la vraie raison pour laquelle ça a été ajouté — l’ancienne signature positionnelle n’avait pas de slot pour elle. session_set_cookie_params() a reçu le même traitement, et une nouvelle directive ini session.cookie_samesite couvre la valeur par défaut.

hrtime() pour un benchmarking qui mesure vraiment le temps

microtime() lit l’horloge murale. Très bien pour la plupart des cas. Mais elle est affectée par les ajustements NTP, et sa résolution dépend de l’implémentation. hrtime() lit l’horloge monotone haute résolution :

$start = hrtime(true);  // nanosecondes sous forme d'entier
doWork();
$elapsed = hrtime(true) - $start;
echo $elapsed / 1e6 . " ms\n";

Sans l’argument true, elle retourne [secondes, nanosecondes] sous forme d’un tableau à deux éléments. Utilisez ça pour les microbenchmarks, ou partout où la dérive d’horloge corromprait silencieusement vos mesures.

gc_status() — regarder à l’intérieur du ramasse-miettes

Le ramasse-miettes cyclique de PHP se déclenche quand un buffer de cycles potentiels se remplit. Jusqu’à 7.3 il n’y avait pas de moyen simple de voir ce qu’il faisait réellement. gc_status() expose l’état interne :

$status = gc_status();
// [
//   'runs'       => 3,
//   'collected'  => 127,
//   'threshold'  => 10001,
//   'roots'      => 42,
// ]

Pas quelque chose que la plupart du code applicatif a besoin. Utile quand on essaie de comprendre pourquoi la mémoire continue de grimper sous des charges de travail spécifiques.

CompileError rejoint la hiérarchie des exceptions

Les erreurs de parsing sont catchables en tant que ParseError depuis PHP 7.0. 7.3 introduit CompileError comme classe parente pour les échecs à la compilation, avec ParseError qui devient une sous-classe :

Error
└── CompileError
    └── ParseError

En pratique, le code qui catch ParseError continue de fonctionner. La nouvelle classe donne juste aux futures erreurs de compilation (qui ne sont pas des erreurs de parsing) une place correcte dans la hiérarchie.

bcscale() comme getter

L’échelle BC Math était toujours settable via bcscale($n). Obtenir l’échelle actuelle nécessitait de la suivre soi-même. 7.3 fait fonctionner bcscale() sans arguments :

bcscale(4);
echo bcscale(); // 4

Mineur. Utile à savoir si vous écrivez du code de bibliothèque qui doit respecter ou restaurer le paramètre d’échelle de l’appelant.

L’avertissement pour continue dans un switch

Celui-là est un correctif d’exactitude qui ressemble à une dépréciation. En PHP, continue dans un switch s’est toujours comporté comme break — il sort du switch, pas de la boucle englobante. Les développeurs venant d’autres langages écrivent souvent ça en espérant passer à l’itération suivante de la boucle :

foreach ($items as $item) {
    switch ($item->type) {
        case 'skip':
            continue; // FAUX : sort du switch, pas du foreach
    }
}

7.3 ajoute un warning pour ce pattern. Le correctif, c’est continue 2 pour cibler explicitement la boucle englobante. Le comportement n’a pas changé. Le silence, si.

Dépréciations

Les constantes insensibles à la casse déclarées via define() sont dépréciées :

define('MY_CONST', 42, true); // troisième argument déprécié

Passer une needle non-chaîne à strpos(), strstr(), et fonctions similaires est déprécié. En PHP 8, ces fonctions interpréteront la needle comme une chaîne, pas comme un codepoint ASCII. Si vous passez intentionnellement des entiers à ces fonctions, chr($n) est la forme explicite.

fgetss() est déprécié — c’était fgets() avec les balises HTML/PHP retirées. Utilisez fgets() et retirez les balises explicitement si nécessaire. Le filtre de stream string.strip_tags disparaît avec lui.

7.3 est le genre de version qu’on apprécie avec du recul. Rien d’individuellement dramatique, mais après six mois avec elle, la correction des heredocs seule a amorti le coût de la migration en lisibilité. Parfois le banal est exactement ce qu’il faut.

C’est une bonne chose, même si ça ne le semble pas quand c’est vous qui devez faire la migration.

Le problème mcrypt

mcrypt n’est plus maintenu depuis 2007. Plus d’une décennie de stagnation dans une bibliothèque cryptographique. Dépréciée en 7.1, elle est retirée définitivement en 7.2. Son remplaçant : sodium, désormais intégré comme extension core.

Sodium est le binding PHP pour libsodium, une bibliothèque cryptographique moderne conçue autour de valeurs par défaut sûres. Là où mcrypt vous demandait de choisir le bon algorithme, le bon mode et le bon padding (et vous laissait vous planter silencieusement), l’API de sodium rend les choix dangereux structurellement difficiles. sodium_crypto_secretbox() pour le chiffrement symétrique, sodium_crypto_box() pour l’asymétrique, sodium_crypto_sign() pour les signatures. Les noms disent ce qu’on fait.

Si vous avez du code mcrypt en production, la migration est inévitable. Et ça vaut le coup de le faire soigneusement : du code cryptographique qui “fonctionne encore” peut être silencieusement cassé d’une façon que vous ne remarquerez qu’il sera trop tard.

Le type hint object

7.2 ajoute object comme type de paramètre et de retour :

function serialize(object $data): string {
    // accepte n'importe quel objet
}

C’est large — n’importe quel objet le satisfait — mais c’est mieux qu’aucun type du tout quand vous ne vous souciez vraiment pas de la classe spécifique. Complète les types existants array, callable et les hints par classe concrète.

Argon2 dans password_hash

$hash = password_hash($password, PASSWORD_ARGON2I);

PASSWORD_BCRYPT était la valeur par défaut et reste raisonnable, mais Argon2 a remporté le Password Hashing Competition pour une bonne raison : il est memory-hard, ce qui rend le craquage par GPU significativement plus coûteux. Vaut la peine de basculer pour les nouvelles apps.

7.2 est davantage une version sécurité qu’une version langage. Supprimez mcrypt, ajoutez sodium, et vous placez la plateforme dans un état où on peut lui faire confiance avec des données sensibles. Les fonctionnalités du langage sont incrémentales. Le changement d’infrastructure, lui, ne l’est pas.

Des types de paramètres qu’on peut désormais omettre intentionnellement

7.2 formalise quelque chose qui était jusqu’ici juste une odeur de code : quand vous implémentez une interface ou surchargez une méthode, vous pouvez maintenant omettre complètement le type du paramètre. C’est de la contravariance valide au sens du principe de substitution de Liskov.

interface Serializable {
    public function serialize(array $data): string;
}

class JsonSerializer implements Serializable {
    public function serialize($data): string { // pas de type — accepte plus, toujours valide
        return json_encode($data);
    }
}

Ça paraît bizarre au premier abord. Mais c’est logiquement correct : une méthode qui accepte tout est strictement plus permissive qu’une qui n’accepte que des tableaux. Le système de types est d’accord, même si votre relecteur de code lève un sourcil.

Des méthodes abstraites qui évoluent

Quand une classe abstraite étend une autre classe abstraite, elle peut désormais surcharger la méthode abstraite avec une signature différente. La contrainte est directionnelle : les paramètres peuvent être élargis (contravariants), les types de retour peuvent être resserrés (covariants).

abstract class BaseProcessor {
    abstract function process(string $input);
}

abstract class TypedProcessor extends BaseProcessor {
    abstract function process($input): int; // paramètre élargi, type de retour ajouté
}

C’était refusé avant 7.2. Ça débloque des abstractions intermédiaires sans forcer chaque classe feuille à répéter la même signature.

Virgule finale dans les imports groupés

Petit, mais je remarque son absence quand elle manque. Les imports de namespaces groupés peuvent désormais avoir une virgule finale après le dernier élément :

use App\Services\{
    UserService,
    OrderService,
    NotificationService, // virgule ici — enfin
};

Ça signifie qu’on peut réordonner ou ajouter des lignes sans toucher à la ligne précédente. Les diffs git deviennent plus propres, les conflits de merge plus rares.

count() a développé une conscience

Avant 7.2, count(null) retournait 0. Silencieusement. Sans warning. C’est exactement le genre de chose qui enterre un bug pendant des mois. Maintenant, ça émet un E_WARNING quand vous passez quelque chose qui n’est ni un tableau ni un objet Countable.

count(null);  // Warning: count(): Parameter must be an array or an object that implements Countable
count(42);    // pareil
count("hi");  // pareil

Le comportement n’a pas changé pour les entrées valides. Seul le silence a été brisé. C’est la bonne direction.

spl_object_id() — ce que vous émuliez avec SplObjectStorage

Si vous avez déjà construit une map indexée par identité d’objet, vous avez écrit quelque chose comme ça :

$storage = new SplObjectStorage();
$storage[$obj] = true;

7.2 ajoute spl_object_id(), qui retourne un entier unique pour la durée de vie d’un objet. C’est le même handle interne qu’utilise SplObjectStorage, rendu directement accessible :

$id = spl_object_id($obj); // ex. 42
$map[$id] = 'something';

L’entier est réutilisé après la destruction de l’objet, donc ne le conservez pas au-delà de la durée de vie de l’objet. Dans un contexte bien délimité cependant, c’est une clé d’identité peu coûteuse.

PDO : les chaînes de caractères nationales

Quand on travaille avec des bases de données qui distinguent les types de chaînes régulières et nationales (Oracle, SQL Server), 7.2 ajoute les flags nécessaires :

$stmt = $pdo->prepare("SELECT * FROM users WHERE name = ?");
$stmt->bindValue(1, 'Ångström', PDO::PARAM_STR | PDO::PARAM_STR_NATL);

Ou définir une valeur par défaut au niveau de la connexion :

$pdo->setAttribute(PDO::ATTR_DEFAULT_STR_PARAM, PDO::PARAM_STR_NATL);

PDO::PARAM_STR_NATL indique que la chaîne est un type caractère national (NCHAR/NVARCHAR). Obscur, certes. Indispensable si vous avez déjà vu vos données Unicode ressortir déformées parce que le driver ne faisait pas la différence.

GD supporte les BMP et les rectangles de clipping

Deux choses à connaître. D’abord, les fichiers BMP sont désormais des citoyens de première classe dans l’extension GD :

$image = imagecreatefrombmp('photo.bmp');
imagebmp($image, 'output.bmp');

Ensuite, on peut maintenant définir un rectangle de clipping pour que les opérations de dessin n’affectent qu’une portion de l’image :

imagesetclip($image, 10, 10, 200, 150); // x1, y1, x2, y2
// tout ce qui est dessiné en dehors de ce rectangle est silencieusement ignoré

Aucune de ces fonctionnalités ne transforme la façon dont la plupart des apps fonctionnent, mais les deux remplacent “installer une bibliothèque supplémentaire” par “c’est juste dans le core maintenant.”

mb_chr() et mb_ord() — le chr() et ord() d’Unicode

PHP a chr() et ord() depuis toujours. Ils travaillent sur des octets. Pour les points de code Unicode, vous étiez livré à vous-même. 7.2 ajoute les équivalents multibyte :

$char = mb_chr(0x1F600); // retourne l'emoji 😀
$code = mb_ord('é');     // retourne 233

Et mb_scrub(), qui supprime les séquences d’octets invalides d’une chaîne plutôt que d’échouer silencieusement ou de lancer une exception :

$clean = mb_scrub($untrustedInput, 'UTF-8');

Pratique à toute frontière externe : réponses API, uploads de fichiers, lectures en base depuis des systèmes legacy.

Dépréciations à connaître avant l’arrivée de 7.4

Plusieurs choses ont été mollement dépréciées en 7.2 et deviendront des erreurs dans les versions ultérieures. Celles qui risquent le plus de piquer :

__autoload() est déprécié. Si vous enregistrez encore une fonction d’autoload globale au lieu d’utiliser spl_autoload_register(), corrigez ça avant que ça devienne fatal.

create_function() est déprécié. C’est un wrapper autour de eval() et ça a toujours été dangereux. Utilisez une closure :

// avant
$fn = create_function('$x', 'return $x * 2;');

// après
$fn = fn($x) => $x * 2;

each() est déprécié. Le pattern de boucle qu’il permettait s’écrit mieux avec foreach. Aucune perte ici.

parse_str() sans second argument déverse les valeurs parsées dans la table des symboles locale — un problème de sécurité qui n’aurait jamais dû être autorisé. Passez toujours la variable de sortie :

parse_str($queryString, $params); // correct

Le cast (unset) est déprécié parce qu’il retourne toujours null, que vous pouvez simplement écrire null. Une syntaxe complètement inutile qui n’aurait jamais dû exister.

Le problème n’est pas dans la logique métier. Il est dans ce que Doctrine fait discrètement avec les dates.

Ce que Doctrine fait par défaut

Quand on déclare un champ datetime dans une entité Doctrine, la conversion entre PHP et la base de données passe par DateTimeType. Cette classe appelle format() sur l’objet DateTime pour écrire en base, et DateTime::createFromFormat() pour le relire. Aucune mention de timezone nulle part.

Si l’objet PHP est en Europe/Paris, Doctrine formate 2017-01-15 11:30:00 et l’écrit tel quel. Si le serveur qui lit ce champ est en UTC, il obtient 2017-01-15 11:30:00 et l’interprète comme UTC. Une heure s’est évaporée dans l’aller-retour, sans le moindre message d’erreur.

La doc Doctrine couvre ce sujet et suggère des types personnalisés comme solution. Ce qu’elle mentionne en passant, c’est qu’on peut donner à ces types personnalisés le même nom que les types natifs. Ce détail change tout.

Remplacer, pas ajouter

La plupart des exemples de types Doctrine personnalisés introduisent un nouveau nom : utc_datetime, app_date, et ainsi de suite. On annote ensuite chaque champ avec type: 'utc_datetime' dans les entités. Ça fonctionne, mais c’est fastidieux et ça ne protège pas contre un type: 'datetime' oublié.

L’autre option : enregistrer le type personnalisé sous le nom datetime. Doctrine remplace sa propre implémentation par la nôtre, partout, sans exception. Chaque champ datetime de toutes les entités passe par notre logique, sans changer une seule annotation.

C’est ce qu’on vient de déployer sur notre plateforme de microservices PHP. Voici à quoi ça ressemble.

Le trait partagé

Les deux types (date et datetime) partagent la même logique de conversion via un trait :

trait UTCDate
{
    private \DateTimeZone $utc;

    public function convertToPHPValue($value, AbstractPlatform $platform): ?\DateTime
    {
        if (null === $value || $value instanceof \DateTime) {
            return $value;
        }

        $format = $this->getFormat($platform);
        $converted = \DateTime::createFromFormat($format, $value, $this->getUtc());

        if (!$converted) {
            throw new \RuntimeException(
                sprintf('Could not convert database value "%s" to DateTime using format "%s".', $value, $format)
            );
        }

        $this->postConvert($converted);

        return $converted;
    }

    abstract protected function getFormat(AbstractPlatform $platform): string;

    private function getUtc(): \DateTimeZone
    {
        if (empty($this->utc)) {
            $this->utc = new \DateTimeZone('UTC');
        }

        return $this->utc;
    }
}

Le point clé : \DateTime::createFromFormat() reçoit une timezone UTC explicite. La valeur brute issue de la base est interprétée comme UTC, peu importe la timezone configurée sur le serveur PHP.

UTCDateTimeType

Pour les champs datetime, le chemin d’écriture doit aussi imposer l’UTC :

class UTCDateTimeType extends DateTimeType
{
    use UTCDate;

    #[\Override]
    public function convertToPHPValue($value, AbstractPlatform $platform): ?\DateTime
    {
        if (null === $value || $value instanceof \DateTimeInterface) {
            return parent::convertToPHPValue($value, $platform);
        }

        return parent::convertToPHPValue("$value+0000", $platform);
    }

    #[\Override]
    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
    {
        if ($value instanceof \DateTime) {
            $value->setTimezone($this->getUtc());
        }

        return parent::convertToDatabaseValue($value, $platform);
    }

    #[\Override]
    protected function getFormat(AbstractPlatform $platform): string
    {
        return $platform->getDateTimeFormatString();
    }

    protected function postConvert(\DateTime $converted): void {}
}

En lecture (convertToPHPValue), si la valeur est une chaîne brute, on y ajoute +0000 avant de déléguer au parent. Le parent utilise ensuite ce suffixe de timezone pour créer correctement l’objet PHP.

En écriture (convertToDatabaseValue), on force le DateTime en UTC avant de le formater. Ce qui va en base est toujours en UTC.

UTCDateType

Pour les colonnes date (sans composante horaire), même approche avec une étape supplémentaire :

class UTCDateType extends DateType
{
    use UTCDate;

    #[\Override]
    protected function getFormat(AbstractPlatform $platform): string
    {
        return $platform->getDateFormatString();
    }

    protected function postConvert(\DateTime $converted): void
    {
        $converted->setTime(0, 0, 0);
    }
}

La méthode postConvert() remet l’heure à 00:00:00 après le parsing. Sans elle, un champ date pourrait revenir avec 23:59:59 ou 00:00:00+02:00 selon la timezone du serveur, ce qui casse les comparaisons et le tri.

Enregistrement dans Symfony

La partie décisive : déclarer les types sous leurs noms natifs dans config/packages/doctrine.yaml.

doctrine:
    dbal:
        types:
            date:
                class: App\Doctrine\DBAL\Types\UTCDateType
            datetime:
                class: App\Doctrine\DBAL\Types\UTCDateTimeType

C’est tout. Doctrine échange ses propres implémentations contre les nôtres. Les entités existantes ne changent pas, les migrations ne bougent pas, les annotations restent type: Types::DATETIME_MUTABLE. Le comportement change globalement, sans friction.

12 microservices, 89 colonnes, un bloc de config

Ces deux types tournent maintenant sur 12 microservices indépendants, chacun avec sa propre config Doctrine, couvrant 89 colonnes de production. Les serveurs CI tournent en UTC, les machines de dev en Europe/Paris, les données voyagent entre eux sans dériver. Ce n’est pas spectaculaire. C’est juste fiable.

La vraie leçon n’est pas technique : un problème de timezone non résolu est un problème d’intégrité des données. Les décalages s’accumulent silencieusement, les comparaisons se trompent, les exports deviennent inexacts. Deux lignes de config et trois classes peuvent prévenir ça définitivement.

Les types nullables

La 7.0 permettait de déclarer string $name comme type de paramètre. Ce qu’elle ne permettait pas, c’était de dire “ça peut aussi être null”. On devait soit abandonner le type hint complètement, soit bricoler autour. La 7.1 ajoute le préfixe ? :

function findUser(?int $id): ?User {
    if ($id === null) return null;
    return $this->repository->find($id);
}

Ça semble mineur. Ce n’est pas le cas. Les types nullables font la différence entre une signature qui dit ce que fait une fonction et une qui ment par omission. Chaque codebase sur lequel j’ai travaillé a des fonctions qui peuvent retourner null. Maintenant on peut vraiment le dire plutôt que de le cacher dans un docblock.

Le type de retour void

Le complément du nullable : une fonction qui ne retourne intentionnellement rien :

public function process(Order $order): void {
    $this->dispatcher->dispatch(new OrderProcessed($order));
}

void rend l’intention explicite et empêche de retourner accidentellement une valeur depuis une fonction qui ne devrait pas. Combiné aux types nullables, le système de types de PHP en 7.1 est bien plus expressif qu’en 7.0.

La visibilité des constantes de classe

Un petit correctif mais bienvenu. Les constantes dans les classes étaient toujours publiques avant la 7.1. Maintenant :

class Config {
    private const DB_PASSWORD = 'secret';
    protected const VERSION = '2.0';
    public const MAX_RETRIES = 3;
}

Garder les détails d’implémentation privés, ça compte. Ça aurait dû exister depuis le début.

Attraper plusieurs exceptions

try {
    // ...
} catch (InvalidArgumentException | RuntimeException $e) {
    // gérer les deux
}

Évite un bloc catch dupliqué quand deux exceptions nécessitent un traitement identique. Simple, utile.

Déstructurer des tableaux sans list()

list() est dans PHP depuis la 4.0 et a toujours semblé un peu à côté syntaxiquement. La 7.1 ajoute un raccourci avec [] qui se lit bien plus naturellement :

[$first, $second] = $coordinates;

foreach ($rows as [$id, $name, $email]) {
    // ...
}

Elle gagne aussi le support des clés, ce qui rend la déstructuration de tableaux associatifs enfin utilisable :

['id' => $id, 'name' => $name] = $user;

foreach ($records as ['id' => $id, 'status' => $status]) {
    // ...
}

Avant ça, extraire des clés nommées d’un tableau signifiait soit extract() (qui déverse tout dans le scope et invite les collisions) soit un tas d’assignations individuelles. C’est juste plus propre.

Le type iterable

Si on écrit une fonction qui accepte soit un tableau soit un générateur, il n’y avait pas de type hint propre pour ça en 7.0. On typait soit en array et on excluait silencieusement les générateurs, soit on abandonnait le hint complètement :

function processItems(iterable $items): void {
    foreach ($items as $item) {
        $this->handle($item);
    }
}

iterable accepte tout ce sur quoi on peut faire un foreach : les tableaux et les implémentations de Traversable. Ça fonctionne aussi comme type de retour. Pas dramatique, mais ça comble un vrai manque.

Les offsets négatifs sur les chaînes

L’indexation de chaînes avec [] ou {} accepte maintenant les valeurs négatives, en comptant depuis la fin :

$str = 'hello';
echo $str[-1]; // "o"
echo $str[-2]; // "l"

Plusieurs fonctions de chaînes ont reçu le même traitement : strpos(), substr(), substr_count() et d’autres acceptent maintenant un offset négatif. Cohérent avec ce que Python fait depuis toujours. Mieux vaut tard que jamais.

Closure::fromCallable()

Avant ça, convertir un callable (comme [$object, 'method'] ou une chaîne nom de fonction) en une vraie Closure nécessitait Closure::bind() ou bindTo() avec une gestion de portée délicate. La 7.1 ajoute une méthode de fabrique statique :

class Processor {
    private function transform(string $value): string {
        return strtoupper($value);
    }

    public function getTransformer(): Closure {
        return Closure::fromCallable([$this, 'transform']);
    }
}

La closure résultante capture le bon $this et la bonne portée. C’est particulièrement utile quand on passe des méthodes comme callbacks à des fonctions qui attendent un callable, ou quand on construit des pipelines.

ArgumentCountError

En PHP 7.0, appeler une fonction définie par l’utilisateur avec trop peu d’arguments générait un warning et l’exécution continuait avec des paramètres remplis à null. En 7.1, ça lève une ArgumentCountError :

function connect(string $host, int $port): void { /* ... */ }

try {
    connect('localhost'); // Lève ArgumentCountError
} catch (\ArgumentCountError $e) {
    // ...
}

ArgumentCountError étend TypeError, qui étend Error. Les call sites qui se dégradaient silencieusement auparavant échouent maintenant bruyamment. C’est un risque de migration si on a du code qui comptait sur le comportement permissif, mais honnêtement, c’est la bonne décision.

La 7.1 est le genre de version qui fait davantage faire confiance à une plateforme. La core team regardait clairement les frictions, pas seulement les titres à faire valoir.

Le chiffre phare : 2x plus rapide que PHP 5.6. Ce n’est pas un benchmark cherry-pick — c’est la médiane sur des applications réelles. Le Zend Engine a été réécrit pour utiliser une nouvelle représentation interne des valeurs, ce qui réduit significativement l’utilisation mémoire et diminue les allocations. Sur un projet, le temps de réponse moyen a chuté de 40% sans aucune modification du code. On met à jour, et ça va plus vite.

Mais les performances ne sont pas la partie la plus intéressante.

Les types, enfin

PHP a eu les type hints pour les objets depuis la 5.0, pour les tableaux depuis la 5.1. En 7.0, on peut enfin déclarer des types scalaires pour les paramètres de fonctions et les valeurs de retour :

function add(int $a, int $b): int {
    return $a + $b;
}

En mode strict (declare(strict_types=1)), passer un float à cette fonction lève une TypeError. En mode coercitif par défaut, PHP convertit la valeur. Cette distinction compte : le mode strict est par fichier, on peut donc l’adopter progressivement sans tout casser d’un coup.

Les déclarations de type de retour constituent l’autre moitié. Placer l’intention dans la signature plutôt que dans un docblock signifie que c’est le moteur qui l’applique, pas un code reviewer à moitié endormi.

L’opérateur null coalescent

?? est petit mais utilisé en permanence :

$username = $_GET['user'] ?? 'guest';

Ça remplace isset($_GET['user']) ? $_GET['user'] : 'guest'. Il se chaîne aussi : $a ?? $b ?? $c. Après des années de bruit avec isset(), ça seul valait la mise à jour.

La partie qui casse

La refonte de la gestion des erreurs est le vrai risque lors de la migration. Beaucoup d’erreurs fatales sont maintenant des exceptions Error, attrapables mais différentes des Exception. Le code qui comptait sur les erreurs fatales pour stopper l’exécution silencieusement a maintenant besoin d’une gestion explicite. La suppression d’erreurs avec @ fonctionne aussi différemment par endroits.

Lire le guide de migration avant de toucher une appli en production. Le gain est réel, mais le fossé entre 5.6 et 7.0 est le plus large que PHP ait jamais eu.

L’opérateur vaisseau spatial

<=> est un opérateur de comparaison combiné qui retourne -1, 0 ou 1. Il est surtout là pour le tri :

usort($users, function ($a, $b) {
    return $a->age <=> $b->age;
});

Avant ça, un comparateur de tri personnalisé était un petit exercice de mémoire arithmétique. $a - $b fonctionne pour les entiers mais plante silencieusement pour les flottants. <=> fait ce qu’il faut pour chaque type comparable.

Les classes anonymes

On peut maintenant instancier une classe définie en ligne, sur le moment, sans lui donner de nom :

$logger = new class($config) implements LoggerInterface {
    public function __construct(private array $config) {}

    public function log(string $message): void {
        file_put_contents($this->config['path'], $message . PHP_EOL, FILE_APPEND);
    }
};