cvs: phpdoc /en/appendices filters.xml

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 &lt;&gt; 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>