archived-doc-es/reference/mbstring/functions/mb-detect-encoding.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 7c4b5fb40ac3149a5b931f1e31b1050ab5eaab7e Maintainer: Marqitos 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>Detectar la codificación de caracteres</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>
   Detectar la codificación de caracteres más probable para la <type>string</type> <parameter>string</parameter>
   desde una lista de candidatos.
  </para>
  <para>
   A partir de PHP 8.1, esta función utiliza heurística para detectar cuál de las codificaciones de texto válidas en la lista
   especificada tiene más probabilidades de ser correcta y puede no estar en el orden de <parameter>encodings</parameter> proporcionado.
  </para>
  <para>
   La detección automática del juego de caracteres previsto nunca es totalmente
   fiable; sin información adicional, es similar a descifrar una cadena cifrada sin la clave. Siempre es preferible utilizar una indicación del juego de caracteres almacenado o transmitido con los datos,
   como el encabezado HTTP "Content-Type".
  </para>
  <para>
   Esta función se utiliza principalmente con codificaciones multibyte, donde no todas las secuencias de
   bytes forman una cadena válida. Si la cadena de entrada contiene una secuencia de este tipo, esta
   codificación será rechazada.
  </para>

  <warning>
   <title>El resultado no es fiable</title>
   <para>
    El nombre de esta función es engañoso, realiza una «suposición» en lugar de una «detección».
   </para>
   <para>
    Las suposiciones están lejos de ser precisas, y por lo tanto, esta función no permite
    detectar de manera fiable la codificación correcto de los caracteres.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       El <type>string</type> que será inspeccionado.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>encodings</parameter></term>
     <listitem>
      <para>
       Una lista de codificaciones de caracteres a probar. Esta lista puede ser especificada como
       un &array; de &string;, o como un &string; único separado por comas.
      </para>
      <para>
       Si <parameter>encodings</parameter> es omitido o &null;,
       el será utilizado el detect_order actual (definido con la opción de configuración
       <link linkend="ini.mbstring.detect-order">mbstring.detect_order</link>,
       o la función <function>mb_detect_order</function>).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>strict</parameter></term>
     <listitem>
      <para>
       Controla el comportamiento cuando <parameter>string</parameter> no es
       válido en ninguno de los <parameter>encodings</parameter> listados.
       Si <parameter>strict</parameter> está definido como &false;, se devolverá la codificación
       más coincidente; si <parameter>strict</parameter>
       está definido como &true;, devolverá &false;.
      </para>
      <para>
       El valor por omisión de <parameter>strict</parameter> puede ser definido
       con la opción de configuración
       <link linkend="ini.mbstring.strict-detection">mbstring.strict_detection</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   La codificación caracteres detectado, o &false; si la cadena no es válida
   en ninguna de las codificaciones listadas.
  </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> ya no devolverá las siguientes
       codificaciones que no sean de texto:
       <literal>"Base64"</literal>, <literal>"QPrint"</literal>,
       <literal>"UUencode"</literal>, <literal>"HTML entities"</literal>,
       <literal>"7 bit"</literal> y <literal>"8 bit"</literal>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <function>mb_detect_encoding</function></title>
    <programlisting role="php">
<![CDATA[
<?php

$str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

// Detecta la codificación con el detect_order actual
var_dump(mb_detect_encoding($str));

// "auto" es modificado según mbstring.language
var_dump(mb_detect_encoding($str, "auto"));

// Especifica el parámetro "encodings" con una lista separada por comas
var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

// Uso de un array para especificar el parámetro "encodings"
$encodings = [
  "ASCII",
  "JIS",
  "EUC-JP"
];
var_dump(mb_detect_encoding($str, $encodings));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
string(5) "ASCII"
string(5) "ASCII"
string(8) "SJIS-win"
string(5) "ASCII"
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Efecto del parámetro <parameter>strict</parameter></title>
    <programlisting role="php">
<![CDATA[
<?php
// 'áéóú' codificado en ISO-8859-1
$str = "\xE1\xE9\xF3\xFA";

// La cadena no válica en ASCII ni UTF-8, pero UTF-8 se considera una coincidencia más cercana
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

// Si se encuentra una codificación válida, el parámetro "strict" no cambia el resultado
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>
   En ciertos casos, la misma secuencia de bytes puede formar una cadena válida
   en diferentes codificaciones de caracteres, y es imposible determinar
   cuál interpretación era prevista. Un ejemplo, entre otros,
   la secuencia de bytes "\xC4\xA2" podría ser:
  </para>
  <para>
   <simplelist>
    <member>
     "Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS seguido de U+00A2 CENT SIGN)
     codificado en ISO-8859-1, ISO-8859-15, o Windows-1252
    </member>
    <member>
     "ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF seguido de U+0402 CYRILLIC CAPITAL LETTER
     DJE) codificado en ISO-8859-5
    </member>
    <member>
     "Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) codificado en UTF-8
    </member>
   </simplelist>
  </para>
  <para>
   <example>
    <title>Efecto del orden cuando coinciden múltiples codificaciones</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = "\xC4\xA2";

// La cadena es válida en las tres codificaciones, pero no siempre devolverá el primero de la lista
var_dump(mb_detect_encoding($str, ['UTF-8']));
var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // A partir de PHP 8.1 esto devolverá ISO-8859-1 en vez de UTF-8
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-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
-->