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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 06394ea77c2f8972e3884c00bede861ef5eb04da 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>
   Pour réaliser l'opération inverse, il faut 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
            chaîne 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 du 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> a 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 <b>gras</b>';

echo htmlentities($str);
echo "\n\n";
echo htmlentities($str, ENT_COMPAT);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Un &#039;apostrophee&#039; est &lt;b&gt;gras&lt;/b&gt;

Un 'apostrophe' est &lt;b&gt;gras&lt;/b&gt
]]>
    </screen>
   </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
-->