doc-fr/reference/mbstring/functions/mb-detect-encoding.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 2c17cef6e71c3d85011319cde128cc4edf89a053 Maintainer: girgias Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.mb-detect-encoding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mb_detect_encoding</refname>
  <refpurpose>Détecte un encodage</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>false</type></type><methodname>mb_detect_encoding</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>string</type><type>null</type></type><parameter>encodings</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>strict</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Détecte l'encodage le plus probable pour la &string;
   <parameter>string</parameter> depuis une liste ordonnée de candidats.
  </para>
  <para>
   La détection automatique du jeu d'encodage prévu n'est jamais totalement
   fiable ; sans information additionnelles, c'est similaire à décoder une
   chaîne chiffré sans la clé. Il est toujours préférable d'utiliser une
   indication du jeu d'encodage stocké ou transmis avec les données,
   tel que l'en-tête HTTP "Content-Type".
  </para>
  <para>
   Cette fonction est le plus utilise avec les encodages multioctets, où
   pas toutes les séquences d'octets forment une chaîne valide. Si la chaîne
   d'entrée contient un telle séquence, cet encodage sera rejeté, et le
   prochain encodage sera vérifié.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       La <type>string</type> étant inspecté.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>encodings</parameter></term>
     <listitem>
      <para>
       Une liste d'encodage de caractères à essayer, dans l'ordre.
       Cette liste peut être spécifier comme un &array; de &string;,
       en tant qu'une &string; unique séparé par des virgules.
      </para>
      <para>
       Si <parameter>encodings</parameter> est omis ou &null;,
       le detect_order actuel (défini avec l'option de configuration
       <link linkend="ini.mbstring.detect-order">mbstring.detect_order</link>,
       ou la fonction <function>mb_detect_order</function>) sera utilisé.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>strict</parameter></term>
     <listitem>
      <para>
       Contrôle le comportement quand <parameter>string</parameter> n'est
       valide dans aucun des <parameter>encodings</parameter> listé.
       Si <parameter>strict</parameter> est défini à &false;, l'encodage qui
       correspond le plus sera retourné ; si <parameter>strict</parameter>
       est défini à &true;, &false; sera retourné.
      </para>
      <para>
       La valeur par défaut de <parameter>strict</parameter> peut être définie
       avec l'option de configuration
       <link linkend="ini.mbstring.strict-detection">mbstring.strict_detection</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   L'encodage de caractère détecté, ou &false; si la chaîne n'est pas valide
   dans un seul des encodages listé.
  </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.2.0</entry>
      <entry>
       <function>mb_detect_encoding</function> ne renverra plus
       les encodages non textuels suivants :
       <literal>"Base64"</literal>, <literal>"QPrint"</literal>,
       <literal>"UUencode"</literal>, <literal>"HTML entities"</literal>,
       <literal>"7 bit"</literal> et <literal>"8 bit"</literal>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>mb_detect_encoding</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// Détecte l'encodage avec le detect_order actuel
echo mb_detect_encoding($str);

// "auto" est modifié selon mbstring.language
echo mb_detect_encoding($str, "auto");

// Spécifie le paramètre "encodings" avec une liste à virgules
echo mb_detect_encoding($str, "JIS, eucjp-win, sjis-win");

// Utilisation d'un tableau pour spécifie le paramètre "encodings"
$encodings = [
  "ASCII",
  "JIS",
  "EUC-JP"
];
echo mb_detect_encoding($str, $encodings);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Effet du paramètre <parameter>strict</parameter></title>
    <programlisting role="php">
<![CDATA[
<?php
// 'áéóú' encoded in ISO-8859-1
$str = "\xE1\xE9\xF3\xFA";

// The string is not valid ASCII or UTF-8, but UTF-8 is considered a closer match
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

// If a valid encoding is found, the strict parameter does not change the result
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
string(5) "UTF-8"
bool(false)
string(10) "ISO-8859-1"
string(10) "ISO-8859-1"
]]>
    </screen>
   </example>
  </para>
  <para>
   Dans certain cas, la même séquences d'octet peut former une chaîne valide
   dans différents encodages de caractères, et il est impossible de déterminer
   quelle interprétation était prévu. Un exemple, parmi tant d'autres,
   la séquence d'octets "\xC4\xA2" pourrait être :
  </para>
  <para>
   <simplelist>
    <member>
     "Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS suivi de U+00A2 CENT SIGN)
     encodé dans un de ISO-8859-1, ISO-8859-15, ou Windows-1252
    </member>
    <member>
     "ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF suivi de U+0402 CYRILLIC CAPITAL LETTER
     DJE) encodé en ISO-8859-5
    </member>
    <member>
     "Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) encodé en UTF-8
    </member>
   </simplelist>
  </para>
  <para>
   <example>
    <title>Effet de l'ordre quand plusieurs encodages correspondent</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = "\xC4\xA2";

// The string is valid in all three encodings, so the first one listed will be returned
var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5']));
var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
string(5) "UTF-8"
string(10) "ISO-8859-1"
string(10) "ISO-8859-5"
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mb_detect_order</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
-->