<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.98 $ -->
 <reference id="ref.variables">
  <title>Variable Functions</title>
  <titleabbrev>Variables</titleabbrev>

  <partintro>
   <para>
    For information on how variables behave, see
    the <link linkend="language.variables">Variables</link> entry in 
    the <link linkend="langref">Language Reference</link> section of the manual.
   </para>
  </partintro>

  <refentry id="function.doubleval">
   <refnamediv>
    <refname>doubleval</refname>
    <refpurpose>Alias of <function>floatval</function></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>
     This function is an alias of <function>floatval</function>.
    </para>
    <note>
     <para>
      This alias is a left-over from a function-renaming. In older versions of
      PHP you'll need to use this alias of the <function>floatval</function>
      function, because <function>floatval</function> wasn't yet available in
      that version. 
     </para>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.empty">
   <refnamediv>
    <refname>empty</refname>
    <refpurpose>Determine whether a variable is set</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>empty</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <note>
     <para>
      <function>empty</function> is a language construct.
     </para>
    </note>
    <para>
     This is the opposite of
     <literal>(boolean) <parameter>var</parameter></literal>,
     except that no warning is generated when the variable is not set.
     See <link linkend="language.types.boolean.casting">converting
     to boolean</link> for more information.
    </para>

    <!-- Returns &false; if <parameter>var</parameter> is set and has a
     non-empty or non-zero value; &true; otherwise. -->

     <informalexample>
      <programlisting role="php">
<![CDATA[
$var = 0;

if (empty($var)) {  // evaluates true
    echo '$var is either 0 or not set at all';
}

if (!isset($var)) { // evaluates false
    echo '$var is not set at all';
}
]]>
      </programlisting>
     </informalexample>

    <simpara>
     Note that this is meaningless when used on anything which isn't a
     variable; i.e. <command>empty (addslashes ($name))</command> has
     no meaning since it would be checking whether something which
     isn't a variable is a variable with a &false; value.
     <!-- will even result in parse error (at least in PHP 4) -->
    </simpara>
    <simpara>
     See also <function>isset</function> and
     <function>unset</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.floatval">
   <refnamediv>
    <refname>floatval</refname>
    <refpurpose>Get float value of a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>float</type><methodname>floatval</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns the <type>float</type> value of <parameter>var</parameter>.
    </simpara>
    <para>
     <parameter>Var</parameter> may be any scalar type. You cannot use
     <function>floatval</function> on arrays or objects.
    <informalexample>
      <programlisting role="php">
