archived-doc-es/reference/image/functions/getimagesize.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6bb90d24b240a0b81e4b203cd8b7ed56bd54033a Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.getimagesize">
 <refnamediv>
  <refname>getimagesize</refname>
  <refpurpose>Devuelve el tamaño de una imagen</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>getimagesize</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">image_info</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>getimagesize</function> determina el tamaño de cualquier imagen soportada
   proporcionada y devuelve las dimensiones, el tipo de imagen y una cadena tipo
   <literal>height/width</literal> para colocar en una etiqueta
   <acronym>HTML</acronym> <tag>IMG</tag> normal
   y el tipo de contenido <acronym>HTTP</acronym> correspondiente.
  </para>
  <para>
   <function>getimagesize</function> puede también devolver más información
   en el argumento <parameter>image_info</parameter>.
  </para>

  <caution>
   <para>
    Esta función espera que <parameter>filename</parameter> sea un
    fichero de imagen válido. Si se proporciona un fichero no imagen, puede ser
    detectado incorrectamente como imagen y la función devolverá con éxito, pero el array puede contener valores absurdos.
   </para>
   <para>
    No se debe utilizar <function>getimagesize</function> para verificar que un
    fichero dado es una imagen válida. En su lugar, debe utilizarse una solución diseñada para ello como la extensión <link linkend="book.fileinfo">FileInfo</link>.
   </para>
  </caution>

  <note>
   <simpara>
    Se debe tener en cuenta que JPC y JP2 pueden tener componentes con diferentes profundidades de bit. En este caso, el valor de "bits" es la mayor profundidad de bit encontrada. Asimismo, los ficheros JP2 disponen de soporte para <literal>multiple JPEG 2000 codestreams</literal>.
    En este caso, <function>getimagesize</function> devuelve los valores
    para el primer codestream encontrado en la raíz del fichero.
   </simpara>
  </note>
  <note>
   <simpara>
    La información sobre iconos se recupera desde el icono con mayor resolución.
   </simpara>
  </note>
  <note>
   <simpara>
    Las imágenes GIF consistentes en uno o varios fotogramas, donde cada fotograma puede ocupar
    únicamente una parte de la imagen. El tamaño de la imagen que es reportado por
    <function>getimagesize</function> es el tamaño global (leído desde el descriptor lógico de la pantalla).
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Este argumento especifica el fichero del cual se desean obtener
       las informaciones. Puede ser un fichero local o (dependiendo
       de la configuración), un fichero remoto utilizando uno de los
       <link linkend="wrappers">flujos soportados</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>image_info</parameter></term>
     <listitem>
      <para>
       Este argumento opcional permite extraer información adicional del fichero de imagen. Actualmente, esta opción
       devuelve diferentes marcadores <acronym>JPG</acronym> APP en un array asociativo. Algunos programas utilizan
       estos marcadores APP para especificar información en las etiquetas
       HTML. Un marcador común es el marcador APP13, descrito
       en <link xlink:href="&url.iptc;">IPTC</link>. Puede utilizarse
       la función <function>iptcparse</function> para analizar este marcador,
       y obtener información legible.
      </para>
      <note>
       <para>
        <parameter>image_info</parameter> soporta únicamente
        los ficheros <acronym>JFIF</acronym>.
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un array que contiene hasta 7 elementos. No todos los tipos
   de imágenes incluyen los elementos <literal>channels</literal> y
   <literal>bits</literal>.
  </para>
  <para>
   El índice 0 contiene el ancho. El índice 1 contiene la altura.
  </para>
  <note>
   <para>
    Algunos formatos pueden no contener ninguna imagen, o bien varias.
    En estos casos, <function>getimagesize</function> puede no ser capaz
    de determinar correctamente el tamaño de la imagen.
    <function>getimagesize</function> devuelve entonces cero como tamaño de
    altura y ancho.
   </para>
  </note>
  <note>
   <simpara>
    <function>getimagesize</function> es independiente de las metadatos de la imagen.
    Por ejemplo, si la bandera Exif <literal>Orientation</literal> está definida en un valor que gira la imagen 90 o 270 grados, los índices 0 y 1 son intercambiados,
    es decir, contienen respectivamente la altura y el ancho.
