svn: /phpdoc/ doc-base/trunk/entities/global.ent en/trunk/reference/strings/functions/htmlentities.xml
en/trunk/reference/strings/functions/htmlspecialchars.xml
| From: | Nikita Popov | 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.