php-doc-en/pear/pear.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
 <reference id="pear.reference">

  <title>PEAR Reference Manual</title>
  <titleabbrev>PEAR</titleabbrev>
  <partintro>
   <simpara>
    This chapter contains reference documentation for PEAR components
    that are distributed with PHP.  It is assumed that you are
    already familiar with <link linkend="language.oop">objects and
    classes</link>.
   </simpara>
  </partintro>
  <refentry id="class.pear">
   <refnamediv>
    <refname>PEAR</refname>
    <refpurpose>PEAR base class</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <synopsis>require_once "PEAR.php";</synopsis>
    <synopsis>class <replaceable>classname</replaceable> extends <classname>PEAR</classname> { ... }</synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Description</title>
    <simpara>
     The PEAR base class provides standard functionality that is used
     by most PEAR classes.  Normally you never make an instance of the
     PEAR class directly, you use it by subclassing it.
    </simpara>
    <para>
     Its key features are:
     <itemizedlist>
      <listitem>
       <simpara>request-shutdown object "destructors"</simpara>
      </listitem>
      <listitem>
       <simpara>error handling</simpara>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
   <refsect1 id="pear.destructors">
    <title>PEAR "destructors"</title>
    <simpara>
     If you inherit <classname>PEAR</classname> in a class called
     <replaceable>ClassName</replaceable>, you can define a method in
     it called called _<replaceable>ClassName</replaceable> (the
     class name with an underscore prepended) that will be invoked
     when the request is over.  This is not a destructor in the sense
     that you can "delete" an object and have the destructor called,
     but in the sense that PHP gives you a callback in the object
     when PHP is done executing.  See <link
     linkend="example.pear.destructors">the example</link> below.
    </simpara>
    <para>
     <warning id="pear.destructors.warning">
      <title>Important!</title>
      <para>
       In order for destructors to work properly, you must
       instantiate your class with the "=&amp; new" operator like
       this:
       <programlisting role="php">
$obj =&amp; new MyClass();
</programlisting>
      </para>
      <simpara>
       If you only use "= new", the object registered in PEAR's
       shutdown list will be a copy of the object at the time the
       constructor is called, and it will this copy's "destructor"
       that will be called upon request shutdown.
      </simpara>
     </warning>
    </para>
   </refsect1>
   <refsect1 id="pear.error-handling">
    <title>PEAR Error Handling</title>
    <simpara>
     PEAR's base class also provides a way of passing around more
     complex errors than a true/false value or a numeric code.  A
     PEAR error is an object that is either an instance of the class
     <classname>PEAR_Error</classname>, or some class inheriting
     <classname>PEAR_Error</classname>.
    </simpara>
    <simpara>
     One of the design criteria of PEAR's errors is that it should not
     force a particular type of output on the user, it should be
     possible to handle errors without any output at all if that is
     desirable.  This makes it possible to handle errors gracefully,
     also when your output format is different from HTML (for example
     WML or some other XML format).
    </simpara>
    <simpara>
     The error object can be configured to do a number of things when
     it is created, such as printing an error message, printing the
     message and exiting, raising an error with PHP's
     <function>trigger_error</function> function, invoke a callback,
     or none of the above.  This is typically specified in
     <classname>PEAR_Error</classname>'s constructor, but all of the
     parameters are optional, and you can set up defaults for errors
     generated from each object based on the
     <classname>PEAR</classname> class.  See the <link
     linkend="example.pear.error1">PEAR error examples</link> for how
     to use it and the <classname>PEAR_Error</classname> reference
     for the full details.
    </simpara>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <para>
     The example below shows how to use the PEAR's "poor man's kinda
     emulated destructors" to implement a simple class that holds the
     contents of a file, lets you append data to the object and
     flushes the data back to the file at the end of the request:
     <example id="example.pear.destructors">
      <title>PEAR: emulated destructors</title>
      <programlisting role="php">
require_once "PEAR.php";

class FileContainer extends PEAR
{
    var $file = '';
    var $contents = '';
    var $modified = 0;
    
    function FileContainer($file)
    {
        $this->PEAR(); // this calls the parent class constructor
        $fp = fopen($file, "r");
        if (!is_resource($fp)) {
            return;
        }
        while (!empty($data = fread($fp, 2048))) {
            $this->contents .= $data;
    	}
        fclose($fp);
    }

    function append($str)
    {
        $this->contents .= $str;
        $this->modified++;
    }

    // The "destructor" is named like the constructor
    // but with an underscore in front.
    function _FileContainer()
    {
        if ($this->modified) {
            $fp = fopen($this->file, "w");
            if (!is_resource($fp)) {
                return;
            }
            fwrite($fp, $this->contents);
            fclose($fp);
        }
    }
}

$fileobj =&amp; new FileContainer("testfile");
$fileobj->append("this ends up at the end of the file\n");

// When the request is done and PHP shuts down, $fileobj's
// "destructor" is called and updates the file on disk.

