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 d'être renommé.

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.

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);

?>