<reference id="ref.misc">
<title>Miscellaneous functions</title>
<titleabbrev>Misc.</titleabbrev>
<partintro>
<para>
These functions were placed here because none of the other
categories seemed to fit.
</partintro>
<refentry id="function.connection-aborted">
<refnamediv>
<refname>connection_aborted</refname>
<refpurpose>Return true if client disconnected</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>connection_aborted</function></funcdef>
<paramdef>void <parameter></parameter></paramdef>
</funcsynopsis>
<simpara>
Returns true if client disconnected. See the Connection Handling
description in the Feature chapter for a complete explanation.
</simpara>
</refsect1>
</refentry>
<refentry id="function.connection-status">
<refnamediv>
<refname>connection_status</refname>
<refpurpose>Returns connection status bitfield</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>connection_status</function></funcdef>
<paramdef>void <parameter></parameter></paramdef>
</funcsynopsis>
<simpara>
Returns the connection status bitfield. See the Connection
Handling description in the Feature chapter for a complete
explanation.
</simpara>
</refsect1>
</refentry>
<refentry id="function.connection-timeout">
<refnamediv>
<refname>connection_timeout</refname>
<refpurpose>Return true if script timed out</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>connection_timeout</function></funcdef>
<paramdef>void <parameter></parameter></paramdef>
</funcsynopsis>
<simpara>
Returns true if script timed out. See the Connection Handling
description in the Feature chapter for a complete explanation.
</simpara>
</refsect1>
</refentry>
<refentry id="function.eval">
<refnamediv>
<refname>eval</refname>
<refpurpose>Evaluate a string as PHP code</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>eval</function></funcdef>
<paramdef>string <parameter>code_str</parameter></paramdef>
</funcsynopsis>
<simpara>
<function>eval</function> evaluates the string given in
<parameter>code_str</parameter> as PHP code. Among other things,
this can be useful for storing code in a database text field for
later execution.
<simpara>
There are some factors to keep in mind when using
<function>eval</function>. Remember that the string passed must
be valid PHP code, including things like terminating statements
with a semicolon so the parser doesn't die on the line after the
<function>eval</function>, and properly escaping things in
<parameter>code_str</parameter>.
<simpara>
Also remember that variables given values under
<function>eval</function> will retain these values in the main
script afterwards.
<para>
<example>
<title>eval() example - simple text merge</title>
<programlisting>
<?php
$string = 'cup';
$name = 'coffee';
$str = 'This is a $string with my $name in it.<br>';
echo $str;
eval( "\$str = \"$str\";" );
echo $str;
?>
</programlisting>
</example>
<para>
The above example will show:
<programlisting>
This is a $string with my $name in it.
This is a cup with my coffee in it.
</programlisting>
</refsect1>
</refentry>
<refentry id="function.extract">
<refnamediv>
<refname>extract</refname>
<refpurpose>Import variables into the symbol table from an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>extract</function></funcdef>
<paramdef>array <parameter>var_array</parameter></paramdef>
<paramdef>int <parameter><optional>extract_type</optional></parameter></paramdef>
<paramdef>string <parameter><optional>prefix</optional></parameter></paramdef>
</funcsynopsis>
<para>
This function is used to import variables from an array into the
current symbol table. It takes associative array
<parameter>var_array</parameter> and treats keys as variable
names and values as variable values. For each key/value pair it
will create a variable in the current symbol table, subject to
<parameter>extract_type</parameter> and
<parameter>prefix</parameter> parameters.
<para>
<function>extract</function> checks for colissions with existing variables.
The way collisions are treated is determined by
<parameter>extract_type</parameter>. It can be one of the
following values:
<variablelist>
<varlistentry>
<term>EXTR_OVERWRITE</term>
<listitem>
<simpara>If there is a collision, overwrite the existing variable.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_SKIP</term>
<listitem>
<simpara>If there is a collision, don't overwrite the existing variable.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_PREFIX_SAME</term>
<listitem>
<simpara>If there is a collision, prefix the new variable with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_PREFIX_ALL</term>
<listitem>
<simpara>Prefix all variables with <parameter>prefix</parameter>.</simpara>
</listitem>
</varlistentry>
</variablelist>
<para>
If <parameter>extract_type</parameter> is not specified,
it is assumed to be EXTR_OVERWRITE.
<para>
Note that <parameter>prefix</parameter> is only required if
<parameter>extract_type</parameter> is EXTR_PREFIX_SAME or
EXTR_PREFIX_ALL.
<para>
<function>extract</function> checks each key to see if it
constitues a valid variable name, and if it does only then does
it proceed to import it.
<para>
A possible use for extract is to import into symbol table
variables contained in an associative array returned by
<function>wddx_deserialize</function>.
<para>
<example>
<title>extract example</title>
<programlisting>
<?
/* Suppose that $var_array is an array returned from
wddx_deserialize */
$size = "large";
$var_array = array("color" => "blue",
"size" => "medium",
"shape" => "sphere");
extract($var_array, EXTR_PREFIX_SAME, "wddx");
print "$color, $size, $shape, $wddx_size\n";
?>
</programlisting>
</example>
<para>
The above example will produce:
<programlisting>
blue, large, sphere, medium
</programlisting>
<para>
The $size wasn't overwritten, becaus we specified
EXTR_PREFIX_SAME, which resulted in $wddx_size being created.
If EXTR_SKIP was specified, then $wddx_size wouldn't even have
been created. EXTR_OVERWRITE would have cause $size to have
value "medium", and EXTR_PREFIX_ALL would result in new
variables being named $wddx_color, $wddx_size, and $wddx_shape.
</refsect1>
</refentry>
<refentry id="function.die">
<refnamediv>
<refname>die</refname>
<refpurpose>Output a message and terminate the current script</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>die</function></funcdef>
<paramdef>string <parameter>message</parameter></paramdef>
</funcsynopsis>
<simpara>
This language construct outputs a message and terminates parsing
of the script. It does not return.
<para>
<example>
<title>die example</title>
<programlisting>
<?php
$filename = '/path/to/data-file';
$file = fopen($filename, 'r')
or die "unable to open file ($filename)";
?>
</programlisting>
</example>
</refsect1>
</refentry>
<refentry id="function.exit">
<refnamediv>
<refname>exit</refname>
<refpurpose>Terminate current script</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>exit</function></funcdef>
<void>
</funcsynopsis>
<simpara>
This language construct terminates parsing of the script. It
does not return.
</refsect1>
</refentry>
<refentry id="function.function-exists">
<refnamediv>
<refname>function_exists</refname>
<refpurpose>Return true if the given function has been defined</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>function_exists</function></funcdef>
<paramdef>string <parameter>function_name</parameter></paramdef>
</funcsynopsis>
<simpara>
Checks the list of defined functions for <parameter>function_name</parameter>.
Returns true if the given function name was found, false otherwise.
</simpara>
</refsect1>
</refentry>
<refentry id="function.ignore-user-abort">
<refnamediv>
<refname>ignore_user_abort</refname>
<refpurpose>Set whether a client disconnect should abort script execution</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>ignore_user_abort</function></funcdef>
<paramdef>int <parameter><optional>setting</optional></parameter></paramdef>
</funcsynopsis>
<simpara>
This function sets whether a client disconnect should cause a
script to be aborted. It will return the previous setting and
can be called without an argument to not change the current
setting and only return the current setting. See the Connection
Handling section in the Features chapter for a complete
description of connection handling in PHP.
</simpara>
</refsect1>
</refentry>
<refentry id="function.iptcparse">
<refnamediv>
<refname>iptcparse</refname>
<refpurpose>Parse a binary IPTC <ulink url="http://www.xe.net/iptc/">
http://www.xe.net/iptc/</ulink> block into single tags.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>array <function>iptcparse</function></funcdef>
<paramdef>string <parameter>iptcblock</parameter></paramdef>
</funcsynopsis>
<simpara>
This function parses a binary IPTC block into its single tags. It
returns an array using the tagmarker as an index and the value as
the value. It returns false on error or if no IPTC data was
found. See <function>GetImageSize</function> for a sample.
</refsect1>
</refentry>
<refentry id="function.leak">
<refnamediv>
<refname>leak</refname>
<refpurpose>Leak memory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>leak</function></funcdef>
<paramdef>int <parameter>bytes</parameter></paramdef>
</funcsynopsis>
<simpara>
<function>Leak</function> leaks the specified amount of memory.
<simpara>
This is useful when debugging the memory manager, which automatically
cleans up "leaked" memory when each request is completed.
</refsect1>
</refentry>
<refentry id="function.pack">
<refnamediv>
<refname>pack</refname>
<refpurpose>pack data into binary string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>string <function>pack</function></funcdef>
<paramdef>string <parameter>format</parameter></paramdef>
<paramdef>mixed <parameter><optional>args</optional></parameter>...</paramdef>
</funcsynopsis>
<para>
Pack given arguments into binary string according to
<parameter>format</parameter>. Returns binary string containing data.
<para>
The idea to this function was taken from Perl and all formatting
codes work the same as there. The format string consists of
format codes followed by an optional repeater argument. The
repeater argument can be either an integer value or * for
repeating to the end of the input data. For a, A, h, H the repeat
count specifies how many characters of one data argument are
taken, for @ it is the absolute position where to put the next
data, for everything else the repeat count specifies how many
data arguments are consumed and packed into the resulting binary
string. Currently implemented are
<itemizedlist>
<listitem><simpara>a NUL-padded string</simpara></listitem>
<listitem><simpara>A SPACE-padded string</simpara></listitem>
<listitem><simpara>h Hex string, low nibble first</simpara></listitem>
<listitem><simpara>H Hex string, high nibble first</simpara></listitem>
<listitem><simpara>c signed char</simpara></listitem>
<listitem><simpara>C unsigned char</simpara></listitem>
<listitem><simpara>s signed short (always 16 bit, machine byte order)</simpara></listitem>
<listitem><simpara>S unsigned short (always 16 bit, machine byte order)</simpara></listitem>
<listitem><simpara>n unsigned short (always 16 bit, big endian
byte order)</simpara></listitem>
<listitem><simpara>v unsigned short (always 16 bit, little
endian byte order)</simpara></listitem>
<listitem><simpara>i signed integer (machine dependant size and
byte order)</simpara></listitem>
<listitem><simpara>I unsigned integer (machine dependant size
and byte order)</simpara></listitem>
<listitem><simpara>l signed long (always 32 bit, machine byte order)</simpara></listitem>
<listitem><simpara>L unsigned long (always 32 bit, machine byte order)</simpara></listitem>
<listitem><simpara>N unsigned long (always 32 bit, big endian
byte order)</simpara></listitem>
<listitem><simpara>V unsigned long (always 32 bit, little endian
byte order)</simpara></listitem>
<listitem><simpara>f float (machine dependent size and representation)</simpara></listitem>
<listitem><simpara>d double (machine dependent size and representation)</simpara></listitem>
<listitem><simpara>x NUL byte</simpara></listitem>
<listitem><simpara>X Back up one byte</simpara></listitem>
<listitem><simpara>@ NUL-fill to absolute position</simpara></listitem>
</itemizedlist>
<example>
<title>pack format string</title>
<programlisting role=php>
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
</programlisting>
<para>
The resulting binary string will be 6 bytes long and contain
the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
</example>
<para>
Note that the distinction between signed and unsigned values only
affects the function <function>unpack</function>, where as
function <function>pack</function> gives the same result for
signed and unsigned format codes.
<para>
Also note that PHP internally stores integral values as signed
values of a machine dependant size. If you give it an unsigned
integral value too large to be stored that way it is converted to
a double which often yields an undesired result.
</refsect1>
</refentry>
<refentry id="function.register-shutdown-function">
<refnamediv>
<refname>register_shutdown_function</refname>
<refpurpose>Register a function for execution on shutdown.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>register_shutdown_function</function></funcdef>
<paramdef>string <parameter>func</parameter></paramdef>
</funcsynopsis>
<simpara>
Registers the function named by <parameter>func</parameter> to be
executed when script processing is complete.
<para>
Common Pitfalls:
<simpara>
Since no output is allowed to the browser in this function, you will be
unable to debug it using statements such as print or echo.
</refsect1>
</refentry>
<refentry id="function.serialize">
<refnamediv>
<refname>serialize</refname>
<refpurpose>generates a storable representation of a value</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>string <function>serialize</function></funcdef>
<paramdef>mixed <parameter>value</parameter></paramdef>
</funcsynopsis>
<simpara>
<function>serialize</function> returns a string containing a
byte-stream representation of <parameter>value</parameter> that
can be stored anywhere.
<simpara>
This is useful for storing or passing PHP values around without
losing their type and structure.
<simpara>
To make the serialized string into a PHP value again, use
<function>unserialize</function>. <function>serialize</function>
handles the types <type>integer</type>, <type>double</type>,
<type>string</type>, <type>array</type> (multidimensional) and
<type>object</type> (object properties will be serialized, but
methods are lost).
<para>
<example>
<title>serialize example</title>
<programlisting role=php>
// $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>
</refsect1>
</refentry>
<refentry id="function.sleep">
<refnamediv>
<refname>sleep</refname>
<refpurpose>Delay execution</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>sleep</function></funcdef>
<paramdef>int <parameter>seconds</parameter></paramdef>
</funcsynopsis>
<simpara>
The sleep function delays program execution for the given number
of <parameter>seconds</parameter>.
<simpara>
See also <function>usleep</function>.
</refsect1>
</refentry>
<refentry id="function.unpack">
<refnamediv>
<refname>unpack</refname>
<refpurpose>unpack data from binary string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>array <function>unpack</function></funcdef>
<paramdef>string <parameter>format</parameter></paramdef>
<paramdef>string <parameter>data</parameter></paramdef>
</funcsynopsis>
<para>
Unpack from binary string into array according to
<parameter>format</parameter>. Returns array containing unpacked
elements of binary string.
<para>
Unpack works slightly different from Perl as the unpacked data is
stored in an associative array. To accomplish this you have to
name the different format codes and separate them by a slash /.
<example>
<title>unpack format string</title>
<programlisting role=php>
$array = unpack("c2chars/nint", $binarydata);
</programlisting>
<para>
The resulting array will contain the entries "chars1",
"chars2" and "int".
</example>
<para>
For an explanation of the format codes see also:
<function>pack</function>
<para>
Note that PHP internally stores integral values as signed. If you
unpack a large unsigned long and it is of the same size as PHP
internally stored values the result will be a negative number
even though unsigned unpacking was specified.
</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>
<funcsynopsis>
<funcdef>mixed <function>unserialize</function></funcdef>
<paramdef>string <parameter>str</parameter></paramdef>
</funcsynopsis>
<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>double</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.
<para>
<example>
<title>unserialize example</title>
<programlisting role=php>
// 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>
</refsect1>
</refentry>
<refentry id="function.uniqid">
<refnamediv>
<refname>uniqid</refname>
<refpurpose>generate a unique id</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>uniqid</function></funcdef>
<paramdef>string <parameter>prefix</parameter></paramdef>
</funcsynopsis>
<simpara>
<function>uniqid</function> returns a prefixed unique identifier
based on current time in microseconds. The prefix can be useful
for instance if you generate identifiers simultaneously on
several hosts that might happen to generate the identifier at the
same microsecond. The prefix can be up to 114 characters long.
<para>
If you need a unique identifier or token and you intend to give
out that token to the user via the network (i.e. session cookies),
it is recommended that you use something along the lines of
<informalexample><programlisting>
$token = md5(uniqid("")); // no random portion
$better_token = md5(uniqid(rand())); // better, difficult to guess
</programlisting></informalexample>
<simpara>
This will create a 32 character identifier (a 128 bit hex number)
that is extremely difficult to predict.
</refsect1>
</refentry>
<refentry id="function.usleep">
<refnamediv>
<refname>usleep</refname>
<refpurpose>Delay execution in microseconds</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>void <function>usleep</function></funcdef>
<paramdef>int <parameter>micro_seconds</parameter></paramdef>
</funcsynopsis>
<simpara>
The sleep function delays program execution for the given number
of <parameter>micro_seconds</parameter>.
<simpara>
See also <function>sleep</function>.
</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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->