diff --git a/language-defs.ent b/language-defs.ent
index 67e8f8b20d..dfeed7cef1 100644
--- a/language-defs.ent
+++ b/language-defs.ent
@@ -5,6 +5,6 @@
-
+
diff --git a/pear/about.xml b/pear/about.xml
new file mode 100644
index 0000000000..fd8d6f185e
--- /dev/null
+++ b/pear/about.xml
@@ -0,0 +1,59 @@
+
+ About PEAR
+
+ PEAR is dedicated to Malin Bakken,
+ born 1999-11-21 (the first PEAR code was written just two hours
+ before she was born).
+
+
+
+ What is PEAR?
+
+ PEAR is a code repository for PHP extensions and PHP library code
+ inspired by TeX's CTAN and Perl's CPAN.
+
+
+ The purpose of PEAR is:
+
+
+
+ to provide a consistent means for library code authors to share
+ their code with other developers
+
+
+
+
+ to give the PHP community an infrastructure for sharing code
+
+
+
+
+ to define standards that help developers write portable and
+ reusable code
+
+
+
+
+ to provide tools for code maintenance and distribution
+
+
+
+
+
+
+
diff --git a/pear/pear.xml b/pear/pear.xml
index dca79a87a1..47553ba473 100644
--- a/pear/pear.xml
+++ b/pear/pear.xml
@@ -1,11 +1,22 @@
- PEAR: the PHP Extension and Application Repository
+ PEAR Reference ManualPEAR
-
+
+
+ This chapter contains reference documentation for PEAR components
+ that are distributed with PHP. It is assumed that you are
+ already familiar with objects and
+ classes.
+
+
+ PEARPEAR base class
+
+ class classname extends PEAR { ... }
+ Description
@@ -24,6 +35,52 @@
+
+ PEAR "destructors"
+
+ If you inherit PEAR in a class called
+ ClassName, you can define a method in
+ it called called _ClassName (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 it is done executing. See the example below.
+
+
+
+ PEAR Error Handling
+
+ 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
+ PEAR_Error, or some class inheriting
+ PEAR_Error.
+
+
+ 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
+ desireable. 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).
+
+
+ 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
+ trigger_error function, invoke a callback,
+ or none of the above. This is typically specified in
+ PEAR_Error's constructor, but all of the
+ parameters are optional, and you can set up defaults for errors
+ generated from each object based on the
+ PEAR class. See the PEAR error examples for how
+ to use it and the PEAR_Error reference
+ for the full details.
+
+ Examples
@@ -32,7 +89,7 @@
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:
-
+ PEAR: emulated destructors
require_once "PEAR.php";
@@ -95,17 +152,216 @@ $fileobj->append("this ends up at the end of the file\n");
+
+ The next examples illustrate different ways of using PEAR's error
+ handling mechanism.
+
+
+
+ PEAR error example (1)
+
+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()."<BR>\n"
+}
+
+
+
+
+ This example shows a wrapper to fsockopen
+ that delivers the error code and message (if any) returned by
+ fsockopen in a PEAR error object. Notice that
+ PEAR::isError is used to detect whether a
+ value is a PEAR error.
+
+
+ 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.
+
+
+ In the next example we're showing how to use default error modes:
+
+
+
+ PEAR error example (2)
+
+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<BR>\n";
+
+
+
+
+ Here, we set the default error mode to
+ PEAR_ERROR_DIE, 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.
+
-
+ PEAR_ErrorPEAR error mechanism base class
+
+ $err = new PEAR_Error($msg);
+
- Description
+ Error Modes
+
+ An error object has a mode of operation that can be set with one
+ of the following constants:
+
+
+ PEAR_ERROR_RETURN
+
+
+ Just return the object, don't do anything special in
+ PEAR_Error's constructor.
+
+
+
+
+ PEAR_ERROR_PRINT
+
+
+ Print the error message in the constructor. The execution is
+ not interrupted.
+
+
+
+
+ PEAR_ERROR_TRIGGER
+
+
+ Use PHP's trigger_error 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.
+
+
+
+
+ PEAR_ERROR_DIE
+
+
+ Print the error message and exit. Execution is of course
+ aborted.
+
+
+
+
+ PEAR_ERROR_CALLBACK
+
+
+ Use a callback function or method to handle errors.
+ Execution is aborted.
+
+
+
+
+
+
+
+ Properties
+
+ Methods
+
+
+ PEAR_Error::PEAR_Error
+
+ message
+ code
+ mode
+ options
+ userinfo
+
+
+
+
+ Description
+
+ PEAR_Error constructor. Parameters:
+
+
+ message
+
+
+ error message, defaults to "unknown error"
+
+
+
+
+ code
+
+
+ error code (optional)
+
+
+
+
+ mode
+
+
+ Mode of operation. See the error modes section for
+ details.
+
+
+
+
+ options
+
+
+ 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 E_USER_NOTICE,
+ E_USER_WARNING or
+ E_USER_ERROR. 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.
+
+
+
+
+
+
+