Compression

OxPHP compresse les réponses HTTP avec Brotli, Zstandard ou gzip, selon ce que le client accepte. La compression s'applique automatiquement à une liste fixe de types de contenu (texte, JSON, XML, SVG, WebAssembly et plusieurs formats de polices), de sorte que la taille des transferts diminue sans aucune modification du code de votre application.

Fonctionnement

L'en-tête Accept-Encoding du client est lu une seule fois, avant que la requête n'atteigne le pipeline de routage, et confronté aux encodages que le serveur propose. La suite dépend de la provenance des octets.

Un fichier statique en cache qui dispose déjà d'une copie compressée stockée est servi directement depuis cette copie. Rien n'est compressé pendant la requête, et aucune des vérifications ci-dessous ne s'applique. Voir Fichiers statiques en cache.

Toutes les autres réponses (sortie PHP, page d'erreur personnalisée, fichier statique sans copie stockée pour l'instant) passent par les mêmes vérifications, dans cet ordre, une fois la réponse construite :

1. Les réponses partielles sont ignorées. Une réponse 206 n'est jamais encodée, car les positions de son Content-Range décrivent la représentation non encodée.
2. Vérification du type de contenu. Le type MIME de la réponse est recherché dans la liste des types compressibles.
3. Vérification d'un encodage préexistant. Une réponse qui porte déjà un en-tête Content-Encoding est laissée telle quelle.
4. Vérification de la taille. Seuls les corps compris entre 256 octets et 3 Mio (3 145 728 octets), bornes incluses, sont compressés. L'en-tête Content-Length est utilisé lorsque la réponse en porte un ; les réponses PHP n'en ont généralement pas et sont mesurées sur le corps mis en tampon.
5. Compression. L'encodage négocié est appliqué à son niveau configuré. Si la sortie compressée n'est pas plus petite que l'originale, c'est la réponse non compressée qui est envoyée à la place.

Les petits corps sont compressés en ligne ; au-delà d'un seuil, le travail passe sur un thread bloquant afin de ne pas paralyser le runtime asynchrone. Ce seuil est de 64 Kio et descend à 4 Kio dès que le niveau est assez élevé pour que la courbe de coût s'infléchisse : au-dessus de la qualité 4 pour Brotli, du niveau 6 pour gzip, du niveau 9 pour Zstandard. Avec les valeurs livrées par défaut, Brotli se trouve déjà dans la partie raide, si bien que les corps Brotli de plus de 4 Kio sont compressés hors du thread asynchrone.

flowchart TD
    AE["Accept-Encoding, read once per request"]
    W["Ranked by weight. A coding the server<br/>does not offer scores zero and drops out"]
    Q{"Is a stored copy<br/>being served?"}
    A["Tie broken br, then zstd, then gzip.<br/>Built once at br 11, zstd 19, gzip 9"]
    P["Tie broken zstd, then br, then gzip.<br/>Compressed now at the configured<br/>zstd 6, br 5, gzip 6"]
    H["Content-Encoding, recomputed Content-Length,<br/>Vary, weakened ETag, no Accept-Ranges"]
    AE --> W
    W --> Q
    Q -->|yes| A
    Q -->|no| P
    A --> H
    P --> H

Choisir un encodage

Accept-Encoding classe les encodages par poids (RFC 9110 §12.5.3), et OxPHP le lit ainsi :

• Les noms d'encodage sont comparés sans tenir compte de la casse, et les encodages inconnus sont ignorés.
• br;q=0 refuse Brotli. Ce n'est pas la même chose que d'omettre l'encodage : un * peut encore couvrir un encodage omis, mais pas un encodage explicitement refusé.
• Un * couvre tout encodage que l'en-tête ne nomme pas explicitement, avec le poids qui lui est attribué.
• Un poids illisible laisse l'encodage au poids par défaut ; un paramètre mal formé ne l'élimine pas. Cela compte pour q=0. Une qvalue comporte au plus trois décimales : q=0.000 refuse donc l'encodage, tandis que q=0.0000 n'est pas un poids valide du tout et se lit comme une acceptation complète. Un encodage nommé deux fois est lu avec son premier poids.
• Parmi les encodages que le client accepte et que le serveur propose, celui qui a le poids le plus élevé l'emporte. Un encodage retiré par la configuration reçoit un score nul avant le classement : un client dont l'encodage favori n'est pas proposé par le serveur passe donc à son choix suivant plutôt qu'à une réponse non compressée.
• Un en-tête qui n'accepte rien (vide, ou *;q=0) donne une réponse non encodée. OxPHP ne répond jamais 406 pour une question d'encodage de contenu, et ne lit jamais identity comme un jeton.