</simpara>
  </note>
  <para>
   El índice 2 es una constante entre <constant>IMAGETYPE_<replaceable>*</replaceable></constant>,
   indicando el tipo de la imagen.
  </para>
  <para>
   El índice 3 contiene la cadena para colocar en las etiquetas
   <acronym>IMG</acronym>: <literal>height="xxx" width="yyy"</literal>.
  </para>
  <para>
   <literal>mime</literal> corresponde al tipo MIME de una imagen.
   Esta información puede ser utilizada para enviar el encabezado
   HTTP <literal>Content-type</literal> correcto:
   <example>
    <title><function>getimagesize</function> y tipos MIME</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize($filename);
$fp = fopen($filename, "rb");
if ($size && $fp) {
    header("Content-type: {$size['mime']}");
    fpassthru($fp);
    exit;
} else {
    // error
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <literal>channels</literal> será 3 para imágenes RGB y 4 para
   imágenes CMYK.
  </para>
  <para>
   <literal>bits</literal> es el número de bytes para cada color.
  </para>
  <para>
   Sin embargo, la presencia de los valores de <literal>channels</literal> y
   de <literal>bits</literal> puede llevar a la confusión. Por
   ejemplo, una imagen <acronym>GIF</acronym> utiliza siempre tres canales por
   píxel, pero el número de bits por píxel no puede ser calculado en el caso
   de una imagen animada <acronym>GIF</acronym> con una tabla de colores global.
  </para>
  <para>
   Si ocurre un error, &false; es devuelto.
  </para>
 </refsect1>
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Si el acceso a <parameter>filename</parameter> es imposible,
   <function>getimagesize</function> generará un error de nivel
   <constant>E_WARNING</constant>. Si ocurre un error durante la lectura,
   <function>getimagesize</function> generará un error de nivel
   <constant>E_NOTICE</constant>.
  </para>
  <para>
   A partir de PHP 8.0.0, se lanza una excepción <exceptionname>ValueError</exceptionname>
   si <parameter>filename</parameter> está vacío.
  </para>
 </refsect1>
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.2.0</entry>
       <entry>
        Devuelve las dimensiones actuales de la imagen, bits y strings de imágenes AVIF;
        previamente, las dimensiones eran reportadas como <literal>0x0</literal>,
        y bits y strings no eran reportados en absoluto.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Ahora se lanza una excepción <exceptionname>ValueError</exceptionname> si
        <parameter>filename</parameter> está vacío; anteriormente se generaba
        un <constant>E_WARNING</constant> y la función devolvía &false;.
       </entry>
      </row>
      <row>
       <entry>7.1.0</entry>
       <entry>
        Añadido el soporte para WebP.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <function>getimagesize</function></title>
    <programlisting role="php">
<![CDATA[
<?php
list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
echo "<img src=\"img/flag.jpg\" $attr alt=\"Ejemplo con getimagesize()\" />";
?>
]]>
    </programlisting>
   </example>
   <example>
    <title><function>getimagesize</function> con una URL</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("http://www.example.com/gifs/logo.gif");

// Si el nombre del fichero contiene espacios, codifíquelo!
$size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

?>
]]>
    </programlisting>
   </example>
   <example>
    <title><function>getimagesize</function> que devuelve IPTC</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("testimg.jpg", $info);
if (isset($info["APP13"])) {
    $iptc = iptcparse($info["APP13"]);
    var_dump($iptc);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.gd.notrequired;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>image_type_to_mime_type</function></member>
   <member><function>exif_imagetype</function></member>
   <member><function>exif_read_data</function></member>
   <member><function>exif_thumbnail</function></member>
   <member><function>imagesx</function></member>
   <member><function>imagesy</function></member>
  </simplelist>
 </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
-->