8.126.42 stream_wrapper_register() Enregistre une enveloppe URL, implémentée comme une classe PHP

stream_wrapper_register permet d'implémenter des gestionnaires de protocole et de flux, à utiliser avec toutes les autres fonctions de fichiers, comme fopen , fread etc.

Pour implémenter une enveloppe, il faut définir une classe avec la liste des membres définie ci-dessous. Lorsque quelqu'un ouvre le flux, PHP va créer une instance de la classe classname et appeler les méthodes de cette instance. Il faut implémenter ces méthodes exactement comme décrit ci-dessous : sinon, les comportements seront indéfinis.

stream_wrapper_register retourne FALSE si le protocole protocol a déjà un gestionnaire attitré.

Cette méthode est appelée immédiatement après la création de votre flux. path spécifie l'URL qui doit être passée à la fonction fopen et ce que cet objet est supposé y lire. Vous pouvez utiliser parse_url pour l'analyser.

mode est le mode d'ouverture du fichier, comme expliqué dans fopen . Vous êtes responsable de la vérification de la validité du paramètre mode avec le chemin path fourni.

options contient des options supplémentaires, utilisées par les API de flux. Il peut contenir une ou plusieurs des options suivantes, combinées avec l'opérateur OR.

Option	Description
STREAM_USE_PATH	Si path est relatif, recherche la ressources en utilisant la configuration de l' include_path .
STREAM_REPORT_ERRORS	Si cette option est activée, la classe est responsable de la génération d'erreurs avec trigger_error durant l'ouverture du flux. Si cette option n'est pas activée, il ne faut générer aucune erreur.

Si le paramètre path est ouvert avec succès, et que STREAM_USE_PATH est activé dans le paramètre options , il faut affecter à opened_path le chemin complet de la ressource ou du fichier qui a été réellement ouvert.

Si la ressource demandée a été ouverte, il faut retourner TRUE , ou, sinon, FALSE

Cette méthode est appelée lorsque le flux est fermé, grâce à la fonction fclose . Vous devez libérer toutes les ressources verrouillées ou réservées par le flux.

Cette méthode est appelée suite à l'utilisation des fonctions fread et fgets . Vous devez lire jusqu'à count octets de données à partir de la position courante d'écriture ou de lecture, sous la forme de chaîne de caractères. S'il y a moins que count octets disponibles, vous devez en retourner autant que possible. Si aucune autre donnée n'est disponible, FALSE sera retourné ou une chaîne vide. Vous devez aussi tenir à jour la position du pointeur d'écriture/lecture dans le flux, en ajoutant ou retranchant le nombre d'octets lus.

Cette méthode est appelée lorsque la fonction fwrite est utilisée. Vous devez stocker les données data dans le flux. S'il n'y a pas assez de place, essayez d'en stocker le maximum. Vous devriez aussi retourner le nombre d'octets que vous avez réussi à écrire, ou bien 0 si aucun n'a pu être stocké. Vous devez aussi tenir à jour la position du pointeur d'écriture/lecture dans le flux, en ajoutant ou retranchant le nombre d'octets écrits.

Cette méthode est appelée lorsque la fonction feof est utilisée. Vous devez retourner TRUE si la position de lecture se situe à la fin du fichier et s'il n'y a plus de données disponibles pour la lecture, ou bien FALSE sinon.

Cette méthode est appelée lorsque la fonction ftell est utilisée. Vous devez retourner la position actuelle du pointeur de lecture/écriture dans le flux.

Cette méthode est appelée lorsque la fonction fseek est utilisée. Vous devez modifier la position du pointeur de lecture/écriture en fonction des paramètres d'offset offset et de direction whence . Reportez-vous à la fonction fseek pour plus de détails sur ces paramètres. Retournez TRUE si la position a été modifiée, et FALSE sinon.

