Manuel PHP
Précédent |  | Suivant

# CVI. Flux

# Introduction

Les flux ("streams" en anglais) ont été introduits en `PHP` 4.3.0 comme méthode de généralisation des fichiers, sockets, connexions réseau, données compressées et autres opérations du même type, qui partagent des opérations communes. Dans sa définition la plus simple, un flux est une ressource qui présente des capacités de flux : c'est à dire que ces objets peuvent être lus ou recevoir des écritures de manière linéaire, et dispose aussi de moyen d'accèder à des positions arbitraires dans le flux.

Un gestionnaire (dit `wrapper` en anglais), est une fonction qui indique comment le flux se comporte spécifiquement. C'est le cas du gestionnaire `http`, qui sait comment traduire une URL en une requête sur un serveur distant. Il existe de nombreux gestionnaires intégré à `PHP` par défaut (voir Annexe J), et de plus, des gestionnaires spécifiques peuvent être ajouté dans les scripts `PHP` avec la fonction stream_register_wrapper(), ou bien directement par une autre extension, en utilisant l'API C de Chapitre 43. Grâce à la souplesse des gestionnaires qui peuvent être ajoutés à `PHP`, il n'y a pas de limites aux possibilités offertes. Pour connaître la liste des gestionnaires actuellement enregistrés, utilisez la fonction stream_get_wrappers().

# Filtres de flux

Un `filtre` est une fonction finale qui effectue des opérations sur les données qui sont lues ou écrites dans un flux. Un nombre arbitraire de filtre peuvent être ajoutés sur un flux. Des filtres personnalisés peuvent aussi être ajoutés avec la fonction stream_register_filter(), ou bien dans une extension avec l'API C de Chapitre 43. Pour connaître la liste des gestionnaires actuellement enregistrés, utilisez la fonction stream_get_filters().

Un flux est identifié dans la forme `protocole`://`serveur`

- `protocole`(chaîne de caractères) - Le nom du protocole utilisé. Par exemple : file, http, https, ftp, ftps, compress.zlib, compress.bz2, ssl, tls et php. Voyez Annexe J pour une liste de gestionnaires intégrés à `PHP`. Si aucun gestionnaire n'est spécifié, la fonction utilise par défaut `file`://).

- `serveur` - Dépend du gestionnaire utilisé. Pour les flux liés au système de fichier, c'est généralement un chemin et un nom de fichier. Pour les objets réseau, c'est généralement un nom de serveur, et un chemin. Encore une fois, reportez vous à Annexe J pour une description des différents serveurs de gestionnaire.

# Contextes de flux

Un `contexte` est un jeu de paramètres et d'options spécifiques à un gestionnaire qui modifie ou améliore le comportement d'un flux. Les contextes sont créés en utilisant la fonction stream_context_create() et peuvent être donné aux fonctions de créations de flux sur le système de fichier (i.e. fopen(), file(), file_get_contents(), etc...).

Les options peuvent être spécifiées en appelant stream_context_create(), ou plus tard, avec stream_context_set_option(). Une liste des options spécifiques à des gestionnaires est disponible dans la liste des gestionnaires intégrés (voyez Annexe J).

De plus, les paramètres peuvent être envoyés à un contexte en utilisant la fonction stream_context_set_params(). Actuellement, le seul paramètre de contexte supporté par `PHP` est `notification`. La valeur de ce paramètre doit être le nom d'une fonction qui sera appelée lorsqu'un événement survient pour un flux. La fonction d'alerte est appelé durant la reception de l'événement, et doit accepter 6 paramètres :

void my_notifier ( int notification_code, int severity, string message, int message_code, int bytes_transferred, int bytes_max)

`notification_code` et `severity` sont des valeurs numériques qui correspondent aux constantes `STREAM_NOTIFY_*` listées ci-dessous. Si un message descriptif est disponible dans un flux, les paramètres `message` et `message_code` en seront équipés. La signification de ces valeurs est dépendante du gestionnaire. `bytes_transferred` et `bytes_max` seront fournies lorsque possible.

# Installation

Les flux font parti de `PHP` depuis la version 4.3.0. Aucune étape supplémentaire n'est requise pour les activer.

# Classes Stream

Des gestionnaires personnalisés peuvent être enregistrés via la fonction stream_register_wrapper(), en utilisant la définition de classe décrite dans ce manuel.

