stream_register_filter() vous permet d'implémenter votre propre filtre de flôt, à utiliser avec les fonctions d'accès aux données externes (comme fopen(), fread(), etc...).
Pour ce faire, vous devez définir une classe qui étend la classe php_user_fitler avec les membres et méthodes définies ci-dessous. Lorsque vous réalisez des opérations de lecture et d'écriture dans le flôt auquel votre filtre est attaché, PHP passera les données à travers votre filtre (et tous les autres filtres attachés), de façon à ce que les données soient modifiées telles que désiré. Vous devez implémenter les méthodes telles que décrit ci-dessous, sous peine de comportement indéfini.
stream_register_filter() retourne FALSE si le nom de filtre filtername est déjà utilisé.
int write ( string data)Cette méthode est appelée dès que les données sont écrite dans le flôt, comme avec la fonction fwrite(). Après la modification des données data, cette méthode doit utiliser la ligne suivante return parent::write($data); pour que le prochain filtre puisse s'exécuter. Lorsqu'il ne reste plus de filtres, le flôt va écrire les données data dans leur forme finale.
Note : Si votre filtre modifie la taille de la chaîne data, par exemple en supprimant le premier caractère, il faut, avant d'utiliser la fonction parent::write($data);, s'assurer d'inclure le caractère supprimé dans la valeur de retour.
class myfilter extends php_user_filter { function write($data) { $data = substr($data,1); $written_by_parent = parent::write($data); return ($written_by_parent + 1); } } |
Cette méthode est appelée dès que des données sont lues dans le flôt (comme avec la fonction fread()). Un filtre doit commencer par utiliser la ligne parent::read($maxlength); pour lire les données issue du filtre précédent. Ultimement, ce sera le flôt qui lira les données. Votre filtre peut alors modifier cette valeur et retourner la valeur finale. Votre filtre ne doit jamais retourner plus de maxlength octets. Comme parent::read($maxlength); ne retournera aussi pas plus de maxlength, ce ne sera pas un problème en règle général. Cependant, si votre filtre accroit la taille des données retournées, il faut alors appeler cette ligne avec parent::read($maxlength-$x); où x est l'accroissement maximal de vos données. Alternativement, vous pouvez bâtir un buffer de lecture dans votre classe.
int flush ( bool closing)Cette méthode est appelée en réponse à une requête de vidage des buffers du flôt (comme avec la fonction fflush() ou fclose()). Le paramètre closing vous indique si le flôt est, en réalité, dans un processus de fermeture. L'action par défaut est d'appeler simplement return parent::flush($closing);, mais votre filtre peut souhaiter exécuter des écritures supplémentaires, ou bien nettoyer des ressources avant de réaliser le vidage en règle.
void oncreate ( void)Cette méthode est appelée durant l'instantiation du filtre. Si votre filtre alloue ou initialise d'autres ressources (comme des buffers), c'est le moment de le faire.
void onclose ( void)Cette méthode est appelée durant l'extinction du filtre (généralement, lorsque le flôt est fermé), et est exécuté après l'appel de la fonction flush. Si aucune ressource a été allouée ou créée durant oncreate(), c'est le moment de les libérer.
L'exemple ci-dessous implémente un filtre appelé rot13, sur le flôt foo-bar.txt, qui réalise un chiffrement de type ROT-13 sur toutes les lettres lue ou écrite dans le flôt.
Voir aussi stream_register_wrapper(), stream_filter_prepend() et stream_filter_append()
Précédent | Sommaire | Suivant |
stream_get_wrappers | Niveau supérieur | stream_register_wrapper |