Les poids sont à égalité dans le cas habituel, puisque les navigateurs envoient tous les encodages qu'ils prennent en charge sans poids. OxPHP départage alors selon ce que deviennent les octets compressés :

La première ligne ne s'applique qu'une fois la copie stockée disponible. Les accès qui la précèdent, et tout fichier trop volumineux pour le cache, relèvent de la seconde ligne : c'est pourquoi une ressource statique est généralement servie en Zstandard avant de l'être en Brotli.

La préférence ne sert qu'à départager. Un client qui écrit br;q=0.2, gzip;q=0.9 reçoit du gzip sur les deux chemins, et la copie stockée construite pour lui est une copie gzip.

Un client qui n'accepte aucun des trois reçoit la réponse non encodée. En pratique, gzip sert de repli : tous les clients HTTP des vingt dernières années l'acceptent, alors que Zstandard exige un navigateur sorti en 2024 ou après.

Vary: Accept-Encoding

Comme la réponse dépend de l'en-tête de la requête, toute réponse située dans la fenêtre de compression porte Vary: Accept-Encoding, qu'elle soit compressée ou non, statique ou dynamique. Une représentation que le serveur encoderait pour un autre client varie selon cet en-tête même lorsque ce client-ci reçoit les octets identité, et un cache partagé à qui l'on dirait le contraire transmettrait ces octets à un client ayant demandé un encodage.

Deux cas échappent à cette règle :

• Une réponse dynamique que le serveur ne détient jamais en entier (tout ce qui est diffusé en flux au fil de la production PHP) ne porte pas de Vary : ce chemin ne peut compresser sous aucun en-tête, la réponse ne varie donc réellement pas. Un fichier statique assez volumineux pour être diffusé en flux n'appartient pas à ce groupe et porte bien l'en-tête, car le même fichier est lu en entier et compressé pour un client qui a négocié un encodage.
• Une réponse 304 ne porte ni Vary ni Content-Encoding : elle rafraîchit une représentation que le client détient déjà au lieu d'en décrire une nouvelle.

Vary est ajouté sur sa propre ligne d'en-tête au lieu d'être fusionné avec celle que l'application a déjà envoyée : une réponse qui a défini Vary: Cookie part donc avec deux lignes Vary. C'est légal, et OxPHP les lit toutes avant d'ajouter la sienne afin de ne jamais dupliquer Accept-Encoding, mais un intermédiaire qui ne lit que la première ligne la manquera.

Fichiers statiques en cache

Un fichier statique qui tient dans le cache de contenu (1 Mio ou moins) et qui est compressible (type listé, au moins 256 octets) est compressé une seule fois plutôt qu'à chaque requête.

1. 1
   Première requête : défaut de cache. Le fichier est lu sur le disque, stocké, et compressé pour cette requête comme n'importe quelle autre réponse.
2. 2
   Requête suivante : construction déclenchée. Le fichier est en cache, et s'il n'existe pas encore de copie stockée pour l'encodage négocié par cette requête, le serveur en demande la construction sur un thread d'arrière-plan. La requête qui a déclenché la construction est servie de la manière habituelle, par compression à la requête, tout comme chaque requête qui arrive pendant la construction.
3. 3
   La copie est prête. Les requêtes suivantes qui négocient le même encodage sont servies depuis la copie stockée.

Il n'y a pas de compteur d'accès : le déclencheur est le premier accès au cache sans copie stockée pour cet encodage. Un fichier qui n'a jamais été servi qu'à des clients gzip obtient donc sa copie Brotli au premier client Brotli qui le demande.

Les copies stockées sont construites au niveau maximal de chaque encodage (Brotli 11, Zstandard 19, gzip 9), indépendamment des niveaux configurés pour la compression à la requête, qu'une copie stockée n'utilise jamais. Aucun réglage distinct ne les concerne : le seul moyen d'empêcher leur construction est de retirer entièrement l'encodage. La qualité maximale produit généralement 8 à 12 % d'octets en moins que le niveau de Brotli utilisé à la requête.

