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 “HTTP/1.0” sur un serveur distant. Il existe de nombreux gestionnaires intégrés à PHP par défaut (voir Annexe M), et, de plus, des gestionnaires spécifiques peuvent être ajoutés dans les scripts PHP avec la fonction stream_register_wrapper(), ou bien directement par une autre extension, en utilisant l’API C de Chapitre 44. 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().

Un flux est référencé comme : “scheme”:“target” * “scheme”(chaîne de caractères) - Le nom du gestionnaire a utiliser. Par exemple, “file”, “http”, “https”, “ftp”, “ftps”, “compress.zlib”, “compress.bz”. et “php.”. Voir Annexe M pour une liste complète des gestionnaires enregistrés de PHP. Si aucun gestionnaire n’est spécifié, la fonction par défaut est utilisée (typiquement, “file”:).

• “target” - Dépend du gestionnaire utilisé. Pour les flux relatifs aux systèmes de fichiers, c’est typiquement un chemin et un nom de fichier du fichier désiré. Pour les flux relatifs aux réseaux, c’est typiquement le nom d’hôte, souvent avec un chemin apposé. Voir aussi Annexe M pour une description des cibles des flux intégrés.

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 filtres 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 44. Pour connaître la liste des gestionnaires actuellement enregistrés, utilisez la fonction stream_get_filters().

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és aux fonctions de création de flux sur le système de fichiers (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 M).

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ée durant la réception 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 si possible.

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

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. C’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émentations de filtres utilisateurs.

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.

Note : Les constantes marquées avec une “*” sont uniquement disponibles depuis PHP 5.0.0.

Note : Les constantes marquées avec une “+” sont disponibles depuis PHP 5.1.0 et sont faites pour être utilisées avec la fonction stream_socket_pair(). Notez que quelques-unes de ces constantes peuvent ne pas être disponibles sur votre système.

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 parce que 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.

<?php
/* Lit un fichier local dans le dossier /home/bar */
$localfile = file_get_contents("/home/bar/foo.txt");                         
 
/* Identique au précédent, mais utilise explicitement le gestionnaire FILE */
$localfile = file_get_contents("file:///home/bar/foo.txt");                  
 
/* Lit un fichier distant sur le serveur www.example.com avec le protocole HTTP */
$httpfile  = file_get_contents("http://www.example.com/foo.txt");
  
/* Lit le même fichier sur le serveur www.example.com avec le protocole HTTPS */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");           
 
/* Lit un fichier distant sur le serveur ftp.example.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.example.com en utilisant le protocole FTPS */
$ftpsfile  = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");  
?>

<?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";
}
 
echo "\n";
 
$body = "";
while (!feof($sock)) {
  $body .= fgets($sock, 4096);
}
 
fclose($sock);
?>

<?php
/* Création d'un fichier compressé contenant une chaîne arbitraire
 * Le fichier peut être 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);
?>

Table des matières

stream_bucket_append –  Ajoute un compartiment au corps stream_bucket_make_writeable –  Retourne un objet de compartiment depuis le corps pour des opérations sur celui-ci stream_bucket_new –  Crée un nouveau compartiment pour l’utiliser sur le flux courant stream_bucket_prepend –  Ajout initial d’un compartiment au corps stream_context_create – Crée un contexte de fluxstream_context_get_default – Lit le contexte par défaut des fluxstream_context_get_options – Lit la valeur des options pour un flux/gestionnaire/contextestream_context_set_option – Configure une option pour un flux/gestionnaire/contextestream_context_set_params – Configure les paramètres pour un flux/gestionnaire/contextestream_copy_to_stream – Copie des données depuis un flux vers un autrestream_encoding – Définit le jeu de caractères pour l’encodage du fluxstream_filter_append – Attache un filtre à un flux en fin de listestream_filter_prepend – Attache un filtre à un flux en début de listestream_filter_register – Enregistre un filtre de fluxstream_filter_remove – Supprime un filtre d’un fluxstream_get_contents – Lit le reste d’un flux dans une chaînestream_get_filters – Liste les filtres enregistrésstream_get_line – Lit une ligne dans un fluxstream_get_meta_data – Lit les en-têtes et données méta des fluxstream_get_transports – Liste les gestionnaires de transports de sockets disponiblesstream_get_wrappers – Liste les gestionnaires de fluxstream_register_wrapper – Alias de stream_wrapper_register()
stream_resolve_include_path –  Détermine quel fichier sera ouvert lors des appels à la fonction fopen() avec un chemin relatif stream_select – Retourne l’équivalent de l’appel système select() sur un tableau de flux avec un délai d’expiration spécifié par tv_sec et tv_usecstream_set_blocking – Configure le mode bloquant d’un fluxstream_set_timeout – Configure la durée d’expiration d’un fluxstream_set_write_buffer – Configure la bufferisation de fichier pour un fluxstream_socket_accept –  Accepte une connexion sur une socket créée par stream_socket_server()
stream_socket_client –  Ouvre une connexion socket Internet ou Unix stream_socket_enable_crypto –  Active ou non le cryptage sur une socket déjà connectée stream_socket_get_name – Lit le nom des sockets locale ou distantestream_socket_pair –  Crée une paire de sockets connectées et indissociables stream_socket_recvfrom – Lit des données depuis une socket, connectée ou passtream_socket_sendto – Envoie une message à la socket, connectée ou passtream_socket_server –  Crée une socket serveur Unix ou Internet stream_socket_shutdown – Arrête une connexion full-duplexstream_wrapper_register –  Enregistre une enveloppe URL, implémentée comme une classe PHP stream_wrapper_restore – Restaure un gestionnaire d’URL suppriméstream_wrapper_unregister – Supprime un gestionnaire d’URL