<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.38 $ -->
<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>array</type><methodname>getimagesize</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">imageinfo</parameter></methodparam>
  </methodsynopsis>
  <para>
   The <function>getimagesize</function> function will determine the
   size of any given image file and return the dimensions along with
   the file type and a height/width text string to be used inside a
   normal <acronym>HTML</acronym> <tag>IMG</tag> tag and the
   correspondant <acronym>HTTP</acronym> content type.
  </para>
  <para>
   <function>getimagesize</function> can also return some more information
   in <parameter>imageinfo</parameter> parameter.
  </para>
  <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 multiple JPEG 2000 codestreams. 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 retreived from the icon with the highest
    bitrate.
   </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 supported streams. 
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>imageinfo</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>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array with 7 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 <literal>IMAGETYPE_XXX</literal> 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 IMG tag.
  </para>
  <para>
   <literal>mime</literal> is the correspondant MIME type of the image.
   This information can be used to deliver images with correct the HTTP 
   <literal>Content-type</literal> header:
   <example>
    <title>getimagesize() 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, or
   if it isn't a valid picture, <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>5.3.0</entry>
       <entry>
        Added icon support.
       </entry>
      </row>
      <row>
       <entry>5.2.3</entry>
       <entry>
        Read errors generated by this function downgraded to
        <constant>E_NOTICE</constant> from <constant>E_WARNING</constant>.
       </entry>
      </row>
      <row>
       <entry>4.3.2</entry>
       <entry>
        Support for <acronym>JPC</acronym>, <acronym>JP2</acronym>,
        <acronym>JPX</acronym>, <acronym>JB2</acronym>, 
        <acronym>XBM</acronym>, and <acronym>WBMP</acronym> became available.
       </entry>
      </row>
      <row>
       <entry>4.3.2</entry>
       <entry>
        JPEG 2000 support was added for the <parameter>imageinfo</parameter>
        parameter.
       </entry>
      </row>
      <row>
       <entry>4.3.0</entry>
       <entry>
        <literal>bits</literal> and <literal>channels</literal> are present
        for other image types, too.
       </entry>
      </row>
      <row>
       <entry>4.3.0</entry>
       <entry>
        <literal>mime</literal> was added.
       </entry>
      </row>
      <row>
       <entry>4.3.0</entry>
       <entry>
        Support for <acronym>SWC</acronym> was added.
       </entry>
      </row>
      <row>
       <entry>4.2.0</entry>
       <entry>
        Support for <acronym>TIFF</acronym> was added.
       </entry>
      </row>
      <row>
       <entry>4.0.5</entry>
       <entry>
        URL support was added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>getimagesize (file)</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>
   <para>
    The <function>getimagesize</function> function does not require the GD
    image library.
   </para>
  </note>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <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>
   </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:"../../../../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
-->