php-doc-en/reference/strings/functions/htmlspecialchars.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlspecialchars" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>htmlspecialchars</refname>
  <refpurpose>Convert special characters to HTML entities</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>htmlspecialchars</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>ENT_COMPAT</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>true</initializer></methodparam>
  </methodsynopsis>
  <para>
   Certain characters have special significance in HTML, and should
   be represented by HTML entities if they are to preserve their
   meanings. This function returns a string with some of these
   conversions made; the translations made are those most
   useful for everyday web programming. If you require all HTML
   character entities to be translated, use
   <function>htmlentities</function> instead.
  </para>
  <simpara>
   This function is useful in preventing user-supplied text from
   containing HTML markup, such as in a message board or guest book
   application.
  </simpara>
  <para>
   The translations performed are:
   <itemizedlist>
    <listitem>
     <simpara>
      '&amp;' (ampersand) becomes '&amp;amp;'
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      '&quot;' (double quote) becomes '&amp;quot;' when <constant>ENT_NOQUOTES</constant>
      is not set.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      &quot;&#039;&quot; (single quote) becomes '&amp;#039;' only when
      <constant>ENT_QUOTES</constant> is set.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      '&lt;' (less than) becomes '&amp;lt;'
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      '&gt;' (greater than) becomes '&amp;gt;'
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       The <type>string</type> being converted.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       The optional second argument, <parameter>flags</parameter>, tells
       the function what to do with single and double quote characters and with
       invalid multi-byte sequences.
       The default mode, <constant>ENT_COMPAT</constant>, is the backwards compatible mode
       which only translates the double-quote character and leaves the
       single-quote untranslated.  If <constant>ENT_QUOTES</constant> is set, both single and
       double quotes are translated and if <constant>ENT_NOQUOTES</constant> is set neither
       single nor double quotes are translated.
       In addition, since 5.3.0, these constants can be combined with
       <constant>ENT_IGNORE</constant>. In that case, strings that contain invalid code unit
       sequences have those invalid sequences discarded instead of having the function
       return an empty string. Avoid using it, as it may have introduce vulnerabilities. 
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>charset</parameter></term>
     <listitem>
      <para>
       Defines character set used in conversion.
       The default character set is ISO-8859-1.
      </para>
      <para>
       For the purposes of this function, the charsets
       <literal>ISO-8859-1</literal>, <literal>ISO-8859-15</literal>,
       <literal>UTF-8</literal>, <literal>cp866</literal>,
       <literal>cp1251</literal>, <literal>cp1252</literal>, and
       <literal>KOI8-R</literal> are effectively equivalent, provided the
       <parameter>string</parameter> itself is valid for the character set, as
       the characters affected by <function>htmlspecialchars</function> occupy
       the same positions in all of these charsets.
      </para>
      &reference.strings.charsets;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>double_encode</parameter></term>
     <listitem>
      <para>
       When <parameter>double_encode</parameter> is turned off PHP will not
       encode existing html entities, the default is to convert everything.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The converted <type>string</type>.
  </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.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.2.3</entry>
       <entry>
        The <parameter>double_encode</parameter> parameter was added.
       </entry>
      </row>
      <row>
       <entry>4.1.0</entry>
       <entry>
        The <parameter>charset</parameter> parameter was added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>htmlspecialchars</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Note that this function does not translate anything beyond what
    is listed above. For full entity translation, see
    <function>htmlentities</function>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>get_html_translation_table</function></member>
    <member><function>htmlspecialchars_decode</function></member>
    <member><function>strip_tags</function></member>
    <member><function>htmlentities</function></member>
    <member><function>nl2br</function></member>
   </simplelist>
  </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
-->