   #PHP Manual Stream functions stream_filter_prepend stream_get_contents

   PHP Manual
   Prev  Next
   ______________________________________________________________________

                            stream_filter_register

   (PHP 5 CVS only)
   stream_filter_register --  Register a stream filter implemented as a
   PHP class derived from php_user_filter

Description

   bool stream_filter_register ( string filtername, string classname)

   stream_filter_register() allows you to implement your own filter on
   any registered stream used with all the other filesystem functions
   (such as fopen(), fread() etc.).

   To implement a filter, you need to define a class as an extension of
   php_user_filter with a number of member functions as defined below.
   When performing read/write operations on the stream to which your
   filter is attached, PHP will pass the data through your filter (and
   any other filters attached to that stream) so that the data may be
   modified as desired. You must implement the methods exactly as
   described below - doing otherwise will lead to undefined behaviour.

   stream_filter_register() will return FALSE if the filtername is
   already defined.
   int filter ( resource in, resource out, int &consumed, bool closing)

   This method is called whenever data is read from or written to the
   attached stream (such as with fread() or fwrite()). in is a resource
   pointing to a bucket brigade which contains one or more bucket objects
   containing data to be filtered. out is a resource pointing to a second
   bucket brigade into which your modified buckets should be placed.
   consumed, which must always be declared by reference, should be
   incremented by the length of the data which your filter reads in and
   alters. In most cases this means you will increment consumed by
   $bucket->datalen for each $bucket. If the stream is in the process of
   closing (and therefore this is the last pass through the filterchain),
   the closing parameter will be set to TRUE The filter method must
   return one of three values upon completion.

   Return Value Meaning
   PSFS_PASS_ON Filter processed successfully with data available in the
   out bucket brigade.
   PSFS_FEED_ME Filter processed successfully, however no data was
   available to return. More data is required from the stream or prior
   filter.
   PSFS_ERR_FATAL (default) The filter experienced an unrecoverable error
   and cannot continue.

   void oncreate ( void )

   This method is called during instantiation of the filter class object.
   If your filter allocates or initializes any other resources (such as a
   buffer), this is the place to do it. Your implementation of this
   method should return FALSE on failure, or TRUE on success.

   When your filter is first instantiated, and yourfilter->oncreate() is
   called, a number of properties will be available as shown in the table
   below.

   Property Contents
   FilterClass->filtername A string containing the name the filter was
   instantiated with. Filters may be registered under multiple names or
   under wildcards. Use this property to determine which name was used.
   FilterClass->params The contents of the params parameter passed to
   stream_filter_append() or stream_filter_prepend().

   void onclose ( void )

   This method is called upon filter shutdown (typically, this is also
   during stream shutdown), and is executed after the flush method is
   called. If any resources were allocated or initialzed during oncreate
   this would be the time to destroy or dispose of them.

   The example below implements a filter named strtoupper on the
   foo-bar.txt stream which will capitalize all letter characters written
   to/read from that stream.

   Example 1. Filter for capitalizing characters on foo-bar.txt stream
   <?php
   /* Define our filter class */
   class strtoupper_filter extends php_user_filter {
     function filter($in, $out, &$consumed, $closing) {
       while ($bucket = stream_bucket_make_writeable($in)) {
         $bucket->data = strtoupper($bucket->data);
         $consumed += $bucket->datalen;
         stream_bucket_append($out, $bucket);
       }
       return PSFS_PASS_ON;
     }
   }
   /* Register our filter with PHP */
   stream_filter_register("strtoupper", "strtoupper_filter")
       or die("Failed to register filter");
   $fp = fopen("foo-bar.txt", "w");
   /* Attach the registered filter to the stream just opened */
   stream_filter_append($fp, "strtoupper");
   fwrite($fp, "Line1\n");
   fwrite($fp, "Word - 2\n");
   fwrite($fp, "Easy As 123\n");
   fclose($fp);
   /* Read the contents back out
   */
   readfile("foo-bar.txt");
   ?>

   Output
LINE1
WORD - 2
EASY AS 123

   Example 2. Registering a generic filter class to match multiple filter
   names.
   <?php
   /* Define our filter class */
   class string_filter extends php_user_filter {
     var $mode;
     function filter($in, $out, &$consumed, $closing) {
       while ($bucket = stream_bucket_make_writeable($in)) {
         if ($this->mode == 1) {
           $bucket->data = strtoupper($bucket->data);
         } elseif ($this->mode == 0) {
           $bucket->data = strtoupper($bucket->data);
         }
         $consumed += $bucket->datalen;
         stream_bucket_append($out, $bucket);
       }
       return PSFS_PASS_ON;
     }
     function oncreate() {
       if ($this->filtername == 'str.toupper') {
         $this->mode = 1;
       } elseif ($this->filtername == 'str.tolower') {
         $this->mode = 0;
       } else {
         /* Some other str.* filter was asked for,
            report failure so that PHP will keep looking */
         return false;
       }
       return true;
     }
   }
   /* Register our filter with PHP */
   stream_filter_register("str.*", "string_filter")
       or die("Failed to register filter");
   $fp = fopen("foo-bar.txt", "w");
   /* Attach the registered filter to the stream just opened
      We could alternately bind to str.tolower here */
   stream_filter_append($fp, "str.toupper");
   fwrite($fp, "Line1\n");
   fwrite($fp, "Word - 2\n");
   fwrite($fp, "Easy As 123\n");
   fclose($fp);
   /* Read the contents back out
   */
   readfile("foo-bar.txt");
   /* Output
   * ------
   LINE1
   WORD - 2
   EASY AS 123
   */
   ?>

   See Also: stream_wrapper_register(), stream_filter_prepend(), and
   stream_filter_append()
   ______________________________________________________________________

   Prev                  Home                Next
   stream_filter_prepend  Up  stream_get_contents
