From 8c2003e7f18d0a4d24d723e34f519c26f8f1d093 Mon Sep 17 00:00:00 2001 From: Stig Bakken Date: Thu, 8 Mar 2001 02:45:54 +0000 Subject: [PATCH] * more PEAR docs git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@42935 c90b9560-bf6c-de11-be94-00142212c4b1 --- language-defs.ent | 2 +- pear/about.xml | 59 ++++++++++ pear/pear.xml | 266 +++++++++++++++++++++++++++++++++++++++++- pear/standards.xml | 282 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 603 insertions(+), 6 deletions(-) create mode 100644 pear/about.xml create mode 100644 pear/standards.xml 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 Manual PEAR - + + + 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. + + + PEAR PEAR 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_Error PEAR 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. + + + + + + +