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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 840ed22479a110ab63bce0fa75d5f3c41642b8e3 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.htmlentities" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>htmlentities</refname>
  <refpurpose>Convertit tous les caractères éligibles en entités HTML</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>htmlentities</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>
   <function>htmlentities</function> est identique à la fonction
   <function>htmlspecialchars</function>, sauf que tous les caractères
   qui ont des équivalents en entités HTML sont effectivement
   traduits.
   La fonction <function>get_html_translation_table</function> peut être utilisée
   pour retourner la table de traduction utilisée
   en fonction des constantes <parameter>flags</parameter> fournies.
  </para>
  <para>
   Si vous voulez réaliser l'opération inverse, vous devez utiliser 
   la fonction <function>html_entity_decode</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       La chaîne d'entrée.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Un masque 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ée 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;#FFFD; (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;#FFFD;
            (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;
      &reference.strings.charsets;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>double_encode</parameter></term>
     <listitem>
      <para>
       Lorsque <parameter>double_encode</parameter> est désactivé, PHP n'encodera pas
       les entités html existantes. Par défaut, tout est converti.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne la chaîne encodée.
  </para>
  <para>
   Si l'entrée <parameter>string</parameter> contient une séquence de
   code invalide dans l'encodage <parameter>encoding</parameter>
   fourni, une chaîne vide sera retournée, à moins que le drapeau
   <constant>ENT_IGNORE</constant> ou le drapeau
   <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>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>encoding</parameter> est désormais nullable.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>htmlentities</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'Un \'apostrophe\' en <strong>gras</strong>';

// Affiche : Un 'apostrophe' en &lt;strong&gt;gras&lt;/strong&gt;
echo htmlentities($str);

// Affiche : Un &#039;apostrophe&#039; en &lt;strong&gt;gras&lt;/strong&gt;
echo htmlentities($str, ENT_QUOTES);
?>
]]>
    </programlisting>
   </example>
  </para>
  
  <para>
   <example>
    <title>Utilisation de <constant>ENT_IGNORE</constant></title>
    <programlisting role="php">
<![CDATA[
<?php
$str = "\x8F!!!";

// Affiche une chaine vide
echo htmlentities($str, ENT_QUOTES, "UTF-8");

// Affiche "!!!"
echo htmlentities($str, ENT_QUOTES | ENT_IGNORE, "UTF-8");
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

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