Cette méthode est appelée lorsque la fonction fflush est utilisée. Si vous avez mis des données dans un système de cache pour votre flux, mais qu'elles ne sont pas encore stockées de manière pérenne, c'est le moment de le faire. Retournez TRUE si les données cachées ont pu être stockées avec succès (il n'y a plus de données à stocker), ou bien FALSE si les données n'ont pu être stockées.

Cette méthode est appelée en réponse à la fonction fstat sur un flux, et retourne un tableau, avec les valeurs appropriées pour le flux.

Cette méthode est appelée en réponse à la fonction unlink avec une URL, et doit tenter de supprimer l'objet identifié par path . La fonction doit retourner TRUE en cas de succès, et FALSE en cas d'échec. Afin de retourner le bon message d'erreur, ne définissez pas cette méthode si votre gestionnaire ne le supporte pas.

Cette méthode est appelée en réponse à la fonction rename avec une URL associée avec l'enveloppe et doit tenter de renommer l'objet identifié par path_from en path_to . Cela doit retourner TRUE en cas de succès ou FALSE en cas d'erreur. Afin de pouvoir retourner le message d'erreur approprié, ne définissez pas cette méthode si votre enveloppe ne supporte pas le renommage.

Cette méthode est appelée en réponse à la fonction mkdir avec une URL associée avec l'enveloppe et doit tenter de créer le répertoire spécifié par path . Cela doit retourner TRUE en cas de succès ou FALSE en cas d'erreur. Afin de pouvoir retourner le message d'erreur approprié, ne définissez pas cette méthode si votre enveloppe ne supporte pas la création de répertoire. Les valeurs possibles pour le paramètre options sont STREAM_REPORT_ERRORS et STREAM_MKDIR_RECURSIVE .

Cette méthode est appelée en réponse à la fonction rmdir avec une URL associée avec l'enveloppe et doit tenter de supprimer le répertoire spécifié par path . Cela doit retourner TRUE en cas de succès ou FALSE en cas d'erreur. Afin de pouvoir retourner le message d'erreur approprié, ne définissez pas cette méthode si votre enveloppe ne supporte pas la suppression de répertoire. La valeur possible pour le paramètre options est STREAM_REPORT_ERRORS .

Cette méthode est appelée immédiatement lorsque votre flux est créé, pour examiner le contenu d'un dossier avec opendir . path spécifie l'URL qui est passée à opendir et que cet objet doit explorer. Vous pouvez utiliser parse_url pour la scinder en morceaux.

Cette méthode est appelée en réponse à la fonction stat avec une URL associée avec l'enveloppe et doit retourner autant d'éléments en commun avec la fonction système que possible. Les valeurs non connues ou non disponibles doivent être définies en une valeur rationnelle (habituellement, 0 ).

flags représente les options additionnelles définies par l'API. Il peut prendre une ou plusieurs des valeurs suivantes séparées par OR.

Option	Description
STREAM_URL_STAT_LINK	Pour les ressources avec la possibilité de relier d'autres ressources (comme par exemple HTTP Location: forward ou un lien symbolique d'un système de fichiers). Cette option spécifie que seul les informations à propos du lien lui-même peuvent être retournées, et non pas les ressources pointées par le lien. Cette option est définie en réponse à l'appel à la fonction lstat , is_link , ou filetype .
STREAM_URL_STAT_QUIET	Si cette option est définie, votre enveloppe ne devra contenir aucune erreur. Si cette option n'est pas définie, vous êtes responsable du traitement des erreurs en utilisant la fonction trigger_error pendant l'évaluation du chemin.

Cette méthode est appelée en réponse à la fonction readdir et doit retourner une chaîne représentant le prochain fichier ouvert par dir_opendir .

Cette méthode est appelée en réponse à rewinddir et doit remettre à zéro les résultats de dir_readdir . i.e. : le prochain appel à dir_readdir doit retourner la première ligne située dans le dossier ouvert par dir_opendir .

Cette méthode est appelée en réponse à closedir . Vous devez libérer toutes les ressources qui ont été réservées durant l'ouverture et l'utilisation du dossier.

L'exemple ci-dessous implémente un gestionnaire de protocole pour le protocole var://, qui permet l'écriture et la lecture de variables globales en utilisant un flux de fichier standard, et les fonctions classiques telles que fread . Le protocole var:// implémenté ci-dessous, étant donné l'URL var://foo va écrire ou lire les données dans $GLOBALS["foo"] .

Une classe de flux pour accéder aux variables globales

<?php class VariableStream {     var $position;     var $varname;         function stream_open($path, $mode, $options, &$opened_path)     {         $url = parse_url($path);         $this->varname = $url["host"];         $this->position = 0;                  return true;     }     function stream_read($count)     {         $ret = substr($GLOBALS[$this->varname], $this->position, $count);         $this->position += strlen($ret);         return $ret;     }     function stream_write($data)     {         $left = substr($GLOBALS[$this->varname], 0, $this->position);         $right = substr($GLOBALS[$this->varname], $this->position + strlen($data));         $GLOBALS[$this->varname] = $left . $data . $right;         $this->position += strlen($data);         return strlen($data);     }     function stream_tell()     {         return $this->position;     }     function stream_eof()     {         return $this->position >= strlen($GLOBALS[$this->varname]);     }     function stream_seek($offset, $whence)     {         switch($whence) {             case SEEK_SET:                 if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) {                      $this->position = $offset;                      return true;                 } else {                      return false;                 }                 break;                              case SEEK_CUR:                 if ($offset >= 0) {                      $this->position += $offset;                      return true;                 } else {                      return false;                 }                 break;                              case SEEK_END:                 if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {                      $this->position = strlen($GLOBALS[$this->varname]) + $offset;                      return true;                 } else {                      return false;                 }                 break;                              default:                 return false;         }     } } stream_wrapper_register("var", "VariableStream")     or die("Failed to register protocol"); $myvar = "";      $fp = fopen("var://myvar", "r+"); fwrite($fp, "line1\n"); fwrite($fp, "line2\n"); fwrite($fp, "line3\n"); rewind($fp); while(!feof($fp)) {     echo fgets($fp); } fclose($fp); var_dump($myvar); ?>