PSR 07 - HTTP Message Interface

Les messages HTTP sont à la base du développement Web. Les navigateurs Web et les clients HTTP tels que cURL créent des messages de requête HTTP qui sont envoyés à un serveur Web, qui fournit un message de réponse HTTP. Le code côté serveur reçoit un message de requête HTTP et renvoie un message de réponse HTTP.

Les messages HTTP sont généralement extraits du consommateur final, mais en tant que développeurs, nous avons généralement besoin de savoir comment ils sont structurés et comment y accéder ou les manipuler afin d'effectuer nos tâches, qu'il s'agisse de faire une demande à une API HTTP. , ou le traitement d'une demande entrante.

Chaque message de requête HTTP a une forme spécifique :

POST /path HTTP/1.1
Host: example.com

foo=bar&baz=bat

La première ligne d'une requête est la « ligne de requête » et contient, dans l'ordre, la méthode de requête HTTP, la cible de la requête (généralement un URI absolu ou un chemin sur le serveur Web) et la version du protocole HTTP. Ceci est suivi d'un ou plusieurs en-têtes HTTP, d'une ligne vide et du corps du message.

Les messages de réponse HTTP ont une structure similaire :

HTTP/1.1 200 OK
Content-Type: text/plain

La première ligne est la “ligne d'état” et contient, dans l'ordre, la version du protocole HTTP, le code d'état HTTP et une "phrase de raison", une description lisible par l'homme du code d'état. Comme le message de requête, il est ensuite suivi d'un ou plusieurs en-têtes HTTP, d'une ligne vide et du corps du message.

Les interfaces décrites dans ce document sont des abstractions autour des messages HTTP et des éléments qui les composent.

Les messages

Un message HTTP est soit une requête d'un client à un serveur, soit une réponse d'un serveur à un client. Cette spécification définit les interfaces pour les messages HTTP Psr\Http\Message\RequestInterface et Psr\Http\Message\ResponseInterface respectivement.

Les deux Psr\Http\Message\RequestInterface et Psr\Http\Message\ResponseInterface étendent Psr\Http\Message\MessageInterface. Bien que Psr\Http\Message\MessageInterface peuvent être implémentés directement, les implémenteurs doivent être implémenter Psr\Http\Message\RequestInterface et Psr\Http\Message\ResponseInterface.

À partir de maintenant, l'espace de noms Psr\Http\Message sera omis lors de la référence à ces interfaces.

Les en-têtes

Les messages HTTP incluent des noms de champs d'en-tête insensibles à la casse. Les en-têtes sont récupérés par nom à partir des classes implémentant le MessageInterface d'une manière insensible à la casse. Par exemple, la récupération de l'en-tête Foo renverra le même résultat que la récupération de l'en-tête Foo. De même, la définition de l'en-tête Foo écrasera toute valeur d'en-tête précédemment définie.

exemple :

$message = $message->withHeader('foo', 'bar');

echo($message->getHeaderLine('foo'));

echo($message->getHeaderLine('FOO'));

$message = $message->withHeader('fOO', 'baz');
echo($message->getHeaderLine('foo'));

Bien que les en-têtes puissent être récupérés sans tenir compte de la casse, la casse d'origine doit être préservée par la mise en œuvre, en particulier lorsqu'elle est récupérée avec getHeaders().

Les applications HTTP non conformes peuvent dépendre d'un certain cas, il est donc utile pour un utilisateur de pouvoir dicter la casse des en-têtes HTTP lors de la création d'une demande ou d'une réponse.

Afin de prendre en charge les en-têtes avec plusieurs valeurs tout en offrant la commodité de travailler avec des en-têtes sous forme de chaînes, les en-têtes peuvent être récupérés à partir d'une instance de a MessageInterface sous forme de tableau ou de chaîne. Utilisez la getHeaderLine() méthode pour récupérer une valeur d'en-tête sous forme de chaîne contenant toutes les valeurs d'en-tête d'un en-tête insensible à la casse par nom concaténé avec une virgule. Utilisez getHeader() pour récupérer un tableau de toutes les valeurs d'en-tête pour un en-tête particulier insensible à la casse par nom.

