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 HTTP/1.0 sur un serveur distant. Il existe de nombreux gestionnaires intégrés à PHP par défaut (voir Liste des protocoles supportés), 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 Eléments Absents. 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 Liste des protocoles supportés 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 Liste des protocoles supportés pour une description des cibles des flux intégrés.
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 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 Eléments Absents. Pour connaître la liste des gestionnaires actuellement enregistrés, utilisez la fonction stream_get_filters().
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é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 Liste des protocoles supportés).
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 :
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.
Installation
Les flux font partie 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. 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.
Constantes pré-définies
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 |
| PSFS_PASS_ON * | Le code retourné indique que le filtre utilisateur retourne des données dans $out . |
| PSFS_FEED_ME * | Le code retourné indique que le filtre utilisateur ne retourne pas de données dans $out (i.e. Aucune donnée disponible). |
| PSFS_ERR_FATAL * | Le code retourné indique que le filtre utilisateur a produit une erreur fatale. (i.e. Données invalides reçues). |
| 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. |
| STREAM_CLIENT_ASYNC_CONNECT * | Ouvre un socket client en mode asynchrone. Cette option doit être utilisée avec le flag STREAM_CLIENT_CONNECT. À utiliser avec la fonction stream_socket_client(). |
| STREAM_CLIENT_CONNECT * | Ouvre un socket client. Les sockets clients doivent toujours inclure ce flag. À utiliser avec la fonction stream_socket_client(). |
| STREAM_CLIENT_PERSISTENT * | Le socket client ouvert avec stream_socket_client() doit rester persistant entre chaque page chargée. |
| STREAM_SERVER_BIND * | Appel un flux créé avec la fonction stream_socket_server() pour s'identifier sur la cible définie. Les sockets serveur doivent toujours utiliser cette constante. |
| STREAM_SERVER_LISTEN * | Appel un flux créé avec stream_socket_server() et utilise la constante STREAM_SERVER_BIND pour commencer à écouter la socket. Les connexions orientées transports (comme TCP) doivent utiliser ce flag sinon la socket serveur ne sera pas activé. Utiliser ce flag pour les connexions basses de transports (comme UDP) est une erreur. |
| STREAM_NOTIFY_RESOLVE * | Une adresse distante requise pour ce flux a été résolue, ou bien la résolution a échoué. Voir le paramètre severity pour avoir une indication sur l'événement survenu. |
| STREAM_NOTIFY_CONNECT | Une connexion avec une ressource externe a été établie. |
| STREAM_NOTIFY_AUTH_REQUIRED | Une autorisation supplémentaire est demandée pour accéder à la ressource spécifiée. Typiquement utilisé avec le niveau d'alerte severity de la constante STREAM_NOTIFY_SEVERITY_ERR. |
| STREAM_NOTIFY_MIME_TYPE_IS | Le type mime de la ressource a été identifié : voir le paramètre message pour une description du type découvert. |
| STREAM_NOTIFY_FILE_SIZE_IS | La taille de la ressource a été découverte. |
| STREAM_NOTIFY_REDIRECTED | La ressource externe a redirigé le flux vers un endroit différent. Voir le paramètre message . |
| STREAM_NOTIFY_PROGRESS | Indique l'actuelle progression du transfert du flux dans bytes_transferred et peut-être bytes_max également. |
| STREAM_NOTIFY_COMPLETED * | Il n'y a plus de données disponibles sur le flux. |
| STREAM_NOTIFY_FAILURE | Une erreur générique est intervenue sur le flux, consultez les paramètres message et message_code pour plus de détails. |
| STREAM_NOTIFY_AUTH_RESULT | L'autorisation est terminée (avec succès ou pas). |
| STREAM_NOTIFY_SEVERITY_INFO | Notification normale, aucune erreur signalée. |
| STREAM_NOTIFY_SEVERITY_WARN | Erreur non critique. Le traitement continue. |
| STREAM_NOTIFY_SEVERITY_ERR | Une erreur critique est survenu. Le traitement ne peut continuer. |
| STREAM_IPPROTO_ICMP + | Fournit un socket ICMP. |
| STREAM_IPPROTO_IP + | Fournit un socket IP. |
| STREAM_IPPROTO_RAW + | Fournit un socket RAW. |
| STREAM_IPPROTO_TCP + | Fournit un socket TCP. |
| STREAM_IPPROTO_UDP + | Fournit un socket UDP. |
| STREAM_PF_INET + | Protocole Internet version 4 (IPv4). |
| STREAM_PF_INET6 + | Protocole internet version 6(IPv6). |
| STREAM_PF_UNIX + | Protocoles internes des systèmes Unix. |
| STREAM_SOCK_DGRAM + | Fournit des datagrammes, qui sont des messages de connexion (UDP, par exemple). |
| STREAM_SOCK_RAW + | Fournit un socket raw, qui fournit un accès aux protocoles et interfaces internes du réseau. Habituellement, ce type de socket n'est disponible qu'à l'utilisateur root. |
| STREAM_SOCK_RDM + | Fournit un socket RDM (Reliably-delivered messages). |
| STREAM_SOCK_SEQPACKET + | Fournit un socket de flux de paquets séquencés. |
| STREAM_SOCK_STREAM + | Fournit un flux séquencé, deux chemins avec un mécanisme de transmission pour les données "out-of-band" (TCP par exemple). |
| STREAM_SHUT_RD | Utilisé avec stream_socket_shutdown() pour désactiver les réceptions futures. Ajouté en PHP 5.2.1. |
| STREAM_SHUT_WR | Utilisé avec stream_socket_shutdown() pour désactiver les transmissions futures. Ajouté en PHP 5.2.1. |
| STREAM_SHUT_RDWR | Utilisé avec stream_socket_shutdown() pour désactiver les réceptions et transmissions futures. Ajouté en PHP 5.2.1. |
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.
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 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.
Exemples
Example#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 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("https://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:[email protected]/foo.txt");
/* Lit un fichier distant sur le serveur ftp.example.com en utilisant le protocole FTPS */
$ftpsfile = file_get_contents("ftps://user:[email protected]/foo.txt");
?>
Example#2 Envoi d'une requête de type POST sur un 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";
}
echo "\n";
$body = "";
while (!feof($sock)) {
$body .= fgets($sock, 4096);
}
fclose($sock);
?>
Example#3 Ecrire des données dans un fichier compressé
<?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 of Contents
- 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 flux
- stream_context_get_default — Lit le contexte par défaut des flux
- stream_context_get_options — Lit la valeur des options pour un flux/gestionnaire/contexte
- stream_context_set_option — Configure une option pour un flux/gestionnaire/contexte
- stream_context_set_params — Configure les paramètres pour un flux/gestionnaire/contexte
- stream_copy_to_stream — Copie des données depuis un flux vers un autre
- stream_encoding — Définit le jeu de caractères pour l'encodage du flux
- stream_filter_append — Attache un filtre à un flux en fin de liste
- stream_filter_prepend — Attache un filtre à un flux en début de liste
- stream_filter_register — Enregistre un filtre de flux
- stream_filter_remove — Supprime un filtre d'un flux
- stream_get_contents — Lit le reste d'un flux dans une chaîne
- stream_get_filters — Liste les filtres enregistrés
- stream_get_line — Lit une ligne dans un flux
- stream_get_meta_data — Lit les en-têtes et données méta des flux
- stream_get_transports — Liste les gestionnaires de transports de sockets disponibles
- stream_get_wrappers — Liste les gestionnaires de flux
- stream_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_usec
- stream_set_blocking — Configure le mode bloquant d'un flux
- stream_set_timeout — Configure la durée d'expiration d'un flux
- stream_set_write_buffer — Configure la bufferisation de fichier pour un flux
- stream_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 distante
- stream_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 pas
- stream_socket_sendto — Envoie une message à la socket, connectée ou pas
- stream_socket_server — Crée une socket serveur Unix ou Internet
- stream_socket_shutdown — Arrête une connexion full-duplex
- stream_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