Chaque encodage a sa propre copie stockée, construite à la demande : un fichier servi uniquement à des clients gzip ne coûte donc jamais une compression Brotli. Toutes partagent le validateur du fichier en cache et sont jetées en même temps que les octets en cache : lorsque l'entrée est évincée pour rester dans le budget de cache de 64 Mio, auquel les copies stockées sont imputées, ou lorsque STATIC_REVALIDATE est activé et remarque que le fichier a changé sur le disque. Ce réglage est désactivé par défaut : sur un déploiement par défaut, l'éviction et le redémarrage sont donc les deux seules façons dont une copie stockée est jetée. Les octets qui ne se compressent pas sont marqués comme tels et ne sont pas retentés, et une réponse 304 ne déclenche aucune construction et ne sert aucune copie stockée.

Fichiers trop volumineux pour le cache

Entre la limite du cache et le haut de la fenêtre de compression (de 1 Mio à 3 Mio, là où vivent les bundles de frameworks, les source maps et les modules WebAssembly), un fichier est lu en entier et compressé à chaque requête, dès que le client a négocié un encodage et que le type est compressible. Il n'est pas mis en cache et n'obtient jamais de copie stockée : c'est la compression la plus coûteuse que le serveur effectue par requête.

La lecture d'un tel fichier le garde en mémoire jusqu'à ce que la réponse soit écrite, si bien que seul un nombre limité d'entre eux est lu à la fois. Une requête qui arrive au-delà de cette limite reçoit le fichier diffusé en flux et non encodé plutôt que d'attendre qu'une place se libère. Sous une charge soutenue sur une ressource volumineuse, certains clients la reçoivent donc compressée et d'autres non ; les deux réponses sont correctes pour l'URL, et Vary: Accept-Encoding est présent dans les deux cas.

En dehors de ce cas, un fichier de plus de 1 Mio est diffusé en flux depuis le disque sans modification : type non compressible, client qui n'accepte aucun encodage, ou tout ce qui dépasse 3 Mio.

Ce que coûte un fichier statique, selon sa taille :

flowchart TD
    F["Static file"]
    C1{"256 B or larger?"}
    C2{"1 MiB or smaller?"}
    C3{"3 MiB or smaller?"}
    N1["Sent as-is, and cached.<br/>The framing would cost more than it saves"]
    N2["Cached, and a stored copy is built once<br/>in the background on the first cache hit"]
    N3["Read whole and compressed on every request.<br/>Too large to cache, so no copy is kept"]
    N4["Streamed from disk, never compressed.<br/>Past the compression window"]
    F --> C1
    C1 -->|no| N1
    C1 -->|yes| C2
    C2 -->|yes| N2
    C2 -->|no| C3
    C3 -->|yes| N3
    C3 -->|no| N4

Ce parcours suppose un type compressible et un client qui a négocié un encodage. Retirez l'une ou l'autre condition : le fichier est mis en cache jusqu'à 1 Mio, diffusé en flux au-delà, les plages sont honorées partout, et rien n'est encodé nulle part.

Configuration

Un encodage est proposé lorsqu'il figure dans COMPRESSION_ENCODINGS et que son niveau n'est pas 0 ; l'une ou l'autre condition suffit à le retirer. Un encodage retiré disparaît de toute la fonctionnalité : il n'est jamais négocié, jamais compressé sur le chemin de la requête et jamais construit en copie stockée.

Pourquoi ces valeurs par défaut

• Brotli 5, et non 4. Le coude de qualité de Brotli (un changement de fonction de hachage) se situe entre les deux. À 4, il produisait plus d'octets que gzip à son propre niveau par défaut sur du JSON de plus de 4 Ko et sur de vraies ressources minifiées, en consommant davantage de CPU, ce qui ne laisse aucune raison de le préférer à gzip. À 5, il est le plus compact des deux sur tous les corps mesurés, pour environ deux fois le CPU de gzip.
• Gzip 6. Le niveau par défaut de zlib lui-même, proche du point de rendement décroissant. Le niveau 9 coûte environ deux fois plus pour un ou deux pour cent.
• Zstandard 6, et non son propre défaut de 3. Sur les corps de plus de quelques kilo-octets, le niveau 6 coûte moins de temps que la qualité Brotli avec laquelle les versions précédentes compressaient tout, tout en produisant moins d'octets : rien ne régresse par rapport à ce qu'envoyaient ces versions.