exemple :

$message = $message
    ->withHeader('foo', 'bar')
    ->withAddedHeader('foo', 'baz');

$header = $message->getHeaderLine('foo');

$header = $message->getHeader('foo');

Remarque : toutes les valeurs d'en-tête ne peuvent pas être concaténées à l'aide d'une virgule (par exemple, Set-Cookie). Lorsqu'ils travaillent avec de tels en-têtes, les consommateurs des classes basées sur MessageInterface devraient s'appuyer sur la méthode getHeader() pour récupérer ces en-têtes à valeurs multiples.

Dans les requêtes, l'en-tête reflète généralement le composant hôte de l'URI, ainsi que l'hôte utilisé lors de l'établissement de la connexion TCP. Cependant, la spécification HTTP permet à l'en-tête de différer de chacun des deux.

Pendant la construction, les mises en œuvre doivent tenter de définir l'en-tête à partir d'un URI fourni si aucun en-tête n'est fourni.

RequestInterface::withUri() remplacera, par défaut, l'en-tête de la requête envoyée par un en-tête correspondant au composant hôte du fichier UriInterface.

Vous pouvez choisir de conserver l'état d'origine de l'en-tête en passant true en deuxième argument ($preserveHost). Lorsque cet argument est défini à “true”, la demande renvoyée ne mettra pas à jour l'en-tête du message renvoyé, à moins que le message ne contient aucun en-tête.

Les messages HTTP se composent d'une ligne de départ, d'en-têtes et d'un corps. Le corps d'un message HTTP peut être très petit ou extrêmement grand. Tenter de représenter le corps d'un message sous forme de chaîne peut facilement consommer plus de mémoire que prévu, car le corps doit être entièrement stocké en mémoire. Tenter de stocker le corps d'une demande ou d'une réponse en mémoire empêcherait l'utilisation de cette implémentation de pouvoir travailler avec des corps de message volumineux. StreamInterface est utilisé afin de masquer les détails de l'implémentation lorsqu'un flux de données est lu ou écrit. Pour les situations où une chaîne serait une implémentation de messages appropriés, des flux intégrés tels que php://memory et php://temp peuvent être utilisés.

StreamInterface expose plusieurs méthodes qui permettent de lire, d'écrire et de traverser efficacement les flux.

Les flux exposent leurs capacités à l'aide de trois méthodes : isReadable(), isWritable(), et isSeekable(). Ces méthodes peuvent être utilisées par les collaborateurs du flux pour déterminer si un flux est capable de répondre à leurs besoins.

Chaque instance de flux aura différentes capacités : elle peut être en lecture seule, en écriture seule ou en lecture-écriture. Il peut également autoriser un accès aléatoire arbitraire (recherche vers l'avant ou l'arrière vers n'importe quel emplacement), ou uniquement un accès séquentiel (par exemple dans le cas d'un socket, d'un tuyau ou d'un flux basé sur un rappel).

Enfin, StreamInterface définit une __toString() méthode pour simplifier la récupération ou l'émission de tout le contenu du corps à la fois.

Contrairement aux interfaces de requête et de réponse, StreamInterface ne modélise pas l'immuabilité. Dans les situations où un flux PHP réel est encapsulé, l'immuabilité est impossible à appliquer, car tout code qui interagit avec la ressource peut potentiellement changer son état (y compris la position du curseur, le contenu, etc.). Notre recommandation est que les implémentations utilisent des flux en lecture seule pour les demandes côté serveur et les réponses côté client. Les consommateurs doivent être conscients du fait que l'instance de flux peut être modifiable et, en tant que telle, pourrait modifier l'état du message ; en cas de doute, créez une nouvelle instance de flux et attachez-la à un message pour appliquer l'état.

Les cibles de requête et URI