As mentioned before, PEAR manages the PEAR application code base according to certain categories. Your PEAR code can be organized into appropriate directories, and other people can easily retrieve and share your results. PEAR is not just a code repository, it is also a standard. Using this standard to write your PHP code will enhance the readability and reusability of your program and reduce the chance of errors. PEAR builds a framework for you by providing two classes that implement functions such as destructors and error catching. You can use these functions through inheritance.
PEAR's coding rules include indentation rules, control structures, function calls, function definitions, comments, included code, PHP tags, file header comment blocks, CVS tags, URL samples, and constant naming. Here is a brief introduction:
Indentation rules:
PEAR requires 4 spaces to indent the code, and no TAB is used. If you use VIM, put the following settings in your ~/.vimrc: set expandtab
set shiftwidth=4
set tabstop=4
If you use Emacs/XEmacs, you need to set indent-tabs-mode to nil.
But if you like to use (X)Emacs to edit PHP files like me, I strongly recommend you to install PHP-MODE so that when you write PEAR code, it will automatically adjust your indentation style. Of course, there are many PHP-MODE Very good feature, you can download the latest version of PHP-MODE from the resource list.
Control structure:
The control structures mentioned here include: if for while switch, etc. For control structures, there should be a space after the keyword (such as if for ..), and then the control parentheses, so that it will not be confused with function calls. In addition, you should try to use curly braces {} as completely as possible. Even if it is syntactically optional. This will prevent logical confusion or errors when you need to add new lines of code in the future. Here is an example: if ((condition1) && (condition2)) {
Statement 1;
}esleif ((Condition 3) || (Condition 4)) {
Statement 2;
}else {
Statement 3;
}
Function call:
For function calls, there should be no space between the function name and the opening bracket ( (), for function parameters, there should be the same space separation between the delimiting comma and the next parameter, and there should be no space between the last parameter and the closing bracket. Below Is a standard function call; $result = foo($param1, $param2, $param3);
Irregular writing:
$result=foo ($param1,$param2,$param3);
$result=foo( $param1,$param2, $param3 );
In addition, if you want to assign the return result of the function, there must be a space between the equal sign and the assigned variable. At the same time, if it is a series of related assignment statements, you add appropriate spaces to align them, like this ：$result1 = $foo($param1, $param2, $param3);
$var2 = $foo($param3);
$var3 = $foo($param4, $param5);
Function definition:
The function definition follows the "one true brace" convention: function connect(&$dsn, $persistent = false){
if (is_array($dsn)) {
$dsninfo = &&dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
As shown above, optional parameters should be at the end of the parameter list, and always try to return meaningful function values.
Regarding comments:
For online documentation of classes, it should be able to be converted by PHPDoc, just like JavaDoc. PHPDoc is also a PEAR application. For a more detailed introduction, you can go to http://www.phpdoc.de/ to view it. In addition to online documentation of classes, it is recommended that you use non-documentation comments to explain your code. When you see a piece of code, you think: Oh, I don't think you need to describe it carefully in the documentation. Then you'd better give this code a simple comment to prevent you from forgetting how it works. For comment forms, C's /* */ and C++'s // are both good. However, do not use Perl or shell's # comment method.
Contains code:
Whenever you need to unconditionally include a class file, you must use require_once; when you need to conditionally include a class file, you must use include_once; this ensures that the file you want to include will only be included once, and these 2 Both statements share the same file list, so you don't have to worry about the two getting confused. Once require_once includes a file, include_once will not include the same file again, and vice versa.
PHP code markup:
Define your PHP code at all times, rather than simply using it. This ensures PEAR compatibility and facilitates cross-platform porting.
Comment declaration in the file header:
For all PHP code files that need to be included in the PEAR core release, you must add the following comment statement at the beginning of the file: /* vim: set expandtab tabstop=4 shiftwidth=4: */
// +-------------------------------------------------- -----------------------+
// | PHP version 4.0 |
// +-------------------------------------------------- -----------------------+
// | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group |
// +-------------------------------------------------- -----------------------+
// | This source file is subject to version 2.0 of the PHP license, |
// | that is bundled with this package in the file LICENSE, and is |
// | available at through the world-wide-web at |
// | http://www.php.net/license/2_02.txt . |
// | If you did not receive a copy of the PHP license and are unable to |
// | obtain it through the world-wide-web, please send a note to |
// | [email protected] so we can mail you a copy immediately. |
// +-------------------------------------------------- -----------------------+
// | Authors: Original Author |
// | Your Name |
// +-------------------------------------------------- -----------------------+
//
// $Id$
For files that are not in the PEAR core code base, it is recommended that you also have a similar comment block like this at the beginning of the file, indicating copyright, license, author, etc. At the same time, add VIM’s MODELINE in the first line, so that PEAR’s code style can be maintained in VIM.
CVS markup:
As shown above, add the CVS ID tag to each file. If the file you edit or modify does not have this tag, please add it, or replace it with a similar expression in the original file (such as "Last modified" etc.)
URL sample:
You can follow RFC 2606 and use " www.example.com " as all URL examples.
Constant naming:
Constants should be written in uppercase when possible, and to make it easier to understand, use underscores to separate each word. At the same time, you should prefix the package name or class name where the constant is located. For example, constants in the Bug class should start with Bug_. The above are the coding rules of PEAR. For detailed coding rules, please refer to the description of the CODING_STANDDARD file in PEAR. To better understand these coding rules, you can also refer to the code of the existing PEAR core module.
Get started with PEAR
Using PEAR is very simple, you only need to define your own PEAR program like this: require_once "PEAR.php";
class your_class_name extends PEAR{
Your class definition...
}
Of course, you need to abide by the PEAR coding rules mentioned above, and then you can implement what you want to do inside your class. Next, let's discuss it. In fact, PEAR provides us with 2 predefined classes: PEAR: This is the base class of PEAR, and all PEAR extensions must inherit and derive from it. PEAR_Error: PEAR's error handling base class, you can choose to derive your own error handling class.
Generally speaking, you should not create an instance of PEAR directly, but derive a new class yourself and then create an instance of this new class. As a base class, PEAR provides us with some useful functions, the most important ones are destructors and error handling
destructors.
PHP supports constructors, but does not support destructors. However, PHP provides the register_shutdown_function() function, which can call back the registered function before the script terminates. Therefore, PEAR takes advantage of this feature to provide simulation of the destructor. If you have a subclass of PEAR called mypear, then in the mypear class, you can define a function. The function name is an underscore plus your class name, _mypear(). This function is the destructor of this class. However, this destructor is different from the destructor in C++. It will not be executed when the object is deleted, but when the script ends. After all, this is just a simulation. Since register_shutdown_function() is used, the printed information will not be returned to the browser in your destructor. In addition, in your constructor, you need to call the constructor of its parent class, because PHP will not automatically call the constructor of the parent class, and the destructor needs to be registered in the constructor of PEAR. We can take a look at PEAR Source code: function PEAR() {
if (method_exists($this, "_".get_class($this))) {
global $_PEAR_destructor_object_list;
$_PEAR_destructor_object_list[] = &this;
}
if ($this->_debug) {
printf("PEAR constructor called, class=%sn",
get_class($this));
}
.....
function _PEAR_call_destructors() {
global $_PEAR_destructor_object_list;
if (is_array($_PEAR_destructor_object_list) && sizeof($_PEAR_destructor_object_list)) {
reset($_PEAR_destructor_object_list);
while (list($k, $objref) = each($_PEAR_destructor_object_list)) {
$destructor = "_".get_class($objref);
if (method_exists($objref, $destructor)) {
$objref->$destructor();
}
}
//Clear the registered object list,
//Prevent repeated calls
$_PEAR_destructor_object_list = array();
}}
....
register_shutdown_function("_PEAR_call_destructors");
The above code shows how PEAR implements the destructor. In the component function, it will check whether there is a destructor in the current class. If so, then the reference of the current class will be put into a global list, in _ In PEAR_call_destructors, check whether each element in the global list has a corresponding destructor, if so, call it, and finally clear the global list.
In the last line of code in PEAR.php, call register_shutdown_function("_PEAR_call_destructors") to register _PEAR_call_destructors, so that when the script is executed, PHP will call back this function. Using the destructor, you can do some necessary "aftercare" work before exiting after processing the user's request. Typical examples are that you can close open files, disconnect from the database, and store certain data on the disk. etc.
Error handling
PEAR allows you to handle errors in many ways. You not only simply return an error code or error information, but you can return a PEAR_Error object, or a new error object derived from PEAR_Error.
The error object in PEAR does not limit the specific output form. It can just capture the error without returning too much information to the user, or it can call back a special error handling function. At the same time, even if it outputs error information, it can also You are forced to use HTML format. You can output XML, CSV format, or other formats defined by yourself. You only need to derive a new class from PEAR_Error, and then create and "throw" this new class at the appropriate time. object on it.
Simple error handling:
In PEAR, the simplest error handling is to "throw" the error. You simply create and return a PEAR_Error object. Here is a simple example: function myconnect($host = "localhost", $port = 1080){
$fp = fsockopen($host, $port, $errno, $errstr);
if (!is_resource($fp)) {
return new PEAR_Error($errstr, $errno);
}
return $fp;
}
$sock = myconnect();
if (PEAR::isError($sock)) {
print "connect error: ".$sock->getMessage()."n"
}
As shown in the above code, after executing a piece of code that may produce an error, you need to use PEAR's isError to detect whether there is an error, and you can use PEAR_Error's getMessage to obtain the latest error message.
and raiseError
in key places.
After PHP4.0.5, PEAR has 2 more functions:
setErrorHandling($mode, $options = null)
raiseError($message = null, $code = null, $mode = null,$options = null, $userinfo = null)
The former can set PEAR's default error handling mode, and the latter is a wrapper function that returns a PEAR_Error object. It is slightly different from directly creating and returning a PEAR_Error object. If parameters such as $mode and $options are omitted, it will Create this PEAR_Error object using default values, which you can customize using setErrorHandling().
PEAR_Error
PEAR_Error is a base class of PEAR's error object. Different from PEAR, generally speaking, you can directly create an instance of PEAR_Error. The creation method is: $error = new PEAR_Error($message, $code, $mode, $options, $userinfo );
$message is your error message, $code is the error number of the error, and the last three parameters are closely related:
$mode: is the error handling mode, which can be the following constants:
PEAR_ERROR_RETURN: Only return the error object (default mode)
PEAR_ERROR_PRINT: Print this error message in the build function, but the current program will continue to run.
PEAR_ERROR_TRIGGER: Use PHP's trigger_error() to trigger an error. If you have set up an error handling function, or you set PHP's error handling level to E_USER_ERROR, then the current program will be terminated.
PEAR_ERROR_DIE: Print the error and exit, the program terminates.
PEAR_ERROR_CALLBACK: Use a callback function or method to handle the current error and the program terminates.
$options: This parameter only works when $mode is PEAR_ERROR_TRIGGER and PEAR_ERROR_CALLBACK. If it is PEAR_ERROR_TRIGGER, $options must be one of the three constants E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR, which is consistent with the value of trigger_error in PHP. If $mode is PEAR_ERROR_CALLBACK, $options can be a string containing the name of the function to be called back, or an array of 2 elements, respectively an object variable and a string (indicating the method to be called).
$userinfo: Stores additional user information. You can put relevant debugging information here.
There are some commonly used methods in PEAR_Error, which are not described in the PHP documentation. They are listed here:
int getMode: Returns the current error handling mode, integer.
string getMessage: Returns the current complete error message, string.
mixed getCallback: Returns the current callback information, which may be the name of the function being called back, or an array of (objects, methods).
int getCode: Returns an integer error code.
string getType: Returns the wrong type, which is the current class name, string.
string getUserInfo: Returns additional user information, string.
string getDebugInfo: The content is the same as above.
string toString: Returns a detailed string description of the current object, including error handling mode, level, error information, error code, related callback functions, etc.
summary
, the introduction to PEAR is over. In summary, if you want to make a PEAR extension application, you need to do this:
require_once "PEAR.php"
Use class your_pear_extend extends PEAR{} to define your new class.
In the constructor of your class, call the constructor of the parent class PEAR: function your_pear_extend{
$this->PEAR();
...
}
If necessary, define your destructor _your_pear_extend
If necessary, derive your own error handling class from PEAR_Error to set your error handling mode and trigger errors when appropriate.
After executing code that may generate errors, use PEAR::isError($obj) to capture the corresponding errors.
Implement your own functionality.
In the PEAR core release, there are already many excellent application modules, such as: PHPDoc, Cache, and HTML.