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 une classe PHP

## Description

bool stream_wrapper_register ( string protocol, string classname )

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.

> 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é.

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 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.

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. 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.

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 à 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.

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'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.

bool rename ( string path_from, string path_to )

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.

bool mkdir ( string path, int mode, int options )

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.

bool rmdir ( string path, int options )

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.

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.

array url_stat ( string path, int flags )

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.

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 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"]`.

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_shutdown | Niveau supérieur | stream_wrapper_restore