archived-doc-es/reference/strings/functions/htmlspecialchars.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d45a16b5f91dfa1702a2d185fa1b627cac5b1341 Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlspecialchars" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>htmlspecialchars</refname>
  <refpurpose>Convierte caracteres especiales en entidades 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_COMPAT | ENT_HTML401</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>encoding</parameter><initializer>ini_get("default_charset")</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>true</initializer></methodparam>
  </methodsynopsis>
  <para>
   Ciertos caracteres tienen un significado especial en HTML y deben
   ser representados por entidades HTML si se desea preservar su
   significado. Esta función devuelve un string con estas
   conversiones realizadas. Si se requiere que todas las subcadenas de entrada tengan asociadas
   entidades con nombre para que sean traducidas, use <function>htmlentities</function>
   en su lugar.
  </para>
  <para>
   Si el string de entrada pasado a esta función y el documento final comparten el
   mismo conjunto de carcteres, esta función es suficiente para preparar entradas para
   su inclusión en la mayoría de los contextos de un documento HTML. Sin embargo, si la entrada puede
   representar caracteres que no están codificados en el conjunto de caracteres del documento final,
   y es necesario conservar dichos caracteres (tales como números o entidades con nombre),
   esta función y <function>htmlentities</function> (la cual solamente codifica
   subcadenas que tienen equivalentes de entidades con nombre) podrían ser insuficientes.
   Se podria usar <function>mb_encode_numericentity</function> en su lugar.
  </para>
  <para>
   Las traducciones realizadas son:
   <itemizedlist>
    <listitem>
     <simpara>
      '&amp;' (et) se convierte en '&amp;amp;'
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      '&quot;' (comillas dobles) se convierte en '&amp;quot;' cuando <constant>ENT_NOQUOTES</constant>
      no está establecido.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      &quot;&#039;&quot; (comilla simple) se convierte en '&amp;#039;' (o &amp;apos;)
      sólo cuando <constant>ENT_QUOTES</constant> está establecido.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      '&lt;' (menor que) se convierte en '&amp;lt;'
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      '&gt;' (mayor que) se convierte en '&amp;gt;'
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       El <type>string</type> a convertir.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Una máscara de bits de una o más de los siguientes indicadores, los cuales especifican cómo manejar las comillas,
       las secuencias de unidad de código inválidas y el tipo de documento utilizado. El valor predeterminado es
       <literal>ENT_COMPAT | ENT_HTML401</literal>.
       <table>
        <title>Constantes disponibles para <parameter>flags</parameter></title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Nombre de la constante</entry>
           <entry>Descripción</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>ENT_COMPAT</constant></entry>
           <entry>Convertirá las comillas dobles y sólo dejará las comillas simples.</entry>
          </row>
          <row>
           <entry><constant>ENT_QUOTES</constant></entry>
           <entry>Convertirá tanto las comillas dobles como las simples.</entry>
          </row>
          <row>
           <entry><constant>ENT_NOQUOTES</constant></entry>
           <entry>Dejará tanto las comillas dobles como las simples sin convertir.</entry>
          </row>
          <row>
           <entry><constant>ENT_IGNORE</constant></entry>
           <entry>
            Descartar silenciosamente unidades de secuencia de código no válidas en lugar de devolver
            un string vacío. No se recomienda el uso de este indicador, ya que
            <link xlink:href="&url.delete.nonchars;">puede tener implicaciones de seguridad</link>.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_SUBSTITUTE</constant></entry>
           <entry>
            Reemplazar las secuencias de unidad de código inválidas con un Carácter de Reemplazo Unicode
            U+FFFD (UTF-8) o &amp;#FFFD; (no UTF-8) en lugar de devolver un string vacío.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_DISALLOWED</constant></entry>
           <entry>
            Reemplazar los puntos de código no válidos para el tipo de documento dado con un
            Carácter de Reemplazo Unicode U+FFFD (UTF-8) o &amp;#FFFD;
            (no UTF-8) en lugar de dejarlos tal cual. Esto puede ser útil, por
            ejemplo, para asegurar que los documentos XML estén bien formados con
            contenido externo incrustado.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_HTML401</constant></entry>
           <entry>
            Maneja el código como HTML 4.01.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_XML1</constant></entry>
           <entry>
            Maneja el código como XML 1.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_XHTML</constant></entry>
           <entry>
            Maneja el código como XHTML.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_HTML5</constant></entry>
           <entry>
            Maneja el código como HTML 5.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>encoding</parameter></term>
     <listitem>
      &strings.parameter.encoding;
      <para>
       Para el propósito de ésta función, los juegos de caracteres
       <literal>ISO-8859-1</literal>, <literal>ISO-8859-15</literal>,
       <literal>UTF-8</literal>, <literal>cp866</literal>,
       <literal>cp1251</literal>, <literal>cp1252</literal> y
       <literal>KOI8-R</literal> son realmente equivalentes, siempre y cuando el
       <parameter>string</parameter> sea válido para la codificación, ya que
       los caracteres afectados por <function>htmlspecialchars</function> ocupan
       las mismas posiciones en todas estas codificaciones.
      </para>
      &reference.strings.charsets;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>double_encode</parameter></term>
     <listitem>
      <para>
       Cuando <parameter>double_encode</parameter> se desactiva, PHP no codificará
       las entidades HTML existentes. El valor predeterminado es convertirlo todo.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   El <type>string</type> convertido.
  </para>
  <para>
   Si el <parameter>string</parameter> de entrada contiene una secuencia de unidad de código
   no válida en <parameter>encoding</parameter>, devolverá un string
   vacío, a menos que cualquiera de los indicadores <constant>ENT_IGNORE</constant> o
   <constant>ENT_SUBSTITUTE</constant> estén establecidos.
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      &strings.changelog.encoding;
      <row>
       <entry>5.4.0</entry>
       <entry>
        El valor predeterminado del parámetro <parameter>encoding</parameter> se
        cambió a UTF-8.
       </entry>
      </row>
      <row>
       <entry>5.4.0</entry>
       <entry>
        Se añadieron las constantes <constant>ENT_SUBSTITUTE</constant>, <constant>ENT_DISALLOWED</constant>,
        <constant>ENT_HTML401</constant>, <constant>ENT_XML1</constant>,
        <constant>ENT_XHTML</constant> y <constant>ENT_HTML5</constant>.
       </entry>
      </row>
      <row>
       <entry>5.3.0</entry>
       <entry>
        Se añadió la constante <constant>ENT_IGNORE</constant>.
       </entry>
      </row>
      <row>
       <entry>5.2.3</entry>
       <entry>
        Se añadió el parámetro <parameter>double_encode</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>htmlspecialchars</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$nuevo = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $nuevo; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Se ha de tener en cuenta que esta función no traduce nada más de lo que
    aparece en la lista de arriba. Para la traducción completa de entidades, véase
    <function>htmlentities</function>.
   </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
-->