(PHP 5 CVS only)
stream_register_filter() 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_fitler with a
number of member functions as defined below. When performing
read/write opperations 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_register_filter() will
return FALSE if the filtername is already
defined.
This method is called whenever data is written to the
attached stream (such as with
fwrite()). After modifying data as needed your filter
should issue: return
parent::write($data); so that the next filter in the
chain can perform its filter. When no filters remain, the
stream will write data in
its final form.
注: If your filter alters the length of data, for example by removing the first character, before passing onto parent::write($data); it must be certain to include that stolen character in the return count.
class myfilter extends php_user_filter { function write($data) { $data = substr($data,1); $written_by_parent = parent::write($data); return ($written_by_parent + 1); } } |
This method is called whenever data is read from the
attached stream (such as with
fread()). A filter should first
call parent::read($maxlength); to
retrieve the data from the previous filter who, ultimately,
retrieved it from the stream. Your filter may then modify the
data as needed and return it. Your
filter should never return more than
maxlength bytes. Since
parent::read($maxlength); will also not return more than
maxlength bytes this will
ordinarily be a non-issue. However, if your filter increases
the size of the data being returned, you should either call
parent::read($maxlength-$x); where
x is the most your filter
will grow the size of the data read. Alternatively, you can
build a read-buffer into your class.
This method is called in response to a request to flush
the attached stream (such as with fflush()
or
fclose()). The
closing parameter tells you whether the stream is,
in fact, in the process of closing. The default action is to
simply call: return
parent::flush($closing); , your filter may wish to
perform additional writes and/or cleanup calls prior to or
directly after a successful flush.
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.
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 rot13 on the
foo-bar.txt stream which will perform ROT-13 encryption
on all letter characters written to/read from that
stream.
See Also:
stream_register_wrapper(),
stream_filter_prepend(), and
stream_filter_append()