Flux

&reftitle.intro; 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 ), 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 . 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. Une flux est référencé comme : scheme://target scheme(&string;) - Le nom du gestionnaire a utilisé. Par exemple, file, http, https, ftp, ftps, compress.zlib, compress.bz. et php.. Voir 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 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 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 . 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é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 ). 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 réception de l'événement, et doit accepter 6 paramètres : voidmy_notifier intnotification_code intseverity stringmessage intmessage_code intbytes_transferred intbytes_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.

&reftitle.install; Les flux font parti 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émentation de filtres utilisateurs.

&reference.stream.constants;

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.

&reftitle.examples; ]]> ]]> ]]>

&reference.stream.functions;