(PHP 4 >= 4.3.2, PHP 5)
stream_wrapper_register -- Enregistre une enveloppe URL, implémentée comme une classe PHPstream_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.
Note : Depuis PHP 5.0.0, l'instance de la classe
classname
contiendra une propriétécontext
, faisant référence à la ressource de contexte qui peut être accédée avec la fonction stream_context_get_options(). Si aucun contexte n'est passé à la fonction de création du flux,context
sera défini à NULL.
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
void stream_close ( void )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.
string stream_read ( int count )
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.
int stream_tell ( void )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.
bool stream_seek ( int offset, int whence )
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.
array stream_stat ( void )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.
bool unlink ( string path )
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.
Note : La méthode enveloppe d'utilisateur unlink n'est pas supportée avant PHP 5.0.0.
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.
Note : La méthode enveloppe d'utilisateur rename n'est pas supportée avant PHP 5.0.0.
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.
Note : La méthode enveloppe d'utilisateur mkdir n'est pas supportée avant PHP 5.0.0.
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.
Note : La méthode enveloppe d'utilisateur rmdir n'est pas supportée avant PHP 5.0.0.
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().
bool dir_rewinddir ( void )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().
bool dir_closedir ( void )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"]
.
Précédent | Sommaire | Suivant |
stream_socket_shutdown | Niveau supérieur | stream_wrapper_restore |