<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.getimagesize">
 <refnamediv>
  <refname>getimagesize</refname>
  <refpurpose>Get the size of an image</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>
   The <function>getimagesize</function> function will determine the
   size of any supported given image file and return the dimensions along with
   the file type and a <literal>height/width</literal> text string to be used inside a
   normal <acronym>HTML</acronym> <tag>IMG</tag> tag and the
   correspondent <acronym>HTTP</acronym> content type.
  </para>
  <para>
   <function>getimagesize</function> can also return some more information
   in <parameter>image_info</parameter> parameter.
  </para>
  <caution>
   <para>
    This function expects <parameter>filename</parameter> to be a valid
    image file. If a non-image file is supplied, it may be incorrectly
    detected as an image and the function will return successfully, but
    the array may contain nonsensical values.
   </para>
   <para>
    Do not use <function>getimagesize</function> to check that a given
    file is a valid image. Use a purpose-built solution such as the
    <link linkend="book.fileinfo">Fileinfo</link> extension instead.
   </para>
  </caution>
  <note>
   <simpara>
    Note that JPC and JP2 are capable of having components with different 
    bit depths. In this case, the value for "bits" is the highest bit depth encountered. Also, JP2
    files may contain <literal>multiple JPEG 2000 codestreams</literal>. In this case,
    <function>getimagesize</function> returns the values for the first
    codestream it encounters in the root of the file.
   </simpara>
  </note>
  <note>
   <simpara>
    The information about icons are retrieved from the icon with the highest
    bitrate.
   </simpara>
  </note>
  <note>
   <simpara>
    GIF images consist of one or more frames, where each frame may only occupy
    part of the image. The size of the image which is reported by
    <function>getimagesize</function> is the overall size (read from the logical
    screen descriptor).
   </simpara>
  </note>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
        This parameter specifies the file you wish to retrieve information
        about. It can reference a local file or (configuration permitting) a
        remote file using one of the <link linkend="wrappers">supported streams</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>image_info</parameter></term>
     <listitem>
      <para>
       This optional parameter allows you to extract some extended
       information from the image file. Currently, this will return the
       different <acronym>JPG</acronym> APP markers as an associative array.
       Some programs use these APP markers to embed text information in 
       images. A very common one is to embed 
       <link xlink:href="&url.iptc;">IPTC</link> information in the APP13 marker.
       You can use the <function>iptcparse</function> function to parse the
       binary APP13 marker into something readable.
      </para>
      <note>
       <para>
        The <parameter>image_info</parameter> only supports
        <acronym>JFIF</acronym> files.
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array with up to 7 elements. Not all image types will include
   the <literal>channels</literal> and <literal>bits</literal> elements.
  </para>
  <para>
   Index 0 and 1 contains respectively the width and the height of the image.
  </para>
  <note>
   <para>
    Some formats may contain no image or may contain multiple images. In these
    cases, <function>getimagesize</function> might not be able to properly
    determine the image size. <function>getimagesize</function> will return
    zero for width and height in these cases.
   </para>
  </note>
  <para>
   Index 2 is one of the <constant>IMAGETYPE_<replaceable>*</replaceable></constant> constants indicating
   the type of the image.
  </para>
  <para>
   Index 3 is a text string with the correct 
   <literal>height="yyy" width="xxx"</literal> string that can be used
   directly in an <acronym>IMG</acronym> tag.
  </para>
  <para>
   <literal>mime</literal> is the correspondant MIME type of the image.
   This information can be used to deliver images with the correct HTTP 
   <literal>Content-type</literal> header:
   <example>
    <title><function>getimagesize</function> and MIME types</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> will be 3 for RGB pictures and 4 for CMYK
   pictures.
  </para>
  <para>
   <literal>bits</literal> is the number of bits for each color.
  </para>
  <para>
   For some image types, the presence of <literal>channels</literal> and
   <literal>bits</literal> values can be a bit
   confusing. As an example, <acronym>GIF</acronym> always uses 3 channels
   per pixel, but the number of bits per pixel cannot be calculated for an
   animated <acronym>GIF</acronym> with a global color table.
  </para>
  <para>
   On failure, &false; is returned.
  </para>
 </refsect1>
 
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   If accessing the <parameter>filename</parameter> image is impossible
   <function>getimagesize</function> will generate an error of level
   <constant>E_WARNING</constant>. On read error,
   <function>getimagesize</function> will generate an error of level
   <constant>E_NOTICE</constant>.
  </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>
        Now returns the actual image dimensions, bits and channels of AVIF images;
        previously, the dimensions were reported as <literal>0x0</literal>,
        and bits and channels were not reported at all.
       </entry>
      </row>
      <row>
       <entry>7.1.0</entry>
       <entry>
        Added WebP support.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>getimagesize</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>getimagesize (URL)</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("http://www.example.com/gifs/logo.gif");

// if the file name has space in it, encode it properly
$size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

?>
]]>
    </programlisting>
   </example>
   <example>
    <title>getimagesize() returning 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
-->