Manuel PHP
Précédent |  | Suivant

# stream_wrapper_register

(PHP 4 >= 4.3.2, PHP 5)

stream_wrapper_register -- Enregistre une enveloppe URL, implémentée comme classe PHP

## Description

bool stream_wrapper_register ( string protocol, string classname)

stream_wrapper_register() vous permet d'implémenter vos propres gestionnaires de protocoles et de flux, à utiliser avec toutes les autres fonctions de fichiers, comme fopen(), fread() etc...

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

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

bool stream_open ( string path, string mode, int options, string opened_path)

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 par des 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, vous êtes responsable pour lever les erreurs avec trigger_error() durant l'ouverture du flux. Si cette option n'est pas activée, vous ne devez lever aucune erreur.

Si le paramètre `path` est ouvert avec succès, et que STREAM_USE_PATH est activé dans le paramètre `options`, vous devez affecter à `opened_path` le chemin complet de la ressource ou du fichier que vous avez réellement ouvert.

Si la ressource demandée a été ouverte, vous devez retourner `TRUE`, ou sinon, vous devez retourner `FALSE`

void stream_close ( void )

Cette méthode est appelée lors que flux est fermée, grâce à la fonction fclose(). Vous devez libérez toutes les ressources réservées par le flux.

string stream_read ( int count)

Cette méthod 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. Si il y a moins que `count` octets disponibles, vous devez en retourner autant que possible. Si aucune autre donnée n'est disponible, retournez soit `FALSE` soit 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.

int stream_write ( string data)

Cette méthode est appelée lorsque la fonction fwrite() est utilisée. Vous devez stocker les données `data` dans le flux. Si 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 lus.

bool stream_eof ( void )

Cette méthode est appelée lorsque la fonction feof() est utilisée. Vous devez retourner `TRUE` si la position de lecture se situe a la fin du fichier et si il n'y a plus de donnée disponible 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.

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.

bool stream_flush ( void )

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'ils ne sont pas encore stockés 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ée à 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 retourne `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 : Userspace wrapper unlink method is not supported prior to `PHP 5.0.0`.

bool dir_opendir ( string path, int options)

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.

string dir_readdir ( void )

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 st 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éthde est appelé 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"].

Exemple 1. 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);
?>`

Précédent | Sommaire | Suivant
stream_socket_server | Niveau supérieur | Chaînes de caractères (Strings)