mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Separate documentation of php_user_filter
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@324430 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jakub Vrana
parent
f7272deef5
commit
48e5dd1b7e
7 changed files with 406 additions and 125 deletions
|
|
@ -70,6 +70,7 @@
|
|||
&reference.stream.contexts;
|
||||
&reference.stream.errors;
|
||||
&reference.stream.examples;
|
||||
&reference.stream.php-user-filter;
|
||||
&reference.stream.streamwrapper;
|
||||
&reference.stream.reference;
|
||||
|
||||
|
|
|
|||
|
|
@ -37,133 +37,13 @@
|
|||
<listitem>
|
||||
<para>
|
||||
To implement a filter, you need to define a class as an extension of
|
||||
<literal>php_user_filter</literal> with a number of member functions
|
||||
as defined below. When performing read/write operations on the stream
|
||||
<classname>php_user_filter</classname> with a number of member
|
||||
functions. 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.
|
||||
</para>
|
||||
<methodsynopsis>
|
||||
<type>int</type><methodname>filter</methodname>
|
||||
<methodparam><type>resource</type><parameter>in</parameter></methodparam>
|
||||
<methodparam><type>resource</type><parameter>out</parameter></methodparam>
|
||||
<methodparam><type>int</type><parameter role="reference">consumed</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>closing</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
This method is called whenever data is read from or written to
|
||||
the attached stream (such as with <function>fread</function> or <function>fwrite</function>).
|
||||
<parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal>
|
||||
which contains one or more <literal>bucket</literal> objects containing data to be filtered.
|
||||
<parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal>
|
||||
into which your modified buckets should be placed.
|
||||
<parameter>consumed</parameter>, which must <emphasis>always</emphasis>
|
||||
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 <parameter>consumed</parameter> by <literal>$bucket->datalen</literal>
|
||||
for each <literal>$bucket</literal>. If the stream is in the process of closing
|
||||
(and therefore this is the last pass through the filterchain),
|
||||
the <parameter>closing</parameter> parameter will be set to &true;.
|
||||
The <methodname>filter</methodname> method must return one of
|
||||
three values upon completion.
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Return Value</entry>
|
||||
<entry>Meaning</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>PSFS_PASS_ON</constant></entry>
|
||||
<entry>
|
||||
Filter processed successfully with data available in the
|
||||
<parameter>out</parameter> <literal>bucket brigade</literal>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>PSFS_FEED_ME</constant></entry>
|
||||
<entry>
|
||||
Filter processed successfully, however no data was available to
|
||||
return. More data is required from the stream or prior filter.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>PSFS_ERR_FATAL</constant> (default)</entry>
|
||||
<entry>
|
||||
The filter experienced an unrecoverable error and cannot continue.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
<methodsynopsis>
|
||||
<type>bool</type><methodname>onCreate</methodname>
|
||||
<void/>
|
||||
</methodsynopsis>
|
||||
<simpara>
|
||||
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.
|
||||
</simpara>
|
||||
<simpara>
|
||||
When your filter is first instantiated, and
|
||||
<literal>yourfilter->onCreate()</literal> is called, a number of properties
|
||||
will be available as shown in the table below.
|
||||
</simpara>
|
||||
<para>
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Property</entry>
|
||||
<entry>Contents</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>FilterClass->filtername</literal></entry>
|
||||
<entry>
|
||||
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.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>FilterClass->params</literal></entry>
|
||||
<entry>
|
||||
The contents of the <parameter>params</parameter> parameter passed
|
||||
to <function>stream_filter_append</function>
|
||||
or <function>stream_filter_prepend</function>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>FilterClass->stream</literal></entry>
|
||||
<entry>
|
||||
The stream resource being filtered. Maybe available only during
|
||||
<methodname>filter</methodname> calls when the
|
||||
<literal>closing</literal> parameter is set to &false;.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
<methodsynopsis>
|
||||
<type>void</type><methodname>onClose</methodname>
|
||||
<void/>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
This method is called upon filter shutdown (typically, this is also
|
||||
during stream shutdown), and is executed <emphasis>after</emphasis>
|
||||
the <literal>flush</literal> method is called. If any resources
|
||||
were allocated or initialized during <literal>onCreate()</literal>
|
||||
this would be the time to destroy or dispose of them.
|
||||
exactly as described in <classname>php_user_filter</classname> - doing
|
||||
otherwise will lead to undefined behaviour.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
|
|||
103
reference/stream/php-user-filter.xml
Normal file
103
reference/stream/php-user-filter.xml
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<phpdoc:classref xml:id="class.php-user-filter" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<title>The php_user_filter class</title>
|
||||
<titleabbrev>php_user_filter</titleabbrev>
|
||||
|
||||
<partintro>
|
||||
|
||||
<!-- {{{ php_user_filter intro -->
|
||||
<section xml:id="php-user-filter.intro">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
Children of this class are passed to
|
||||
<function>stream_filter_register</function>.
|
||||
</para>
|
||||
</section>
|
||||
<!-- }}} -->
|
||||
|
||||
<section xml:id="php-user-filter.synopsis">
|
||||
&reftitle.classsynopsis;
|
||||
|
||||
<!-- {{{ Synopsis -->
|
||||
<classsynopsis>
|
||||
<ooclass><classname>php_user_filter</classname></ooclass>
|
||||
|
||||
<!-- {{{ Class synopsis -->
|
||||
<classsynopsisinfo>
|
||||
<ooclass>
|
||||
<classname>php_user_filter</classname>
|
||||
</ooclass>
|
||||
</classsynopsisinfo>
|
||||
<!-- }}} -->
|
||||
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
|
||||
<fieldsynopsis>
|
||||
<modifier>public</modifier>
|
||||
<varname linkend="php-user-filter.props.filtername">filtername</varname>
|
||||
</fieldsynopsis>
|
||||
<fieldsynopsis>
|
||||
<modifier>public</modifier>
|
||||
<varname linkend="php-user-filter.props.params">params</varname>
|
||||
</fieldsynopsis>
|
||||
|
||||
|
||||
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
|
||||
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.php-user-filter')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
|
||||
</classsynopsis>
|
||||
<!-- }}} -->
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<!-- {{{ php_user_filter properties -->
|
||||
<section xml:id="php-user-filter.props">
|
||||
&reftitle.properties;
|
||||
<variablelist>
|
||||
<varlistentry xml:id="php-user-filter.props.filtername">
|
||||
<term><varname>filtername</varname></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Name of the filter registered by
|
||||
<function>stream_filter_append</function>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="php-user-filter.props.params">
|
||||
<term><varname>params</varname></term>
|
||||
<listitem>
|
||||
<para></para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</section>
|
||||
<!-- }}} -->
|
||||
|
||||
|
||||
</partintro>
|
||||
|
||||
&reference.stream.entities.php-user-filter;
|
||||
|
||||
</phpdoc:classref>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
134
reference/stream/php_user_filter/filter.xml
Normal file
134
reference/stream/php_user_filter/filter.xml
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="php-user-filter.filter" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>php_user_filter::filter</refname>
|
||||
<refpurpose>Called when applying the filter</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>public</modifier> <type>int</type><methodname>php_user_filter::filter</methodname>
|
||||
<methodparam><type>resource</type><parameter>in</parameter></methodparam>
|
||||
<methodparam><type>resource</type><parameter>out</parameter></methodparam>
|
||||
<methodparam><type>int</type><parameter role="reference">consumed</parameter></methodparam>
|
||||
<methodparam><type>bool</type><parameter>closing</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
This method is called whenever data is read from or written to
|
||||
the attached stream (such as with <function>fread</function> or <function>fwrite</function>).
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>in</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal>
|
||||
which contains one or more <literal>bucket</literal> objects containing data to be filtered.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>out</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal>
|
||||
into which your modified buckets should be placed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>consumed</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<parameter>consumed</parameter>, which must <emphasis>always</emphasis>
|
||||
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 <parameter>consumed</parameter> by <literal>$bucket->datalen</literal>
|
||||
for each <literal>$bucket</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>closing</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If the stream is in the process of closing
|
||||
(and therefore this is the last pass through the filterchain),
|
||||
the <parameter>closing</parameter> parameter will be set to &true;.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
The <methodname>filter</methodname> method must return one of
|
||||
three values upon completion.
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Return Value</entry>
|
||||
<entry>Meaning</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><constant>PSFS_PASS_ON</constant></entry>
|
||||
<entry>
|
||||
Filter processed successfully with data available in the
|
||||
<parameter>out</parameter> <literal>bucket brigade</literal>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>PSFS_FEED_ME</constant></entry>
|
||||
<entry>
|
||||
Filter processed successfully, however no data was available to
|
||||
return. More data is required from the stream or prior filter.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><constant>PSFS_ERR_FATAL</constant> (default)</entry>
|
||||
<entry>
|
||||
The filter experienced an unrecoverable error and cannot continue.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
60
reference/stream/php_user_filter/onclose.xml
Normal file
60
reference/stream/php_user_filter/onclose.xml
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="php-user-filter.onclose" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>php_user_filter::onClose</refname>
|
||||
<refpurpose>Called when closing the filter</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>public</modifier> <type>void</type><methodname>php_user_filter::onClose</methodname>
|
||||
<void />
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
This method is called upon filter shutdown (typically, this is also
|
||||
during stream shutdown), and is executed <emphasis>after</emphasis>
|
||||
the <literal>flush</literal> method is called. If any resources
|
||||
were allocated or initialized during <literal>onCreate()</literal>
|
||||
this would be the time to destroy or dispose of them.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
&no.function.parameters;
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
Return value is ignored.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
103
reference/stream/php_user_filter/oncreate.xml
Normal file
103
reference/stream/php_user_filter/oncreate.xml
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="php-user-filter.oncreate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>php_user_filter::onCreate</refname>
|
||||
<refpurpose>Called when creating the filter</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>public</modifier> <type>bool</type><methodname>php_user_filter::onCreate</methodname>
|
||||
<void />
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When your filter is first instantiated, and
|
||||
<literal>yourfilter->onCreate()</literal> is called, a number of properties
|
||||
will be available as shown in the table below.
|
||||
</para>
|
||||
<para>
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Property</entry>
|
||||
<entry>Contents</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><literal>FilterClass->filtername</literal></entry>
|
||||
<entry>
|
||||
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.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>FilterClass->params</literal></entry>
|
||||
<entry>
|
||||
The contents of the <parameter>params</parameter> parameter passed
|
||||
to <function>stream_filter_append</function>
|
||||
or <function>stream_filter_prepend</function>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><literal>FilterClass->stream</literal></entry>
|
||||
<entry>
|
||||
The stream resource being filtered. Maybe available only during
|
||||
<methodname>filter</methodname> calls when the
|
||||
<literal>closing</literal> parameter is set to &false;.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
&no.function.parameters;
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
Your implementation of
|
||||
this method should return &false; on failure, or &true; on success.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
indent-tabs-mode:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
|
|
@ -28,7 +28,7 @@
|
|||
using the class definition shown on that manual page.
|
||||
</simpara>
|
||||
<simpara>
|
||||
<literal>class</literal> php_user_filter is predefined and is an abstract
|
||||
Class <classname>php_user_filter</classname> is predefined and is an abstract
|
||||
baseclass for use with user defined filters. See the manual page for
|
||||
<function>stream_filter_register</function> for details on implementing
|
||||
user defined filters.
|
||||
|
|
|
|||
Loading…
Reference in a new issue