<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.get-browser" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>get_browser</refname>
  <refpurpose>Tells what the user's browser is capable of</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>get_browser</methodname>
   <methodparam choice="opt"><type>string</type><parameter>user_agent</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>return_array</parameter><initializer>false</initializer></methodparam>
  </methodsynopsis>
  <para>
   Attempts to determine the capabilities of the user's browser, by looking
   up the browser's information in the <filename>browscap.ini</filename>
   file.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>user_agent</parameter></term>
     <listitem>
      <para>
       The User Agent to be analyzed. By default, the value of HTTP
       User-Agent header is used; however, you can alter this (i.e., look up
       another browser's info) by passing this parameter.
      </para>
      <para>
       You can bypass this parameter with a &null; value.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>return_array</parameter></term>
     <listitem>
      <para>
       If set to &true;, this function will return an <type>array</type>
       instead of an <type>object</type>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The information is returned in an object or an array which will contain
   various data elements representing, for instance, the browser's major and
   minor version numbers and ID string; &true;/&false; values for features
   such as frames, JavaScript, and cookies; and so forth.
  </para>
  <para>
   The <literal>cookies</literal> value simply means that the browser
   itself is capable of accepting cookies and does not mean the user has
   enabled the browser to accept cookies or not. The only way to test if
   cookies are accepted is to set one with <function>setcookie</function>,
   reload, and check for the value.
  </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>4.3.2</entry>
       <entry>
        The optional parameter <parameter>return_array</parameter> was added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Listing all information about the users browser</title>
    <programlisting role="php">
<![CDATA[
<?php
echo $_SERVER['HTTP_USER_AGENT'] . "\n\n";

$browser = get_browser(null, true);
print_r($browser);
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7) Gecko/20040803 Firefox/0.9.3

Array
(
    [browser_name_regex] => ^mozilla/5\.0 (windows; .; windows nt 5\.1; .*rv:.*) gecko/.* firefox/0\.9.*$
    [browser_name_pattern] => Mozilla/5.0 (Windows; ?; Windows NT 5.1; *rv:*) Gecko/* Firefox/0.9*
    [parent] => Firefox 0.9
    [platform] => WinXP
    [browser] => Firefox
    [version] => 0.9
    [majorver] => 0
    [minorver] => 9
    [cssversion] => 2
    [frames] => 1
    [iframes] => 1
    [tables] => 1
    [cookies] => 1
    [backgroundsounds] =>
    [vbscript] =>
    [javascript] => 1
    [javaapplets] => 1
    [activexcontrols] =>
    [cdf] =>
    [aol] =>
    [beta] => 1
    [win16] =>
    [crawler] =>
    [stripper] =>
    [wap] =>
    [netclr] =>
)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    In order for this to work, your <link 
    linkend="ini.browscap">browscap</link> configuration setting in 
    &php.ini; must point to the correct location of the
    <filename>browscap.ini</filename> file on your system.
   </para>
   <para>
    <filename>browscap.ini</filename> is not bundled with PHP, but you may
    find an up-to-date <link 
    xlink:href="&url.browscap.download;">php_browscap.ini</link> file here.
   </para>
   <para>
    While <filename>browscap.ini</filename> contains information on
    many browsers, it relies on user updates to keep the database
    current. The format of the file is fairly self-explanatory.
   </para>
  </note>
 </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
-->