svn: /phpdoc/ doc-base/trunk/entities/global.ent en/trunk/reference/strings/functions/htmlentities.xml
en/trunk/reference/strings/functions/htmlspecialchars.xml

From: Date: Fri, 27 Jan 2012 20:42:48 +0000
Subject: svn: /phpdoc/ doc-base/trunk/entities/global.ent en/trunk/reference/strings/functions/htmlentities.xml
en/trunk/reference/strings/functions/htmlspecialchars.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-9504@lists.php.net to get a copy of this message
nikic Fri, 27 Jan 2012 20:42:48 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=322868 Log: Minor improvements to htmlspecialchars() and htmlentities() docs Changed paths: U phpdoc/doc-base/trunk/entities/global.ent U phpdoc/en/trunk/reference/strings/functions/htmlentities.xml U phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml Modified: phpdoc/doc-base/trunk/entities/global.ent =================================================================== --- phpdoc/doc-base/trunk/entities/global.ent 2012-01-27 20:33:53 UTC (rev 322867) +++ phpdoc/doc-base/trunk/entities/global.ent 2012-01-27 20:42:48 UTC (rev 322868) @@ -81,6 +81,7 @@ <!ENTITY url.dbx.docs "http://www.guidance.nl/php/dbx/doc/"> <!ENTITY url.dbxsl "http://docbook.sourceforge.net/"> <!ENTITY url.debian "http://www.debian.org/"> +<!ENTITY url.delete.nonchars "http://unicode.org/reports/tr36/#Deletion_of_Noncharacters"> <!ENTITY url.derick.references "http://derickrethans.nl/php_references_article.php"> <!ENTITY url.diophantine-equation "http://mathworld.wolfram.com/DiophantineEquation.html"> <!ENTITY url.dmalloc "http://dmalloc.com/"> Modified: phpdoc/en/trunk/reference/strings/functions/htmlentities.xml =================================================================== --- phpdoc/en/trunk/reference/strings/functions/htmlentities.xml 2012-01-27 20:33:53 UTC (rev 322867) +++ phpdoc/en/trunk/reference/strings/functions/htmlentities.xml 2012-01-27 20:42:48 UTC (rev 322868) @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> -<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlentities"> +<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlentities" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>htmlentities</refname> <refpurpose>Convert all applicable characters to HTML entities</refpurpose> @@ -21,7 +21,7 @@ have HTML character entity equivalents are translated into these entities. </para> <para> - If you're wanting to decode instead (the reverse) you can use + If you want to decode instead (the reverse) you can use <function>html_entity_decode</function>. </para> </refsect1> @@ -71,8 +71,8 @@ <entry><constant>ENT_IGNORE</constant></entry> <entry> Silently discard invalid code unit sequences instead of returning - an empty string. This is provided for backwards compatibility; - avoid using it as it may have security implications. + an empty string. Using this flag is discouraged as it + <link xlink:href="&url.delete.nonchars;">may have security implications</link>. </entry> </row> <row> @@ -123,14 +123,12 @@ <term><parameter>charset</parameter></term> <listitem> <para> - Like <function>htmlspecialchars</function>, - <function>htmlentities</function> takes an optional third argument - <parameter>charset</parameter> which defines character set used in - conversion. - If omitted, the default value for this argument is ISO-8859-1 in - versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards. - Although this argument is technically optional, you are highly - encouraged to specify the correct value for your code. + Like <function>htmlspecialchars</function>, it takes an optional + third argument <parameter>charset</parameter> which defines character + set used in conversion. + Presently, the ISO-8859-1 character set is used as the default. + However, this default is very likely to change in future versions of + PHP; the programmer is highly encouraged to specify a value. </para> &reference.strings.charsets; </listitem> @@ -153,6 +151,12 @@ <para> Returns the encoded string. </para> + <para> + If the input <parameter>string</parameter> contains an invalid code unit + sequence within the given <parameter>charset</parameter> an empty string + will be returned, unless either the <constant>ENT_IGNORE</constant> or + <constant>ENT_SUBSTITUTE</constant> flags are set. + </para> </refsect1> <refsect1 role="changelog"> @@ -170,13 +174,6 @@ <row> <entry>5.4.0</entry> <entry> - The default value for the <parameter>charset</parameter> parameter was - changed to UTF-8. - </entry> - </row> - <row> - <entry>5.4.0</entry> - <entry> The constants <constant>ENT_SUBSTITUTE</constant>, <constant>ENT_DISALLOWED</constant>, <constant>ENT_HTML401</constant>, <constant>ENT_XML1</constant>, <constant>ENT_XHTML</constant> and <constant>ENT_HTML5</constant> were added. Modified: phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml =================================================================== --- phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml 2012-01-27 20:33:53 UTC (rev 322867) +++ phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml 2012-01-27 20:42:48 UTC (rev 322868) @@ -108,8 +108,8 @@ <entry><constant>ENT_IGNORE</constant></entry> <entry> Silently discard invalid code unit sequences instead of returning - an empty string. This is provided for backwards compatibility; - avoid using it as it may have security implications. + an empty string. Using this flag is discouraged as it + <link xlink:href="&url.delete.nonchars;">may have security implications</link>. </entry> </row> <row> @@ -161,8 +161,7 @@ <listitem> <para> Defines character set used in conversion. - If omitted, the default value for this argument is ISO-8859-1 in - versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards. + The default character set is ISO-8859-1. </para> <para> For the purposes of this function, the charsets @@ -197,9 +196,9 @@ </para> <para> If the input <parameter>string</parameter> contains an invalid code unit - sequence within the given <parameter>charset</parameter> and the - <constant>ENT_IGNORE</constant> flag is not set, then - <function>htmlspecialchars</function> will return an empty string. + sequence within the given <parameter>charset</parameter> an empty string + will be returned, unless either the <constant>ENT_IGNORE</constant> or + <constant>ENT_SUBSTITUTE</constant> flags are set. </para> </refsect1> @@ -218,13 +217,6 @@ <row> <entry>5.4.0</entry> <entry> - The default value for the <parameter>charset</parameter> parameter was - changed to UTF-8. - </entry> - </row> - <row> - <entry>5.4.0</entry> - <entry> The constants <constant>ENT_SUBSTITUTE</constant>, <constant>ENT_DISALLOWED</constant>, <constant>ENT_HTML401</constant>, <constant>ENT_XML1</constant>, <constant>ENT_XHTML</constant> and <constant>ENT_HTML5</constant> were added.

« previous php.doc.cvs (#9504) next »