PHP Stream

PHP Streams

Un stream en PHP est une façon générique de lire ou d'écrire un flux de données, quel que soit l'endroit où ces données se trouvent. Un fichier sur disque, un bloc de mémoire, un socket réseau et le corps d'une réponse HTTP sont des choses très différentes, mais PHP vous permet de les gérer avec le même ensemble de fonctions. Cette uniformité est l'essentiel : une fois que vous savez lire un fichier avec fopen()/fgets(), vous savez déjà lire une page web ou un tampon mémoire.

Cette page explique ce que sont les streams, les fonctions qui les pilotent, les wrappers qui identifient la source d'un stream, et comment les utiliser en toute sécurité.

Quel problème les streams résolvent-ils ?

Sans les streams, vous auriez besoin d'une API différente pour chaque source de données — une pour les fichiers, une autre pour HTTP, une autre pour les sockets. Les streams vous offrent une abstraction unique :

• Wrapper — un préfixe comme file://, php://, http://, ou php://memory qui indique à PHP quel type de ressource vous adressez.
• Handle de ressource — la valeur retournée par fopen() ; vous la passez à toutes les autres fonctions de stream.
• Filtres et contextes — des couches optionnelles qui transforment les données (ex. : gzip) ou configurent la connexion (ex. : en-têtes HTTP, délais d'attente).

Grâce à cette conception, vous pouvez remplacer un chemin local par une URL distante et la majeure partie de votre code reste identique.

Fonctions principales des streams

Ces fonctions forment la colonne vertébrale de l'API Streams :

Le paramètre $mode contrôle l'accès : 'r' (lecture), 'w' (écriture, avec troncature), 'a' (ajout), et les variantes '+' pour la lecture et l'écriture.

Pour des lectures et écritures ponctuelles, vous n'avez généralement pas besoin de gérer un handle du tout — les assistants de haut niveau file_get_contents() et file_put_contents() ouvrent, transfèrent et ferment un stream pour vous en un seul appel.

Wrappers et types de streams

Le wrapper au début de la chaîne cible détermine le type de stream :

• Streams de fichiers (file://, ou simplement un chemin nu) — lit et écrit des données sur le système de fichiers. Voir PHP File Handling et Open and Read a File.
• Streams mémoire (php://memory, php://temp) — un tampon en lecture/écriture qui réside en RAM ; idéal pour construire des données dans des tests sans toucher le disque.
• Streams I/O (php://stdin, php://stdout, php://input) — entrée/sortie standard et le corps brut de la requête.
• Streams réseau / socket (tcp://, ssl://) — lit et écrit via une connexion réseau.
• Streams HTTP/FTP (http://, https://, ftp://) — récupère des documents distants comme s'ils étaient des fichiers (nécessite que allow_url_fopen soit activé).

Lecture d'un fichier ligne par ligne

Cet exemple minimal et autonome écrit un petit fichier, le relit via un stream une ligne à la fois, puis effectue le nettoyage :

<?php

$path = sys_get_temp_dir() . '/stream-demo.txt';

// Write three lines using the high-level helper.
file_put_contents($path, "alpha\nbeta\ngamma\n");

// Read them back through a stream handle.
$handle = fopen($path, 'r');
if ($handle === false) {
    exit("Could not open the stream.\n");
}

while (!feof($handle)) {
    $line = fgets($handle);
    if ($line !== false) {
        echo "Line: " . trim($line) . PHP_EOL;
    }
}

fclose($handle);
unlink($path);

Résultat :

Line: alpha
Line: beta
Line: gamma

Nous ouvrons le fichier en mode lecture, bouclons jusqu'à ce que feof() signale la fin, et lisons chaque ligne avec fgets(). Vérifiez toujours que fopen() n'a pas retourné false avant d'utiliser le handle, et appelez fclose() lorsque vous avez terminé.

Utilisation d'un stream mémoire

Les streams mémoire se comportent comme des fichiers mais ne touchent jamais le disque — utiles pour assembler des sorties ou pour des tests unitaires :

<?php

$handle = fopen('php://memory', 'r+');

fwrite($handle, "buffered data");

// Rewind to the start before reading what we wrote.
rewind($handle);

echo fread($handle, 1024);

fclose($handle);

Résultat :

buffered data

Après l'écriture, vous devez rewind() le pointeur vers le début avant de lire, car la position interne se trouve à la fin de ce que vous venez d'écrire.

Lecture d'un stream distant

Comme HTTP n'est qu'un autre wrapper, la même boucle fonctionne avec une URL lorsque allow_url_fopen est activé :

<?php

$handle = fopen('https://www.example.com', 'r');
if ($handle === false) {
    exit("Failed to open the remote stream.\n");
}

while (!feof($handle)) {
    echo fgets($handle);
}

fclose($handle);

Cet exemple nécessite un accès réseau et le paramètre allow_url_fopen activé, il ne fonctionnera donc pas dans un bac à sable hors ligne. Pour de vraies applications, un client HTTP dédié tel que cURL vous offre un meilleur contrôle sur les en-têtes, les délais d'attente et les erreurs.

Gestion des erreurs

Les fonctions de stream signalent les échecs en retournant false plutôt qu'en levant une exception, il faut donc surveiller chaque appel :

• Vérifiez la valeur de retour de fopen() avant de lire ou d'écrire.
• Enveloppez les opérations risquées dans try/catch si vous convertissez les avertissements en exceptions — voir PHP Exceptions.
• Appelez toujours fclose() sur les handles que vous ouvrez pour libérer les ressources.

Conclusion

Les streams offrent à PHP une interface unique et cohérente pour chaque type de flux de données — fichiers, tampons mémoire, sockets et réponses HTTP. Apprenez le petit ensemble de fonctions principales (fopen, fread/fgets, fwrite, feof, fclose), comprenez les wrappers comme file:// et php://memory, et appuyez-vous sur les assistants de haut niveau file_get_contents()/file_put_contents() pour les cas simples. Pour aller plus loin, explorez la création et l'écriture de fichiers et la gestion des erreurs.

Pratique