PEAR:修订间差异
无编辑摘要 |
Ahbaybface(讨论 | 贡献) 无编辑摘要 |
||
第1行: | 第1行: | ||
[[Image:pear_logo.png|right]] | |||
'''PEAR'''是[[PHP]]扩展与应用库(the PHP Extension and Application Repository)的缩写。它是一个PHP扩展及应用的一个代码仓库,简单地说,PEAR就是PHP的CPAN. | |||
==PEAR的特性== | |||
#PEAR按照一定的分类来管理PEAR应用代码库,你的PEAR代码可以组织到其中适当的目录中,其他的人可以方便地检索并分享到你的成果。 | |||
#PEAR不仅仅是一个代码仓库,它同时也是一个标准,使用这个标准来书写你的PHP代码,将会增强你的程序的可读性,复用性,减少出错的几率。 | |||
#PEAR通过提供2个类为你搭建了一个[[框架]],实现了诸如析构函数,错误捕获功能,你通过继承就可以使用这些功能。 | |||
==PEAR的编码规则== | |||
PEAR的编码规则包括:缩进规则,控制结构,函数调用,函数定义,注释,包含代码,PHP标记,文件头的注释块,CVS标记,[[URL]]样例,常量的命名这11方面。下面简要地介绍一下: | |||
* 缩进规则 | |||
PEAR中需要使用4个空格来缩排代码,并且不使用TAB。如果你使用VIM,将下列设置放入你的~/.vimrc中: | |||
<pre> | |||
set expandtab | |||
set shiftwidth=4 | |||
set tabstop=4 | |||
</pre> | |||
如果,你使用Emacs/XEmacs,需要把indent-tabs-mode 设置成nil。 | |||
不过你象我一样喜欢用(X)Emacs编辑PHP文件,我强烈推荐你安装PHP-MODE,这样当你编写PEAR代码的时候,它会自动调整你的缩排风格,当然PHP-MODE还有许多很优秀的特性,你可以从资源列表中的地方下载最新版的PHP-MODE。 | |||
* 控制结构 | |||
这里所说的控制结构包括: if for while switch 等。对于控制结构,在关键字(如if for ..)后面要空一个格,然后再跟控制的圆括号,这样,不至于和函数调用混淆,此外,你应该尽量完整的使用花括号{},即使从语法上来说是可选的。这样可以防止你以后需添加新的代码行时产生逻辑上的疑惑或者错误。这里是一个样例: | |||
<pre> | |||
if ((条件1) && (条件2)) { | |||
语句1; | |||
}esleif ((条件3) || (条件4)) { | |||
语句2; | |||
}else { | |||
语句3; | |||
} | |||
</pre> | |||
* 函数调用 | |||
对于函数调用,函数名和左括号之间不应该有空格,对于函数参数,在分隔的逗号和下一个参数之间要有相同的空格分离,最后一个参数和右括号之间不能有空格。下面是一个标准的函数调用; | |||
<pre> | |||
$result = foo($param1, $param2, $param3); | |||
</pre> | |||
不规范的写法: | |||
<pre> | |||
$result=foo ($param1,$param2,$param3); | |||
$result=foo( $param1,$param2, $param3 ); | |||
</pre> | |||
此外,如果要将函数的返回结果赋值,那么在等号和所赋值的变量之间要有空格,同时,如果是一系列相关的赋值语句,你添加适当的空格,使它们对齐,就象这样: | |||
<pre> | |||
$result1 = $foo($param1, $param2, $param3); | |||
$var2 = $foo($param3); | |||
$var3 = $foo($param4, $param5); | |||
</pre> | |||
* 函数定义 | |||
函数定义遵循"one true brace"习俗: | |||
<pre> | |||
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; | |||
} | |||
</pre> | |||
如上所示,可选参数要在参数表的末端,并且总是尽量返回有意义的函数值。 | |||
* 关于注释 | |||
对于类的在线文档,应该能够被PHPDoc转换,就象JavaDoc那样。PHPDoc也是一个PEAR的应用程序,更详细的介绍你可以去 <nowiki>http://www.phpdoc.de/</nowiki> 查看。除了类的在线文档,建议你应该使用非文档性质的注释来诠释你的代码,当你看到一段代码时想:哦,我想不需要在文档里去仔细描述它吧。那么你最好给这段代码作一个简单的注释,这样防止你会忘记它们是如何工作的。对于注释的形式,[[C]]的 /* */和[[C++]]的//都不错,不过,不要使用[[Perl]]或者shell的#注释方式。 | |||
* 包含代码 | |||
无论什么时候,当你需要无条件包含进一个class文件,你必须使用requre_once;当你需要条件包含进一个class文件,你必须使用 include_once;这样可以保证你要包含的文件只会包含一次,并且这2个语句共用同一个文件列表,所以你无须担心二者会混淆,一旦 require_once 包含了一个文件,include_once不会再重复包含相同的文件,反之亦然。 | |||
* PHP代码标记 | |||
任何时候都要使用<?php ?>定义你的php代码,而不要简单地使用<? ?>,这样可以保证PEAR的兼容性,也利于跨平台的移植。 | |||
* 文件头的注释声明: | |||
所有需要包含在PEAR核心发布的PHP代码文件,在文件开始的时候,你必须加入以下的注释声明: | |||
<pre> | |||
/* 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 | | |||
// | license@php.net so we can mail you a copy immediately. | | |||
// +----------------------------------------------------------------------+ | |||
// | Authors: Original Author | | |||
// | Your Name | | |||
// +----------------------------------------------------------------------+ | |||
// | |||
// $Id$ | |||
</pre> | |||
对于不在PEAR核心代码库中的文件,建议你也在文件的开始处有这样一个类似的注释块,标明版权,协议,作者等等。同时也在第一行加入VIM的MODELINE,这样在VIM中能够保持PEAR的代码风格。 | |||
* CVS标记 | |||
如上面所展示那样,在每个文件中加入CVS的ID标记,如果你编辑或修改的文件中没有这个标记,那么请加入,或者是替换原文件中相类似的表现形式(如"Last modified"等等) | |||
* URL样本 | |||
你可以参照RFC 2606,使用"www.example.com"作为所有的URL样本。 | |||
* 常量命名 | |||
常量应该尽量使用大写,为了便于理解,使用下划线分割每个单词。同时,你应该常量所在的包名或者是类名作为前缀。比如,对于Bug类中常量应该以Bug_开始。以上是PEAR的编码规则,详细的编码规则可以参考PEAR中的CODING_STANDDARD文件的说明。为了更好地理解这些编码规则,你也可以参考一下现有PEAR核心模块的代码。 | |||
==PEAR的使用== | |||
==PEAR相关资源== | |||
[http://pear.php.net/ 官方网站] | [http://pear.php.net/package/PEAR/download PEAR官方下载] | |||
==相关条目== | |||
*[[PHP]] | |||
*[[php APC]] | |||
*[[php PECL]] | |||
*[[PDO]] | |||
*[[GD]] | |||
==参考来源== | |||
*[http://www.ibm.com/developerworks/cn/linux/sdk/php/pear1/index.html 参考来源1] | |||
第18行: | 第133行: | ||
[[category:开放源代码|P]] | [[category:开放源代码|P]] | ||
[[category:PHP|P]] | [[category:PHP|P]] | ||
[[category:PHP模块|P]] |
2010年1月28日 (四) 16:21的版本
PEAR是PHP扩展与应用库(the PHP Extension and Application Repository)的缩写。它是一个PHP扩展及应用的一个代码仓库,简单地说,PEAR就是PHP的CPAN.
PEAR的特性
- PEAR按照一定的分类来管理PEAR应用代码库,你的PEAR代码可以组织到其中适当的目录中,其他的人可以方便地检索并分享到你的成果。
- PEAR不仅仅是一个代码仓库,它同时也是一个标准,使用这个标准来书写你的PHP代码,将会增强你的程序的可读性,复用性,减少出错的几率。
- PEAR通过提供2个类为你搭建了一个框架,实现了诸如析构函数,错误捕获功能,你通过继承就可以使用这些功能。
PEAR的编码规则
PEAR的编码规则包括:缩进规则,控制结构,函数调用,函数定义,注释,包含代码,PHP标记,文件头的注释块,CVS标记,URL样例,常量的命名这11方面。下面简要地介绍一下:
- 缩进规则
PEAR中需要使用4个空格来缩排代码,并且不使用TAB。如果你使用VIM,将下列设置放入你的~/.vimrc中:
set expandtab set shiftwidth=4 set tabstop=4
如果,你使用Emacs/XEmacs,需要把indent-tabs-mode 设置成nil。
不过你象我一样喜欢用(X)Emacs编辑PHP文件,我强烈推荐你安装PHP-MODE,这样当你编写PEAR代码的时候,它会自动调整你的缩排风格,当然PHP-MODE还有许多很优秀的特性,你可以从资源列表中的地方下载最新版的PHP-MODE。
- 控制结构
这里所说的控制结构包括: if for while switch 等。对于控制结构,在关键字(如if for ..)后面要空一个格,然后再跟控制的圆括号,这样,不至于和函数调用混淆,此外,你应该尽量完整的使用花括号{},即使从语法上来说是可选的。这样可以防止你以后需添加新的代码行时产生逻辑上的疑惑或者错误。这里是一个样例:
if ((条件1) && (条件2)) { 语句1; }esleif ((条件3) || (条件4)) { 语句2; }else { 语句3; }
- 函数调用
对于函数调用,函数名和左括号之间不应该有空格,对于函数参数,在分隔的逗号和下一个参数之间要有相同的空格分离,最后一个参数和右括号之间不能有空格。下面是一个标准的函数调用;
$result = foo($param1, $param2, $param3);
不规范的写法:
$result=foo ($param1,$param2,$param3); $result=foo( $param1,$param2, $param3 );
此外,如果要将函数的返回结果赋值,那么在等号和所赋值的变量之间要有空格,同时,如果是一系列相关的赋值语句,你添加适当的空格,使它们对齐,就象这样:
$result1 = $foo($param1, $param2, $param3); $var2 = $foo($param3); $var3 = $foo($param4, $param5);
- 函数定义
函数定义遵循"one true brace"习俗:
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; }
如上所示,可选参数要在参数表的末端,并且总是尽量返回有意义的函数值。
- 关于注释
对于类的在线文档,应该能够被PHPDoc转换,就象JavaDoc那样。PHPDoc也是一个PEAR的应用程序,更详细的介绍你可以去 http://www.phpdoc.de/ 查看。除了类的在线文档,建议你应该使用非文档性质的注释来诠释你的代码,当你看到一段代码时想:哦,我想不需要在文档里去仔细描述它吧。那么你最好给这段代码作一个简单的注释,这样防止你会忘记它们是如何工作的。对于注释的形式,C的 /* */和C++的//都不错,不过,不要使用Perl或者shell的#注释方式。
- 包含代码
无论什么时候,当你需要无条件包含进一个class文件,你必须使用requre_once;当你需要条件包含进一个class文件,你必须使用 include_once;这样可以保证你要包含的文件只会包含一次,并且这2个语句共用同一个文件列表,所以你无须担心二者会混淆,一旦 require_once 包含了一个文件,include_once不会再重复包含相同的文件,反之亦然。
- PHP代码标记
任何时候都要使用<?php ?>定义你的php代码,而不要简单地使用<? ?>,这样可以保证PEAR的兼容性,也利于跨平台的移植。
- 文件头的注释声明:
所有需要包含在PEAR核心发布的PHP代码文件,在文件开始的时候,你必须加入以下的注释声明:
/* 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 | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ // | Authors: Original Author | // | Your Name | // +----------------------------------------------------------------------+ // // $Id$
对于不在PEAR核心代码库中的文件,建议你也在文件的开始处有这样一个类似的注释块,标明版权,协议,作者等等。同时也在第一行加入VIM的MODELINE,这样在VIM中能够保持PEAR的代码风格。
- CVS标记
如上面所展示那样,在每个文件中加入CVS的ID标记,如果你编辑或修改的文件中没有这个标记,那么请加入,或者是替换原文件中相类似的表现形式(如"Last modified"等等)
- URL样本
你可以参照RFC 2606,使用"www.example.com"作为所有的URL样本。
- 常量命名
常量应该尽量使用大写,为了便于理解,使用下划线分割每个单词。同时,你应该常量所在的包名或者是类名作为前缀。比如,对于Bug类中常量应该以Bug_开始。以上是PEAR的编码规则,详细的编码规则可以参考PEAR中的CODING_STANDDARD文件的说明。为了更好地理解这些编码规则,你也可以参考一下现有PEAR核心模块的代码。
PEAR的使用
PEAR相关资源