Manuel PHP
PrécédentSuivant

stream_wrapper_register

(PHP 4 >= 4.3.2)

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.

OptionDescription
STREAM_USE_PATHSi path est relatif, recherche la ressources en utilisant la configuration de l'include_path.
STREAM_REPORT_ERRORSSi 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édentSommaireSuivant
stream_socket_serverNiveau supérieurChaînes de caractères (Strings)