Les niveaux 9 à 11 conviennent mieux à une compression hors ligne ou effectuée au moment de la construction qu'au travail par requête ; les fichiers statiques en cache les utilisent malgré tout, car ce coût n'est payé qu'une fois.

Types de contenu compressibles

La liste est fermée : il n'existe aucune règle de préfixe ni de joker, donc un type absent de la liste n'est jamais compressé, même s'il se compresserait bien. À l'intérieur de la liste, la correspondance est tolérante. Les paramètres et les espaces autour sont supprimés et le type lui-même est comparé sans tenir compte de la casse : text/html; charset=utf-8 et Application/JSON correspondent tous deux.

Types texte :

• text/html
• text/css
• text/plain
• text/xml
• text/javascript

Types application :

• application/javascript
• application/json
• application/xml
• application/xhtml+xml
• application/rss+xml
• application/atom+xml
• application/manifest+json
• application/ld+json
• application/wasm

Autres types :

• image/svg+xml
• font/ttf
• font/otf
• application/x-font-ttf
• application/x-font-opentype
• application/vnd.ms-fontobject

Non compressé

Les réponses sont envoyées sans compression lorsque l'une des conditions suivantes est remplie :

• Le client n'accepte aucun de br, zstd et gzip dans l'en-tête Accept-Encoding, ne les accepte qu'avec un poids nul (br;q=0, zstd;q=0, gzip;q=0), ou n'envoie pas cet en-tête du tout
• Chaque encodage accepté par le client a été retiré par COMPRESSION_ENCODINGS ou par un niveau de 0
• La réponse possède déjà un en-tête Content-Encoding (par exemple un contenu pré-compressé produit par l'application)
• Le corps de la réponse fait moins de 256 octets ou plus de 3 Mio
• La réponse est un 206 Partial Content : les positions de la plage décrivent la représentation non encodée, un corps partiel n'est donc jamais encodé
• Le type de contenu ne figure pas dans la liste ci-dessus. image/png, image/jpeg, font/woff2 et application/zip sont exclus parce que ces formats embarquent déjà leur propre compression, et text/event-stream parce qu'un flux d'événements doit parvenir au client événement par événement. text/csv, application/pdf, image/x-icon et une réponse sans aucun Content-Type sont également exclus, parce qu'ils ne figurent pas dans la liste
• Le serveur ne détient pas le corps en entier : scripts PHP utilisant oxphp_stream_flush(), Server-Sent Events, et fichiers statiques lus sur le disque au fil de leur envoi. OxPHP compresse une réponse d'un seul tenant. Brotli, Zstandard et gzip savent tous encoder de manière incrémentale : il s'agit donc d'une limite du serveur et non des encodages
• La réponse provient d'un plugin qui a répondu avant l'exécution du pipeline, comme un 429 de limitation de débit, qui revient avant l'étape de compression
• La réponse provient de l'écouteur interne (INTERNAL_ADDR), qui sert /metrics et les endpoints de santé sans encodage, quoi qu'accepte le collecteur

En-têtes de réponse

Une réponse que le serveur encode est réécrite comme suit, qu'elle ait été compressée pour cette requête ou servie depuis une copie stockée :

Tous les encodages d'un même fichier statique partagent cette étiquette faible, dérivée de la taille identité et de la date de modification. C'est Vary qui sépare les variantes ; l'étiquette ne décide que de la fraîcheur, si bien qu'un cache qui revalide une variante ne peut pas indiquer au serveur laquelle il détient.

Observabilité

Deux compteurs de l'endpoint de métriques indiquent ce que la compression a réellement fait :

• oxphp_compressed_responses_total : réponses envoyées sous un encodage de contenu
• oxphp_compression_bytes_saved_total : taille identité moins taille compressée, cumulée

Les deux comptent les accès aux copies stockées aussi bien que les compressions à la requête : un ratio par rapport à oxphp_requests_total répond donc à la question « la compression atteint-elle mon trafic ? » de façon plus fiable qu'un simple curl -I.

Dépannage

Exemple Docker

Prompts pour votre agent

Ces prompts supposent un agent connecté au serveur MCP de la documentation OxPHP — il lira lui-même les pages dont il a besoin.

Voir aussi

• Fichiers statiques — service de fichiers, détection MIME et mise en cache HTTP
• Métriques — les compteurs de compression et le reste de l'endpoint
• Référence de configuration — liste complète des variables d'environnement