pollita Wed Apr 14 01:37:43 2004 EDT
Modified files:
/phpdoc/en/appendices filters.xml
Log:
Refactor
http://cvs.php.net/diff.php/phpdoc/en/appendices/filters.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/appendices/filters.xml
diff -u phpdoc/en/appendices/filters.xml:1.2 phpdoc/en/appendices/filters.xml:1.3
--- phpdoc/en/appendices/filters.xml:1.2 Wed Apr 7 08:57:35 2004
+++ phpdoc/en/appendices/filters.xml Wed Apr 14 01:37:43 2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<appendix id="filters">
<title>List of Built-In Filters</title>
<para>
@@ -45,60 +45,97 @@
the corresponding function.
</simpara>
- <para>
- <table>
- <title>
- String Filters
- </title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>PHP Function equivalent</entry>
- <entry>Since Version</entry>
- <entry>Parameters</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>string.rot13</literal></entry>
- <entry>
- <function>str_rot13</function>
- </entry>
- <entry><literal>PHP 4.3.0</literal></entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><literal>string.toupper</literal></entry>
- <entry>
- <function>strtoupper</function>
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><literal>string.tolower</literal></entry>
- <entry>
- <function>strtolower</function>
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><literal>string.strip_tags</literal></entry>
- <entry>
- <function>strip_tags</function>
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>
- String containing allowable tags, similar to second parameter of
<function>strip_tags</function>.
- May also be an array containing list of tags (excluding <> symbols).
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
+ <simpara>
+ <literal>string.rot13</literal>
+ (since <literal>PHP 4.3.0</literal>)
+ Use of this filter is equivalent to processing all stream data through
+ the <function>str_rot13</function> function.
+ </simpara>
+ <example>
+ <title>string.rot13</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'string.rot13');
+fwrite($fp, "This is a test.\n");
+/* Outputs: Guvf vf n grfg. */
+?>
+]]>
+ </programlisting>
+ </example>
+
+ <simpara>
+ <literal>string.toupper</literal>
+ (since <literal>PHP 5.0.0</literal>)
+ Use of this filter is equivalent to processing all stream data through
+ the <function>strtoupper</function> function.
+ </simpara>
+ <example>
+ <title>string.toupper</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'string.toupper');
+fwrite($fp, "This is a test.\n");
+/* Outputs: THIS IS A TEST. */
+?>
+]]>
+ </programlisting>
+ </example>
+
+ <simpara>
+ <literal>string.tolower</literal>
+ (since <literal>PHP 5.0.0</literal>)
+ Use of this filter is equivalent to processing all stream data through
+ the <function>strtolower</function> function.
+ </simpara>
+ <example>
+ <title>string.tolower</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'string.tolower');
+fwrite($fp, "This is a test.\n");
+/* Outputs: this is a test. */
+?>
+]]>
+ </programlisting>
+ </example>
+
+ <simpara>
+ <literal>string.strip_tags</literal>
+ (since <literal>PHP 5.0.0</literal>)
+ Use of this filter is equivalent to processing all stream data through
+ the <function>strip_tags</function> function.
+ It accepts parameters in one of two forms:
+ Either as a string containing a list of tags similar to the
+ second parameter of the <function>strip_tags</function> function,
+ or as an array of tag names.
+ </simpara>
+ <example>
+ <title>string.strip_tags</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, "<b><i><u>");
+fwrite($fp, "<b>bolded text</b> enlarged to a <h1>level 1 heading</h1>\n");
+fclose($fp);
+/* Outputs: <b>bolded text</b> enlarged to a level 1 heading */
+
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE,
array('b','i','u'));
+fwrite($fp, "<b>bolded text</b> enlarged to a <h1>level 1 heading</h1>\n");
+fclose($fp);
+/* Outputs: <b>bolded text</b> enlarged to a level 1 heading */
+?>
+]]>
+ </programlisting>
+ </example>
+
</section>
<section id="filters.convert">
@@ -106,77 +143,84 @@
<simpara>
Like the string.* filters, the convert.* filters perform actions
- similar to their names.
+ similar to their names. The convert filters were added with
+ <literal>PHP 5.0.0</literal>.
For more information on a given filter, refer to the manual page for
the corresponding function.
</simpara>
- <para>
- <table>
- <title>
- Convert Filters
- </title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>PHP Function equivalent</entry>
- <entry>Since Version</entry>
- <entry>Parameters</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>convert.base64-encode</literal></entry>
- <entry>
- <function>base64_encode</function>
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>
- If parameters are provided as an associative array,
- <literal>convert.base64-encode</literal> will insert the value of
- <literal>$parameters['line-break-chars']</literal> every
<literal>$parameters['line-length']</literal>
- characters of base64 output. This allow automatic formatting of encoded
output
- otherwise achieved using <function>chunk_split</function>.
- </entry>
- </row>
- <row>
- <entry><literal>convert.base64-decode</literal></entry>
- <entry>
- <function>base64_decode</function>
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><literal>convert.quoted-printable-encode</literal></entry>
- <entry>
- None. This is the counterpart to quoted-printable-decode.
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>
- <literal>line-break-chars</literal> and <literal>line-length</literal> are
supported
- in the same manner as <literal>convert.base64-encode</literal> above. In
addition,
- <literal>binary</literal> and <literal>force-encode-first</literal> are
supported as
- boolean values which default to &false;.
- </entry>
- </row>
- <row>
- <entry><literal>convert.quoted-printable-decode</literal></entry>
- <entry>
- <function>quoted_printable_decode</function>
- </entry>
- <entry><literal>PHP 5.0.0</literal></entry>
- <entry>
- If <literal>line-break-chars</literal> were specified during the encoding
process,
- they should be specified here again in order to be stripped out for a
successful decode.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
+ <simpara>
+ <literal>convert.base64-encode</literal> and
+ <literal>convert.base64-decode</literal>
+ Use of these filters are equivalent to processing all stream data through
+ the <function>base64_encode</function> and <function>base64_decode</function>
+ functions respectively.
+ <literal>convert.base64-encode</literal> supports parameters given as
+ an associative array. If <parameter>line-length</parameter> is given, the
+ base64 output will be split into chunks of <parameter>line-length</parameter>
+ characters each. If <parameter>line-braek-chars</parameter> is given, each
+ chunk will be delimted by the characters given. These parameters give the
+ same effect as using <function>base64_encode</function> with
+ <function>chunk_split</function>.
+ </simpara>
+ <example>
+ <title>convert.base64_encode</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'convert.base64-encode');
+fwrite($fp, "This is a test.\n");
+fclose($fp);
+/* Outputs: VGhpcyBpcyBhIHRlc3QuCg== */
+
+$param = array('line-length' => 8, 'line-break-chars' => "\r\n");
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'convert.base64-encode', STREAM_FILTER_WRITE, $param);
+fwrite($fp, "This is a test.\n");
+fclose($fp);
+/* Outputs: VGhpcyBp
+ : cyBhIHRl
+ : c3QuCg== */
+
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'convert.base64-decode');
+fwrite($fp, "VGhpcyBpcyBhIHRlc3QuCg==");
+fclose($fp);
+/* Outputs: This is a test. */
+?>
+]]>
+ </programlisting>
+ </example>
+ <simpara>
+ <literal>convert.quoted-printable-encode</literal> and
+ <literal>convert.quoted-printable-decode</literal>
+ Use of the decode version of this filter is equivalent to processing all stream
+ data through the <function>quoted_printable_decode</function> functions.
+ There is no function equivalent to
<literal>convert.quoted-printable-encode</literal>.
+ <literal>convert.quoted-printable-encode</literal> supports parameters given as
+ an associative array. In addition to the parameters supported by
+ <literal>convert.base64-encode</literal>,
<literal>convert.quoted-printable-encode</literal>
+ also supports boolean arguments <parameter>binary</parameter> and
+ <parameter>force-encode-first</parameter>.
+ <literal>convert.base64-decode</literal> only supports the
+ <parameter>line-break-chars</parameter> parameter as a type-hint
+ for striping from the encoded payload.
+ </simpara>
+ <example>
+ <title>string.tolower</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fp = fopen('php://output', 'w');
+stream_filter_append($fp, 'convert.quoted-printable-encode');
+fwrite($fp, "This is a test.\n");
+/* Outputs: =This is a test.=0A */
+?>
+]]>
+ </programlisting>
+ </example>
</section>
</appendix>
