doc-fr/reference/strings/functions/htmlspecialchars.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: eabde0419cf90f596f60db00e31fcb6ebe41ac55 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.htmlspecialchars" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>htmlspecialchars</refname>
  <refpurpose>Convertit les caractères spéciaux en entités HTML</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_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>&true;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Certains caractères ont des significations spéciales en HTML,
   et doivent être remplacés par des entités HTML pour conserver
   leurs significations. Cette fonction retourne une chaîne de caractères
   avec ces modifications. Si vous avez besoin que toutes
   les sous-chaînes en entrée qui sont associées à des entités
   nommées soient transformées, utilisez la fonction
   <function>htmlentities</function>.
  </para>
  <para>
   Si la chaîne en entrée passée à cette fonction et le document final
   partagent le même jeu de caractères, cette fonction est suffisante pour
   préparer l'entrée pour une inclusion dans la plupart des contextes
   d'un document HTML. Si cependant, l'entrée peut présenter des caractères
   qui ne sont pas codés dans le jeu de caractères du document final,
   et que vous souhaitez épargner ces caractères (comme des numériques ou
   des entités nommés), cette fonction et la fonction <function>htmlentities</function>
   (qui n'encodes que les sous-chaînes qui ont des entités nommés équivalentes)
   ne sont pas suffisantes. Vous devez utiliser la fonction
   <function>mb_encode_numericentity</function> à la place.
  </para>
  <para>
   <table>
    <title>Remplacement effectué</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Caractère</entry>
       <entry>Remplacement</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>&amp;</literal> (ET commercial)</entry>
       <entry><literal>&amp;amp;</literal></entry>
      </row>
      <row>
       <entry><literal>&quot;</literal> (double guillement)</entry>
       <entry><literal>&amp;quot;</literal> sauf si <constant>ENT_NOQUOTES</constant></entry>
      </row>
      <row>
       <entry><literal>'</literal> (simple guillemet)</entry>
       <entry>
        <literal>&amp;#039;</literal> (pour <constant>ENT_HTML401</constant>) ou
        <literal>&amp;apos;</literal> (pour
        <constant>ENT_XML1</constant>, <constant>ENT_XHTML</constant> ou
        <constant>ENT_HTML5</constant>), mais seulement lorsque
        <constant>ENT_QUOTES</constant> est défini
       </entry>
      </row>
      <row>
       <entry><literal>&lt;</literal> (inférieur à)</entry>
       <entry><literal>&amp;lt;</literal></entry>
      </row>
      <row>
       <entry><literal>&gt;</literal> (supérieur à)</entry>
       <entry><literal>&amp;gt;</literal></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       La chaîne à convertir.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Un masque bit d'un ou plusieurs drapeaux suivants, qui déterminent la façon
       dont les guillemets seront gérés, dont les séquences de code invalide seront
       gérées ainsi que le type du document utilisé. Par défaut, c'est
       <literal>ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</literal>.
       <table>
        <title>Constantes disponibles pour <parameter>flags</parameter></title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Constante</entry>
           <entry>Description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>ENT_COMPAT</constant></entry>
           <entry>Convertit les guillemets doubles, et ignore les guillemets simples.</entry>
          </row>
          <row>
           <entry><constant>ENT_QUOTES</constant></entry>
           <entry>Convertit les guillemets doubles et les guillemets simples.</entry>
          </row>
          <row>
           <entry><constant>ENT_NOQUOTES</constant></entry>
           <entry>Ignore les guillemets doubles et les guillemets simples.</entry>
          </row>
          <row>
           <entry><constant>ENT_IGNORE</constant></entry>
           <entry>
            Ignore les séquences de caractères invalides plutôt que de retourner une
            chaine vide. L'utilisation de ce drapeau est fortement
            déconseillé pour des
            <link xlink:href="&url.delete.nonchars;">raisons de sécurité</link>.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_SUBSTITUTE</constant></entry>
           <entry>
            Remplace les séquences de code invalide avec un caractère de remplacement
            Unicode U+FFFD (UTF-8) ou &amp;#xFFFD; (sinon) au lieu de retourner une
            chaîne vide.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_DISALLOWED</constant></entry>
           <entry>
            Remplace les points du code invalides du document fourni avec
            un caractère de remplacement Unicode U+FFFD (UTF-8) ou &amp;#xFFFD;
            (sinon) au lieu de le laisser tel quel. Ceci peut être utile pour,
            par exemple, s'assurer du bon formatage de documents XML contenant
            du contenu externe.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_HTML401</constant></entry>
           <entry>
            Gère le code comme étant du HTML 4.01.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_XML1</constant></entry>
           <entry>
            Gère le code comme étant du XML 1.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_XHTML</constant></entry>
           <entry>
            Gère le code comme étant du XHTML.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_HTML5</constant></entry>
           <entry>
            Gère le code comme étant du HTML 5.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>encoding</parameter></term>
     <listitem>
      &strings.parameter.encoding;
      <para>
       Pour cette fonction, les encodages
       <literal>ISO-8859-1</literal>, <literal>ISO-8859-15</literal>,
       <literal>UTF-8</literal>, <literal>cp866</literal>,
       <literal>cp1251</literal>, <literal>cp1252</literal>, et
       <literal>KOI8-R</literal> sont équivalents, à condition
       que le paramètre <parameter>string</parameter> soit valable
       pour l'encodage, dans le sens où les caractères affectés par la fonction
       <function>htmlspecialchars</function> occupent la même position
       dans tous ces encodages.
      </para>
      &reference.strings.charsets;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>double_encode</parameter></term>
     <listitem>
      <para>
       Lorsque le paramètre <parameter>double_encode</parameter> est désactivé,
       PHP n'encodera pas les entités html existants ; par défaut, tout est converti.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   La chaîne convertie.
  </para>
  <para>
   Si la chaîne d'entrée <parameter>string</parameter> contient une
   séquence de code invalide dans le paramètre
   <parameter>encoding</parameter> fourni, une chaîne vide sera retournée
   à moins que le drapeau <constant>ENT_IGNORE</constant> ou
   <constant>ENT_SUBSTITUTE</constant> ne soit défini.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.1.0</entry>
      <entry>
       <parameter>flags</parameter> à changé de <constant>ENT_COMPAT</constant> à
       <constant>ENT_QUOTES</constant> | <constant>ENT_SUBSTITUTE</constant> | <constant>ENT_HTML401</constant>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>htmlspecialchars</function></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>
    Notez que cette fonction ne fait aucun autre remplacement que ceux
    qui sont listés ci-dessus. Pour faire un remplacement total,
    voyez plutôt <function>htmlentities</function>.
   </para>
  </note>
  <note>
   <para>
    Dans le cas d'une valeur ambigue pour <parameter>flags</parameter>,
    les règles suivantes s'appliquent :
   </para>
   <para>
    <itemizedlist>
     <listitem>
      <simpara>
       Quand aucun de <constant>ENT_COMPAT</constant>,
       <constant>ENT_QUOTES</constant>,
       <constant>ENT_NOQUOTES</constant> est présent,
       la valeur par défaut est <constant>ENT_NOQUOTES</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Quand plus d'un des <constant>ENT_COMPAT</constant>,
       <constant>ENT_QUOTES</constant>,
       <constant>ENT_NOQUOTES</constant> sont présent,
       <constant>ENT_QUOTES</constant> prend la plus haute priorité,
       suivi de <constant>ENT_COMPAT</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Quand aucun de <constant>ENT_HTML401</constant>,
       <constant>ENT_HTML5</constant>,
       <constant>ENT_XHTML</constant>, <constant>ENT_XML1</constant> est présent,
       la valeur par défaut est <constant>ENT_HTML401</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Quand plus d'un des <constant>ENT_HTML401</constant>,
       <constant>ENT_HTML5</constant>,
       <constant>ENT_XHTML</constant>, <constant>ENT_XML1</constant> sont présent,
       <constant>ENT_HTML5</constant> prend la plus haute priorité,
       suivi de <constant>ENT_XHTML</constant>, <constant>ENT_XML1</constant> et
       <constant>ENT_HTML401</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Quand plus d'un des <constant>ENT_DISALLOWED</constant>,
       <constant>ENT_IGNORE</constant>,
       <constant>ENT_SUBSTITUTE</constant> sont présent,
       <constant>ENT_IGNORE</constant> prend la plus haute priorité,
       suivi de <constant>ENT_SUBSTITUTE</constant>.
      </simpara>
     </listitem>
    </itemizedlist>
   </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
-->