La classe php_user_filter est prédéfinie et est une classe abstraite à utiliser avec les filtres personnalisés. Voyez le manuel de la fonction stream_register_filter() pour plus de détails sur les implémentation de filtres utilisateurs.

# Constantes prédefinies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

Constante | Description
--- | ---
`STREAM_FILTER_READ` | Utilisée avec stream_filter_append() et stream_filter_prepend() pour indiquer que le filtre spécifié ne doit être appliqué qu'après la lecture.
`STREAM_FILTER_WRITE` | Utilisée avec stream_filter_append() et stream_filter_prepend() pour indiquer que le filtre spécifié ne doit être appliqué qu'après l' écriture.
`STREAM_FILTER_ALL` | Cette constante est équivalente à ``STREAM_FILTER_READ` | `STREAM_FILTER_WRITE``
`STREAM_USE_PATH` | Option indiquant si `stream` a utilisé l'include path.
`STREAM_REPORT_ERRORS` | Option indiquant si le gestionnaire est responsable pour la levée des erreurs avec trigger_error() durant l'ouverture du flux. Si cette constante n'existe pas, vous ne devez pas émettre d'erreurs.

# Erreurs de flux

Comme avec n'importe quel fichier ou socket, les opérations sur un flux peuvent échouer pour une grande variété de raisons (par exemple : impossible de se connecter au serveur distant, fichier introuvable, etc...). Un flux peut aussi échouer parceque le gestionnaire n'est pas configuré sur le système en cours. Voyez le tableau retourné par la fonction stream_get_wrappers() pour connaître la liste des gestionnaires configurés sur votre installation de `PHP`. Comme avec la plupart des fonctions internes de `PHP`, si une erreur survient, un message de type `E_WARNING` sera généré pour indiquer la nature de l'erreur.

# Exemples

Exemple 1. Exemples avec file_get_contents()

`<?php
// Lit un fichier local dans le dossier /home/bar
$localfile = file_get_contents("/home/bar/foo.txt");
// Identique au precedent, mais utilise explicitement le gestionnaire FILE
$localfile = file_get_contents("file:///home/bar/foo.txt");
// Lit un fichier distant sur le serveur www.exemple.com avec le protocole HTTP
$httpfile = file_get_contents("http://www.exemple.com/foo.txt");
// Lit le même fichier sur le serveur www.exemple.com avec le protocole HTTPS
$httpsfile = file_get_contents("https://www.exemple.com/foo.txt");
// Lit un fichier distant sur le serveur ftp.exemple.com en utilisant le protocole FTP
$ftpfile = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");
// Lit un fichier distant sur le serveur ftp.exemple.com en utilisant le protocole FTPS
$ftpsfile = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?>`

Exemple 2. Envoie d'une requête de type POST sur une serveur sécurisé

`<?php
/* Envoi d'une requête POST sur le serveur https://secure.example.com/form_action.php
* Inclusion des variables "foo" et "bar"
*/
$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");
$data = "foo=" . urlencode("Valeur de Foo") . "&bar=" . urlencode("Valeur de Bar");
fputs($sock, "POST /form_action.php HTTP/1.0\r\n");
fputs($sock, "Host: secure.example.com\r\n");
fputs($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fputs($sock, "Content-length: " . strlen($data) . "\r\n");
fputs($sock, "Accept: */*\r\n");
fputs($sock, "\r\n");
fputs($sock, "$data\r\n");
fputs($sock, "\r\n");
$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";
print "\n";
$body = "";
while (!feof($sock))
$body .= fgets($sock, 4096);
fclose($sock);
?>`

Exemple 3. Ecrire des données dans un fichier compressé

`<?php /* Création d'un fichier compressé contenant une chaîne arbitraire * Le fichier peut etre lu en utilisant le gestionnaire compress.zlib * ou simplement decompresse; en ligne de commande avec 'gzip -d foo-bar.txt.gz' */ $fp = fopen("compress.zlib://foo-bar.txt.gz","w"); if (!$fp) die("Impossible de créer le fichier."); fwrite($fp, "Ceci est un test.\n"); fclose($fp); ?>`

Précédent | Sommaire | Suivant
SimpleXMLIterator::valid | Niveau supérieur | stream_context_create