* started documenting the PEAR base class and error mechanism

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@42900 c90b9560-bf6c-de11-be94-00142212c4b1

pear/pear.xml

@@ -0,0 +1,126 @@
+ <reference id="ref.pear">
+  <title>PEAR: the PHP Extension and Application Repository</title>
+  <titleabbrev>PEAR</titleabbrev>
+  <refentry id="pear.class.pear">
+   <refnamediv>
+    <refname>PEAR</refname>
+    <refpurpose>PEAR base class</refpurpose>
+   </refnamediv>
+   <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>
+    <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>
+      <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 = 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>
+     </note>
+    </para>
+   </refsect1>
+  </refentry>
+  <refentry id="pear.class.pear-error">
+   <refnamediv>
+    <refname>PEAR_Error</refname>
+    <refpurpose>PEAR error mechanism base class</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <simpara></simpara>
+   </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:
+-->