<![CDATA[
$var = '122.34343The';
$float_value_of_var = floatval ($var);
print $float_value_of_var; // prints 122.34343
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     See also <function>intval</function>,
     <function>strval</function>, <function>settype</function> and
     <link linkend="language.types.type-juggling">Type
     juggling</link>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.gettype">
   <refnamediv>
    <refname>gettype</refname>
    <refpurpose>Get the type of a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>gettype</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the type of the PHP variable
     <parameter>var</parameter>.
    </para>
    <warning>
     <simpara>
      Never use <function>gettype</function> to test for a certain type,
      since the returned string may be subject to change in a future version.
      In addition, it is slow too, as it involves string comparision <!--
      where's my dictionary? -->.
     </simpara>
     <simpara>
      Instead, use the <literal>is_*</literal> functions.
     </simpara>
    </warning>
    <para>
     Possibles values for the returned string are:
     <itemizedlist>
      <listitem>
       <simpara>"<type>boolean</type>" (since PHP 4)</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>integer</type>"</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>double</type>" (for historical reasons "double" is
       returned in case of a <type>float</type>, and not simply
       "float")</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>string</type>"</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>array</type>"</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>object</type>"</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>resource</type>" (since PHP 4)</simpara>
      </listitem>
      <listitem>
       <simpara>"<type>NULL</type>" (since PHP 4)</simpara>
      </listitem>
      <listitem>
       <simpara>"user function" (PHP 3 only, deprecated)</simpara>
      </listitem>
      <listitem>
       <simpara>"unknown type"<!-- someone's joking? --></simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     For PHP 4, you should use <function>function_exists</function> and
     <function>method_exists</function> to replace the prior usage of
     <function>gettype</function> on a function.
    </para>
    <para>
     See also
     <function>settype</function>,
     <function>is_array</function>,
     <function>is_bool</function>,
     <function>is_float</function>,
     <function>is_integer</function>,
     <function>is_null</function>,
     <function>is_numeric</function>,
     <function>is_object</function>,
     <function>is_resource</function>,
     <function>is_scalar</function> and
     <function>is_string</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.get-defined-vars">
   <refnamediv>
    <refname>get_defined_vars</refname>
    <refpurpose>
     Returns an array of all defined variables
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>get_defined_vars</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This function returns an multidimensional array containing a list of
     all defined variables, be them environment, server or user-defined
     variables.
     <informalexample>
      <programlisting role="php">
<![CDATA[
$b = array(1,1,2,3,5,8);

$arr = get_defined_vars();

// print $b
print_r($arr["b"]);

// print path to the PHP interpreter (if used as a CGI)
// e.g. /usr/local/bin/php
echo $arr["_"];

// print the command-line paramaters if any
print_r($arr["argv"]);

// print all the server vars
print_r($arr["HTTP_SERVER_VARS"]);

// print all the available keys for the arrays of variables
print_r(array_keys(get_defined_vars()));
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also <function>get_defined_functions</function> and
     <function>get_defined_constants</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.get-resource-type">
   <refnamediv>
    <refname>get_resource_type</refname>
    <refpurpose>
     Returns the resource type
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>get_resource_type</methodname>
      <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function returns a string representing the type of the 
     <type>resource</type> passed to it. If the paramater is not a 
     valid <type>resource</type>, it
     generates an error.
     <informalexample>
      <programlisting role="php">
<![CDATA[
$c = mysql_connect();
echo get_resource_type($c)."\n";
// prints: mysql link

$fp = fopen("foo","w");
echo get_resource_type($fp)."\n";
// prints: file

$doc = new_xmldoc("1.0");
echo get_resource_type($doc->doc)."\n";
// prints: domxml document
]]>
      </programlisting>
     </informalexample>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.import-request-variables">
   <refnamediv>
    <refname>import_request_variables</refname>
    <refpurpose>Import GET/POST/Cookie variables into the global scope</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>import_request_variables</methodname>
      <methodparam><type>string</type><parameter>types</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>prefix</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Imports GET/POST/Cookie variables into the global scope. It is
     useful if you disabled
     <link linkend="ini.register-globals">register_globals</link>,
     but would like to see some variables in the global scope.
    </simpara>
    <simpara>
     Using the <parameter>types</parameter> parameter, you can
     specify, which request variables to import. You can use
     'G', 'P' and 'C' characters respectively for GET, POST and
     Cookie. These characters are not case sensitive, so you
     can also use any combination of 'g', 'p' and 'c'. POST
     includes the uploaded file informations. Note, that the
     order of the letters matters, as using "gp", the POST
     variables will overwrite GET variables with the same
     name. Any other other letters then GPC are discarded.
    </simpara>
    <note>
     <para>
      Although the <parameter>prefix</parameter> argument is
      optional, you will get a notice level error, if you
      specify no prefix, or specify an empty string as a
      prefix. This is a possible security hazard. Notice
      level errors are not displayed using the default
      error reporting level.
     </para>
    </note>
    <informalexample>
     <programlisting role="php">
<![CDATA[
// This will import GET and POST vars
// with an "rvar_" prefix
import_request_variables("gP", "rvar_");
]]>
     </programlisting>
    </informalexample>
    <simpara>
     See also <link linkend="ini.register-globals">register_globals</link>
     and <link linkend="ini.track-vars">track_vars</link>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.intval">
   <refnamediv>
    <refname>intval</refname>
    <refpurpose>Get integer value of a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>intval</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>base</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns the <type>integer</type> value of <parameter>var</parameter>,
     using the specified base for the conversion (the default is
     base 10).
    </simpara>
    <simpara>
     <parameter>var</parameter> may be any scalar type. You cannot use
     <function>intval</function> on <type>array</type>s or <type>object</type>s.
    </simpara>
    <note>
     <para>
      The <parameter>base</parameter> argument for
      <function>intval</function> has no effect unless the
      <parameter>var</parameter> argument is a string.
     </para>
    </note>
    <simpara>
     See also <function>floatval</function>,
     <function>strval</function>, <function>settype</function> and
     <link linkend="language.types.type-juggling">Type
     juggling</link>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.is-array">
   <refnamediv>
    <refname>is_array</refname>
    <refpurpose>Finds whether a variable is an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_array</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if <parameter>var</parameter> is an <type>array</type>, &false;
     otherwise.
    </para>
    <para>
     See also 
     <function>is_float</function>,
     <function>is_int</function>,
     <function>is_integer</function>,
     <function>is_string</function>, and
     <function>is_object</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-bool">
   <refnamediv>
    <refname>is_bool</refname>
     <refpurpose>
      Finds out whether a variable is a boolean
     </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <methodsynopsis>
       <type>bool</type><methodname>is_bool</methodname>
       <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
     <para>
      Returns &true; if the <parameter>var</parameter> parameter is
      a <type>boolean</type>.
     </para>
     <para>
     See also 
     <function>is_array</function>,
     <function>is_float</function>,
     <function>is_int</function>,
     <function>is_integer</function>,
     <function>is_string</function>, and
     <function>is_object</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-double">
   <refnamediv>
    <refname>is_double</refname>
    <refpurpose>Alias of <function>is_float</function></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>
     This function is an alias of <function>is_float</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-float">
   <refnamediv>
    <refname>is_float</refname>
    <refpurpose>Finds whether a variable is a float</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_float</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns &true; if <parameter>var</parameter> is a <type>float</type>,
     &false; otherwise.
    </simpara>
    <note>
     <para>
      To test if a variable is a number or a numeric string (such as form
      input, which is always a string), you must use
      <function>is_numeric</function>.
     </para>
    </note>
    <simpara>
     See also 
     <function>is_bool</function>,
     <function>is_int</function>,
     <function>is_integer</function>,
     <function>is_numeric</function>,
     <function>is_string</function>,
     <function>is_array</function>, and
     <function>is_object</function>,
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.is-int">
   <refnamediv>
    <refname>is_int</refname>
    <refpurpose>Find whether a variable is an integer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_int</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns &true; if <parameter>var</parameter> is an <type>integer</type>
     &false; otherwise.
    </simpara>
    <note>
     <para>
      To test if a variable is a number or a numeric string (such as form
      input, which is always a string), you must use
      <function>is_numeric</function>.
     </para>
    </note>
    <simpara>
     See also <function>is_bool</function>,
     <function>is_float</function>,
     <function>is_integer</function>,
     <function>is_numeric</function>,
     <function>is_string</function>,
     <function>is_array</function>, and
     <function>is_object</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.is-integer">
   <refnamediv>
    <refname>is_integer</refname>
    <refpurpose>Alias of <function>is_int</function></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>
     This function is an alias of <function>is_int</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-long">
   <refnamediv>
    <refname>is_long</refname>
    <refpurpose>Alias of <function>is_int</function></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>
     This function is an alias of <function>is_int</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-null">
   <refnamediv>
    <refname>is_null</refname>
    <refpurpose>
     Finds whether a variable is &null;
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_null</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if <parameter>var</parameter> is <type>null</type>,
     &false; otherwise.
    </para>
    <para>
     See also <function>is_bool</function>,
     <function>is_numeric</function>,
     <function>is_float</function>,
     <function>is_int</function>,
     <function>is_string</function>,
     <function>is_object</function>,
     <function>is_array</function>, and
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.is-numeric">
   <refnamediv>
    <refname>is_numeric</refname>
    <refpurpose>
     Finds whether a variable is a number or a numeric string
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_numeric</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if <parameter>var</parameter> is a number or a
     numeric string, &false; otherwise.
    </para>
    <para>
     See also <function>is_bool</function>,
     <function>is_float</function>,
     <function>is_int</function>,
     <function>is_string</function>,
     <function>is_object</function>,
     <function>is_array</function>, and
     <function>is_integer</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-object">
   <refnamediv>
    <refname>is_object</refname>
    <refpurpose>Finds whether a variable is an object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_object</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if <parameter>var</parameter> is an <type>object</type>, 
     &false; otherwise.
    </para>
    <para>
     See also <function>is_bool</function>,
     <function>is_int</function>,
     <function>is_integer</function>,
     <function>is_float</function>,
     <function>is_string</function>, and
     <function>is_array</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-real">
   <refnamediv>
    <refname>is_real</refname>
    <refpurpose>Alias of <function>is_float</function></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>
     This function is an alias of <function>is_float</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-resource">
   <refnamediv>
    <refname>is_resource</refname>
    <refpurpose>
     Finds whether a variable is a resource
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_resource</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>is_resource</function> returns &true; if the variable
     given by the <parameter>var</parameter> parameter is a 
     <type>resource</type>, otherwise it returns &false;.
    </para>
    <para>
     See the documentation on the <type>resource</type>-type for
     more information.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-scalar">
   <refnamediv>
    <refname>is_scalar</refname>
    <refpurpose>
     Finds whether a variable is a scalar
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_scalar</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>is_scalar</function> returns &true; if the variable
     given by the <parameter>var</parameter> parameter is a scalar,
     otherwise it returns &false;.
    </para>
    <para>
     Scalar variables are those containing an <type>integer</type>, 
     <type>float</type>, <type>string</type> or <type>boolean</type>.  
     Types <type>array</type>, <type>object</type> and <type>resource</type> 
     or not scalar.
     <informalexample>
      <programlisting role="php">
<!-- TODO: better example, this one can be quite misleading for unexperienced
           programmers.  -->
<![CDATA[
function show_var($var) {
    if (is_scalar($var)) {
        echo $var;
    } else {
        var_dump($var);
    }
}
$pi = 3.1416;
$proteins = array("hemoglobin", "cytochrome c oxidase", "ferredoxin");

show_var($pi);
// prints: 3.1416

show_var($proteins)
// prints:
// array(3) {
//   [0]=>
//   string(10) "hemoglobin"
//   [1]=>
//   string(20) "cytochrome c oxidase"
//   [2]=>
//   string(10) "ferredoxin"
// }
]]>
      </programlisting>
     </informalexample>
    </para>
    <note>
     <para>
      <function>is_scalar</function> does not consider <type>resource</type>
      type values to be scalar as resources are abstract datatypes 
      which are currently based on integers. This implementation detail should 
      not be relied upon, as it may change.
     </para>
    </note>
    <para>
     See also <function>is_bool</function>,
     <function>is_numeric</function>,
     <function>is_float</function>,
     <function>is_int</function>,
     <function>is_real</function>,
     <function>is_string</function>,
     <function>is_object</function>,
     <function>is_array</function>, and
     <function>is_integer</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.is-string">
   <refnamediv>
    <refname>is_string</refname>
    <refpurpose>Finds whether a variable is a string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_string</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if <parameter>var</parameter> is a <type>string</type>,
     &false; otherwise.
    </para>
    <para>
     See also <function>is_bool</function>,
     <function>is_int</function>,
     <function>is_integer</function>,
     <function>is_float</function>,
     <function>is_real</function>,
     <function>is_object</function>, and
     <function>is_array</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.isset">
   <refnamediv>
    <refname>isset</refname>
    <refpurpose>Determine whether a variable is set</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>isset</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns &true; if <parameter>var</parameter>
     exists; &false; otherwise.
    </simpara>
    <para>
     If a variable has been unset with <function>unset</function>,
     it will no longer be <function>isset</function>. <function>isset</function>
     will return &false; if testing a variable that has been
     set to &null;. Also note that a &null; byte (<literal>"\0"</literal>)
     is not equivalent to the PHP &null; constant.
     <informalexample>
      <programlisting role="php">
<![CDATA[
$a = "test";
$b = "anothertest";

echo isset ($a); // TRUE
echo isset ($a, $b) //TRUE

unset ($a);
echo isset ($a); // FALSE
echo isset ($a, $b); //FALSE

$foo = NULL;
print isset ($foo); // FALSE


]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     See also <function>empty</function> and
     <function>unset</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.print-r">
   <refnamediv>
    <refname>print_r</refname>
    <refpurpose>
     Prints human-readable information about a variable
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>print_r</methodname>
      <methodparam><type>mixed</type><parameter>expression</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>print_r</function> displays information about a variable
     in a way that's readable by humans.  If given a <type>string</type>,
     <type>integer</type> or <type>float</type>, the value itself will be
     printed.  If given an <type>array</type>,
     values will be presented in a format that shows keys and
     elements.  Similar notation is used for <type>object</type>s.
    </simpara>
    <simpara>
     Remember that <function>print_r</function> will move the array
     pointer to the end. Use <function>reset</function> to bring
     it back to beginning.
    </simpara>
     &tip.ob-capture;
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<pre>
<?php
    $a = array ('a' => 'apple', 'b' => 'banana', 'c' => array ('x','y','z'));
    print_r ($a);
?>
</pre>
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     Which will output:
     <screen>
<![CDATA[
<pre>
Array
(
    [a] => apple
    [b] => banana
    [c] => Array
        (
            [0] => x
            [1] => y
            [2] => z
        )
)
</pre>
]]>
      </screen>
     </para>
    <note>
     <simpara>
      Prior to PHP 4.0.4, <function>print_r</function> will continue forever
      if given an <type>array</type> or <type>object</type> that
      contains a direct or indirect reference to itself.  An example
      is <literal>print_r($GLOBALS)</literal> because
      <literal>$GLOBALS</literal> is itself a global variable that
      contains a reference to itself.
     </simpara>
    </note>
    <simpara>
      See also <function>ob_start</function>, <function>var_dump</function>,
      and <function>var_export</function>.
    </simpara>

   </refsect1>
  </refentry>

  <refentry id="function.serialize">
   <refnamediv>
    <refname>serialize</refname>
    <refpurpose>
     Generates a storable representation of a value
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>serialize</methodname>
      <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>serialize</function> returns a string containing a
     byte-stream representation of <parameter>value</parameter> that
     can be stored anywhere.
    </simpara>
    <simpara>
     This is useful for storing or passing PHP values around without
     losing their type and structure.
    </simpara>
   <simpara>
    To make the serialized string into a PHP value again, use
    <function>unserialize</function>.  <function>serialize</function>
    handles all types, except the <type>resource</type>-type.
    You can even <function>serialize</function> arrays that contain
    references to itself. References inside the array/object you 
    are <function>serialize</function>ing will also be stored.
   </simpara>
   <!-- TODO
        in 4.0.4pl1 this didn't work properly, however, there
        been some fixes. I don't know whether this all
        works correctly now, and if so, whether it is since 405
        or 406
   <note>
    <simpara>
     This didn't work correctly until 4.0.?
    </simpara>
   </note>
   </simpara>
   -->
   <note>
    <para>
     In PHP 3, object properties will be serialized, but methods are
     lost.  PHP 4 removes that limitation and restores both properties
     and methods.  Please see the <link
     linkend="language.oop.serialization">Serializing Objects</link>
     section of <link linkend="language.oop">Classes and
     Objects</link> for more information.
    </para>
   </note>
    <para>
     <example>
      <title><function>serialize</function> example</title>
      <programlisting role="php">
<![CDATA[
// $session_data contains a multi-dimensional array with session
// information for the current user.  We use serialize() to store
// it in a database at the end of the request.

$conn = odbc_connect ("webdb", "php", "chicken");
$stmt = odbc_prepare ($conn,
      "UPDATE sessions SET data = ? WHERE id = ?");
$sqldata = array (serialize($session_data), $PHP_AUTH_USER);
if (!odbc_execute ($stmt, &$sqldata)) {
    $stmt = odbc_prepare($conn,
     "INSERT INTO sessions (id, data) VALUES(?, ?)");
    if (!odbc_execute($stmt, &$sqldata)) {
    /* Something went wrong.  Bitch, whine and moan. */
    }
}
]]>
      </programlisting>
     </example>
    </para>
   <para>
    See Also: <function>unserialize</function>.
   </para>
   </refsect1>
  </refentry>

  <refentry id="function.settype">
   <refnamediv>
    <refname>settype</refname>
    <refpurpose>Set the type of a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>settype</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam><type>string</type><parameter>type</parameter></methodparam>
     </methodsynopsis>
    <para>
     Set the type of variable <parameter>var</parameter> to
     <parameter>type</parameter>.
    </para>
    <para>
     Possibles values of <parameter>type</parameter> are:
     <itemizedlist>
      <listitem>
       <simpara>
        "boolean" (or, since PHP 4.2.0, "bool")
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "integer" (or, since PHP 4.2.0, "int")
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "float" (only possible since PHP 4.2.0, for older versions use the
        deprecated variant "double")
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "string"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "array"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "object"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "null" (since PHP 4.0.8)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Returns &true; if successful; otherwise returns
     &false;.
    </para>
    <para>
     <example>
      <title><function>settype</function> example</title>
      <programlisting role="php">
<![CDATA[
$foo = "5bar"; // string
$bar = true;   // boolean

settype($foo, "integer"); // $foo is now 5   (integer)
settype($bar, "string");  // $bar is now "1" (string)
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>gettype</function>,
     <link linkend="language.types.typecasting">type-casting</link> and
     <link linkend="language.types.type-juggling">type-juggling</link>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.strval">
   <refnamediv>
    <refname>strval</refname>
    <refpurpose>Get string value of a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>strval</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns the <type>string</type> value of <parameter>var</parameter>.
     See the documentation on <type>string</type> for more information
     on converting to string.
    </simpara>
    <simpara>
     <parameter>var</parameter> may be any scalar type. You cannot use
     <function>strval</function> on arrays or objects.
    </simpara>
    <simpara>
     See also <function>floatval</function>,
     <function>intval</function>, <function>settype</function> and
     <link linkend="language.types.type-juggling">Type
     juggling</link>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.unserialize">
   <refnamediv>
    <refname>unserialize</refname>
    <refpurpose>
     Creates a PHP value from a stored representation
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>unserialize</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>unserialize</function> takes a single serialized
     variable (see <function>serialize</function>) and converts it
     back into a PHP value.  The converted value is returned, and can
     be an <type>integer</type>, <type>float</type>,
     <type>string</type>, <type>array</type> or <type>object</type>.
     If an object was serialized, its methods are not preserved in the
     returned value.
    </simpara>
    <note>
     <para>
      It's possible to set a callback-function which will be called,
      if an undefined class should be instanciated during unserializing.
      (to prevent getting an incomplete <type>object</type> "__PHP_Incomplete_Class".)
      Use your php.ini, <function>ini_set</function> or .htaccess-file 
       to define 'unserialize_callback_func'. 
      Everytime an undefined class should be instanciated, it'll be called. 
      To disable this feature just empty this global variable.
     </para>
    </note>
    <para>
     <example>
      <title>unserialize_callback_func example</title>
      <programlisting role="php">
<![CDATA[
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';

ini_set('unserialize_callback_func','mycallback'); // set your callback_function

function mycallback($classname) {
    // just include a file containing your classdefinition
    // you get $classname to figure out which classdefinition is required
}
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      In PHP 3, methods are not preserved when unserializing a
      serialized object. PHP 4 removes that limitation and restores
      both properties and methods.  Please see the <link
      linkend="language.oop.serialization">Serializing Objects</link>
      section of <link linkend="language.oop">Classes and
      Objects</link> or more information.
     </para>
    </note>
    <para>
     <example>
      <title><function>unserialize</function> example</title>
      <programlisting role="php">
<![CDATA[
// Here, we use unserialize() to load session data from a database
// into $session_data.    This example complements the one described
// with <function>serialize</function>.

$conn = odbc_connect ("webdb", "php", "chicken");
$stmt = odbc_prepare ($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array ($PHP_AUTH_USER);
if (!odbc_execute ($stmt, &$sqldata) || !odbc_fetch_into ($stmt, &$tmp)) {
    // if the execute or fetch fails, initialize to empty array
    $session_data = array();
} else {
    // we should now have the serialized data in $tmp[0].
    $session_data = unserialize ($tmp[0]);
    if (!is_array ($session_data)) {
    // something went wrong, initialize to empty array
    $session_data = array();
    }
}
]]>
      </programlisting>
     </example>
    </para>
   <para>
    See Also: <function>serialize</function>.
   </para>
   </refsect1>
  </refentry>

  <refentry id="function.unset">
   <refnamediv>
    <refname>unset</refname>
    <refpurpose>Unset a given variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>unset</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>unset</function> destroys the specified variables. Note
     that in PHP 3, <function>unset</function> will always return &true;
     (actually, the integer value 1). In PHP 4, however,
     <function>unset</function> is no longer a true function: it is
     now a statement. As such no value is returned, and attempting to
     take the value of <function>unset</function> results in a parse
     error.
    </para>
    <para>
     <example>
      <title><function>unset</function> example</title>
      <programlisting role="php">
<![CDATA[
// destroy a single variable
unset ($foo);

// destroy a single element of an array
unset ($bar['quux']);

// destroy more than one variable
unset ($foo1, $foo2, $foo3);
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The behavior of <function>unset</function> inside of a function
     can vary depending on what type of variable you are attempting to
     destroy.
    </para>
    <para>
     If a globalized variable is <function>unset</function> inside of
     a function, only the local variable is destroyed.  The variable
     in the calling environment will retain the same value as before
     <function>unset</function> was called.
     <informalexample>
      <programlisting role="php">
<![CDATA[
function destroy_foo() {
    global $foo;
    unset($foo);
}

$foo = 'bar';
destroy_foo();
echo $foo;
]]>
      </programlisting>
     </informalexample>
     The above example would output:
     <informalexample>
      <screen>
<![CDATA[
bar
]]>
      </screen>
     </informalexample>
    </para>
    <para>
     If a variable that is PASSED BY REFERENCE is
     <function>unset</function> inside of a function, only the local
     variable is destroyed.  The variable in the calling environment
     will retain the same value as before <function>unset</function>
     was called.
     <informalexample>
      <programlisting role="php">
<![CDATA[
function foo(&$bar) {
    unset($bar);
    $bar = "blah";
}

$bar = 'something';
echo "$bar\n";

foo($bar);
echo "$bar\n";
]]>
      </programlisting>
     </informalexample>
     The above example would output:
     <informalexample>
      <screen>
<![CDATA[
something
something
]]>
      </screen>
     </informalexample>
    </para>
    <para>
     If a static variable is <function>unset</function> inside of a
     function, <function>unset</function> destroyes the variable and all 
     its references.
     <informalexample>
      <programlisting role="php">
<![CDATA[
function foo() {
    static $a;
    $a++;
       echo "$a\n";

    unset($a);
}

foo();
foo();
foo();
]]>
      </programlisting>
     </informalexample>
     The above example would output:
     <informalexample>
      <screen>
<![CDATA[
1
2
3
]]>
      </screen>
     </informalexample>
    </para>
    <para>
     If you would like to <function>unset</function> a global variable inside of a function, you can use the <parameter>$GLOBALS</parameter> array to do so:
     <informalexample>
      <programlisting role="php">
<![CDATA[
function foo() {
    unset($GLOBALS['bar']);
}

$bar = "something";
foo();
]]>
      </programlisting>
     </informalexample>
    </para>
    <note>
     <para>
      <function>unset</function> is a language construct.
     </para>
    </note>
    <para>
     See also <function>isset</function> and
     <function>empty</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.var-dump">
   <refnamediv>
    <refname>var_dump</refname>
    <refpurpose>Dumps information about a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>var_dump</methodname>
      <methodparam><type>mixed</type><parameter>expression</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>expression</parameter></methodparam>
      <methodparam choice="opt"><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     This function returns structured information about one or more expressions
     that includes its type and value.  Arrays are explored
     recursively with values indented to show structure.
    </simpara>
    &tip.ob-capture;
    <simpara>
     Compare <function>var_dump</function> to
     <function>print_r</function>.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<pre>
<?php
$a = array (1, 2, array ("a", "b", "c"));
var_dump ($a);

/* output:
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  array(3) {
    [0]=>
    string(1) "a"
    [1]=>
    string(1) "b"
    [2]=>
    string(1) "c"
  }
}

*/

$b = 3.1; $c = TRUE;
var_dump($b,$c);

/* output:
float(3.1)
bool(true)

*/
?>;
</pre>
]]>
      </programlisting>
     </informalexample>
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.var-export">
   <refnamediv>
    <refname>var_export</refname>
    <refpurpose>Outputs or returns a string representation of avariable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>var_export</methodname>
      <methodparam><type>mixed</type><parameter>expression</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>return</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     This function returns structured information about the variable that is
     passed to this function. It is similar to <function>var_dump</function>
     with the exception that the returned representation is valid PHP code.
    </simpara>
    <simpara>
     You can also return the variable representation by using &true; as
     second parameter to this function.
    </simpara>
    <simpara>
     Compare <function>var_export</function> to
     <function>var_dump</function>.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<pre>
<?php
$a = array (1, 2, array ("a", "b", "c"));
var_export ($a);

/* output:
array (
  0 => 1,
  1 => 2,
  2 => 
  array (
    0 => 'a',
    1 => 'b',
    2 => 'c',
  ),
)
*/

$b = 3.1;
$v = var_export($b, TRUE);
echo $v;

/* output:
3.1
*/
?>
</pre>
]]>
      </programlisting>
     </informalexample>
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.is-callable'>
   <refnamediv>
    <refname>is_callable</refname>
    <refpurpose>
     Find out whether the argument is a valid callable construct
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>is_callable</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>syntax_only</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>callable_name</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>
  

 </reference>

<!-- 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
-->