</programlisting>
     </example>
     <note>
      <simpara>
       PEAR "destructors" use PHP's shutdown callbacks
       (<function>register_shutdown_function</function>), and you
       can't output anything from these when PHP is running in a web
       server.  So anything printed in a "destructor" gets lost except
       when PHP is used in command-line mode.  Bummer.
      </simpara>
      <simpara>
       Also, see the <link
       linkend="pear.destructors.warning">warning</link> about how to
       instantiate objects if you want to use the destructor.
      </simpara>
     </note>
    </para>
    <simpara>
     The next examples illustrate different ways of using PEAR's error
     handling mechanism.
    </simpara>
    <para>
     <example id="example.pear.error1">
      <title>PEAR error example (1)</title>
      <programlisting role="php">
function mysockopen($host = "localhost", $port = 8090)
{
    $fp = fsockopen($host, $port, $errno, $errstr);
    if (!is_resource($fp)) {
        return new PEAR_Error($errstr, $errno);
    }
    return $fp;
}

$sock = mysockopen();
if (PEAR::isError($sock)) {
    print "mysockopen error: ".$sock->getMessage()."&lt;BR>\n"
}
</programlisting>
     </example>
    </para>
    <simpara>
     This example shows a wrapper to <function>fsockopen</function>
     that delivers the error code and message (if any) returned by
     fsockopen in a PEAR error object.  Notice that
     <function>PEAR::isError</function> is used to detect whether a
     value is a PEAR error.
    </simpara>
    <simpara>
     PEAR_Error's mode of operation in this example is simply
     returning the error object and leaving the rest to the user
     (programmer).  This is the default error mode.
    </simpara>
    <simpara>
     In the next example we're showing how to use default error modes:
    </simpara>
    <para>
     <example id="example.pear.error2">
      <title>PEAR error example (2)</title>
      <programlisting role="php">
class TCP_Socket extends PEAR
{
    var $sock;

    function TCP_Socket()
    {
        $this->PEAR();
    }

    function connect($host, $port)
    {
        $sock = fsockopen($host, $port, $errno, $errstr);
        if (!is_resource($sock)) {
            return $this->raiseError($errstr, $errno);
        }
    }
}

$sock = new TCP_Socket;
$sock->setErrorHandling(PEAR_ERROR_DIE);
$sock->connect("localhost", 8090);
print "still alive&lt;BR>\n";
</programlisting>
     </example>
    </para>
    <simpara>
     Here, we set the default error mode to
     <constant>PEAR_ERROR_DIE</constant>, and since we don't specify
     any error mode in the raiseError call (that'd be the third
     parameter), raiseError uses the default error mode and exits if
     fsockopen fails.
    </simpara>
   </refsect1>
   <refsect1>
    <title>Global Variables Used</title>
    <para>
     The PEAR class uses some global variables to register global
     defaults, and an object list used by the "destructors".  All of
     the global variables associated with the PEAR class have a
     <literal>_PEAR_</literal> name prefix.
    </para>
    <para>
     <variablelist>
      <varlistentry>
       <term>$_PEAR_default_error_mode</term>
       <listitem>
	<simpara>
	 If no default error mode is set in an object, this mode will
	 be used.  Must be one of
	 <constant>PEAR_ERROR_RETURN</constant>,
	 <constant>PEAR_ERROR_PRINT</constant>,
	 <constant>PEAR_ERROR_TRIGGER</constant>,
	 <constant>PEAR_ERROR_DIE</constant> or
	 <constant>PEAR_ERROR_CALLBACK</constant>.
	</simpara>
	<para>
	 Don't set this variable directly, call
	 <function>PEAR::setErrorHandling</function> as a static
	 method like this:
	 <informalexample>
	  <programlisting role="php">
PEAR::setErrorHandling(PEAR_ERROR_DIE);
</programlisting>
	 </informalexample>
	</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>$_PEAR_default_error_options</term>
       <listitem>
	<simpara>
	 If the error mode is <constant>PEAR_ERROR_TRIGGER</constant>,
	 this is the error level (one of
	 <constant>E_USER_NOTICE</constant>,
	 <constant>E_USER_WARNING</constant> or
	 <constant>E_USER_ERROR</constant>).
	</simpara>
	<para>
	 Don't set this variable directly, call
	 <function>PEAR::setErrorHandling</function> as a static
	 method like this:
	 <informalexample>
	  <programlisting role="php">
PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR);
</programlisting>
	 </informalexample>
	</para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>$_PEAR_default_error_callback</term>
       <listitem>
	<simpara>
	 If no <replaceable>options</replaceable> parameter is used
	 when an error is raised and the error mode is
	 <constant>PEAR_ERROR_CALLBACK</constant>, the value of this
	 variable is used as the callback.  This means that you can
	 switch the error mode temporarily and return to callback mode
	 without specifying the callback function again.  A string
	 value represents a function, a two-element array with an
	 object at index 0 and a string at index 1 represents a
	 method.
	</simpara>
	<para>
	 Again, don't set this variable directly, call
	 <function>PEAR::setErrorHandling</function> as a static
	 method like this:
	 <informalexample>
	  <programlisting role="php">
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler");
</programlisting>
	 </informalexample>
	</para>
	<para>
	 Here is an example of how you can switch back and forth
	 without specifying the callback function again:
	 <informalexample>
	  <programlisting role="php">
PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler");
do_some_stuff();
PEAR::setErrorMode(PEAR_ERROR_DIE);
do_some_critical_stuff();
PEAR::setErrorMode(PEAR_ERROR_CALLBACK);
// now we're back to using my_function_handler again
</programlisting>
	 </informalexample>
	</para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>
   <refsect1>
    <title>Methods</title>
    <refsect2 id="function.pear.pear">
     <title>PEAR::PEAR</title>
     <funcsynopsis>
      <funcprototype>
       <funcdef>PEAR()</funcdef>
       <void/>
      </funcprototype>
     </funcsynopsis>
     <para>
      This is the PEAR class constructor.  Call it from the
      constructor of every class inheriting the PEAR class.
      <example>
       <title>PEAR Class Constructor Example</title>
       <programlisting role="php">
class MyClass extends PEAR
{
    var $foo, $bar;
    function MyClass($foo, $bar)
    {
        $this->PEAR();
        $this->foo = $foo;
        $this->bar = $bar;
    }
}
</programlisting>
      </example>
     </para>
    </refsect2>
    <refsect2 id="function.pear.-pear">
     <title>PEAR::_PEAR</title>
     <funcsynopsis>
      <funcprototype>
       <funcdef>_PEAR()</funcdef>
       <void/>
      </funcprototype>
     </funcsynopsis>
     <para>
      This is the PEAR class destructor.  It is called during request
      shutdown.
     </para>
    </refsect2>
   </refsect1>
  </refentry>
  <refentry id="class.pear-error">
   <refnamediv>
    <refname>PEAR_Error</refname>
    <refpurpose>PEAR error mechanism base class</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <synopsis>$err = new <classname>PEAR_Error</classname>($msg);</synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Error Modes</title>
    <para>
     An error object has a mode of operation that can be set with one
     of the following constants:
     <variablelist id="pear.error-modes">
      <varlistentry id="constant.pear-error-return">
       <term>PEAR_ERROR_RETURN</term>
       <listitem>
	<simpara>
	 Just return the object, don't do anything special in
	 PEAR_Error's constructor.
	</simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-print">
       <term>PEAR_ERROR_PRINT</term>
       <listitem>
	<simpara>
	 Print the error message in the constructor.  The execution is
	 not interrupted.
	</simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-trigger">
       <term>PEAR_ERROR_TRIGGER</term>
       <listitem>
	<simpara>
	 Use PHP's <function>trigger_error</function> function to
	 raise an internal error in PHP.  The execution is aborted if
	 you have defined your own PHP error handler or if you set the
	 error severity to E_USER_ERROR.
	</simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-die">
       <term>PEAR_ERROR_DIE</term>
       <listitem>
	<simpara>
	 Print the error message and exit.  Execution is of course
	 aborted.
	</simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-callback">
       <term>PEAR_ERROR_CALLBACK</term>
       <listitem>
	<simpara>
	 Use a callback function or method to handle errors.
	 Execution is aborted.
	</simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>
   <refsect1>
    <title>Properties</title>
    <simpara></simpara>
   </refsect1>
   <refsect1>
    <title>Methods</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef><function>PEAR_Error::PEAR_Error</function></funcdef>
      <paramdef>
       <parameter><optional>message</optional></parameter>
       <parameter><optional>code</optional></parameter>
       <parameter><optional>mode</optional></parameter>
       <parameter><optional>options</optional></parameter>
       <parameter><optional>userinfo</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <refsect2>
     <title>Description</title>
     <para>
      PEAR_Error constructor.  Parameters:
      <variablelist>
       <varlistentry>
	<term>message</term>
	<listitem>
	 <simpara>
	  error message, defaults to "unknown error"
	 </simpara>
	</listitem>
       </varlistentry>
       <varlistentry>
	<term>code</term>
	<listitem>
	 <simpara>
	  error code (optional)
	 </simpara>
	</listitem>
       </varlistentry>
       <varlistentry>
	<term>mode</term>
	<listitem>
	 <simpara>
	  Mode of operation.  See the <link
	  linkend="pear.error-modes">error modes</link> section for
	  details.
	 </simpara>
	</listitem>
       </varlistentry>
       <varlistentry>
	<term>options</term>
	<listitem>
	 <simpara>
	  If the mode of can have any options specified, use this
	  parameter.  Currently the "trigger" and "callback" modes are
	  the only using the options parameter.  For trigger mode,
	  this parameter is one of <constant>E_USER_NOTICE</constant>,
	  <constant>E_USER_WARNING</constant> or
	  <constant>E_USER_ERROR</constant>.  For callback mode, this
	  parameter should contain either the callback function name
	  (string), or a two-element (object, string) array
	  representing an object and a method name.
	 </simpara>
	</listitem>
       </varlistentry>
      </variablelist>
     </para>
    </refsect2>
   </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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->