《服务端插件开发——开发规范》

文件格式

文件应该保存为 Unicode(UTF-8)编码格式,不要使用 字节序标记(BOM),和 UTF-16 和 UTF-32 不一样, UTF-8 编码格式的文件不需要指定字节序。而且 BOM 会在 PHP 的输出中产生副作用, 它会阻止应用程序设置它的头信息。另外,所有的换行符应该使用 Unix 格式换行符(LF)。
以下是在一些常见的文本编辑器中更改这些设置的方法。针对你的编辑器,方法也许会有所不同, 请参考你的编辑器的说明。

TextMate

1. 打开应用程序设置
2. 点击 “高级” ,切换到 “保存” 标签页。
3. 在 “文件编码” 中,选择 “UTF-8(推荐)”
4. 在 “换行符” 中,选择 “LF(推荐)”
5. 可选:如果你想对现有文件也能自动作此设置,勾上 “同时应用到已有文件” 选项

BBEdit

1. 打开应用程序设置
2. 选择左侧的 “文本编码”
3. 在 “新文档的默认编码”,选择 “Unicode (UTF-8, no BOM)”
4. 可选:在 “如果无法检测文件编码,使用...”,选择 “Unicode (UTF-8, no BOM)”
5. 选择左侧的 “文本文件”
6. 在 “默认的换行符” 中,选择 “Mac OS X and Unix (LF)”

Notepad++

1. 打开首选项,“菜单” => “设置” => “首选项”
2. 左侧选择“新建”
3. 在“格式”选择“Unix”
4. 在“编码”选择“UTF-8(无BOM)”

Geany

1. 打开首选项,“菜单” => “编辑” => “首选项”
2. 左侧选择“文件”
3. “新建文件”下的“缺省文件行尾符”选择“Unix(LF)”
4. “编码”下“缺省编码(新文件)”选择“Unicode(UTF-8)”

PHP 结束标签

PHP 结束标签 ?> 对于 PHP 解析器来说是可选的。
但是只要使用了,结束标签之后的空格 有可能会导致不想要的输出,这个空格可能是由开发者或者用户又或者 FTP 应用程序引入的, 甚至可能导致出现 PHP 错误,如果配置了不显示 PHP 错误,就会出现空白页面。
基于这个原因, 所有的 PHP 文件将不使用结束标签,而是以一个空行代替。

插件文件的命名

插件文件总共有3个,包括登录验证接口文件,支付通知接口文件,特殊订单接口文件。
各个接口文件的命名需要遵循如下规则:

登录验证接口文件:首字母大写的SDK标识+Login.php;    
支付通知接口文件:首字母大写的SDK标识+PayNotice.php;    
特殊订单接口文件:SubOrder.php;

除非对应的SDK因兼容旧版本而采用指定的名字,具体的兼容性列表前往 代码兼容性 页面查看。SDK标识首字母转换成大写,其他字母保持不变。

类名、类继承和入口方法名

类名和继承规则

与插件文件对应,总共有3个,包括登录验证接口,支付通知接口,特殊订单接口。
各个接口类的命名需要遵循如下规则:

登录验证接口:首字母大写的SDK标识+LoginController;继承自 SdkLogin;    
支付通知接口:首字母大写的SDK标识+PayNoticeController;继承自 SdkPayNotice;    
特殊订单接口:SubOrder;无继承

除非对应的SDK因兼容旧版本而采用指定的名字,具体的兼容性列表前往 代码兼容性 页面查看。SDK标识首字母转换成大写,其他字母保持不变。

方法名

每个接口类都需要定义入口方法,入口方法是必须定义的。
各接口对应的入口方法名对应如下:

登录验证接口:check    
支付通知接口:payNotice    
特殊订单接口:deal

对于 代码兼容性 列出的SDK插件,需要另行定义列表中不同于上述名称的入口方法。

注释

通常情况下,应该多写点注释,这不仅可以向那些缺乏经验的程序员描述代码的流程和意图, 而且当你几个月后再回过头来看自己的代码时仍能帮你很好的理解。 注释并没有强制规定的格式,但是我们建议以下的形式。
DocBlock 风格的注释,写在类、方法和属性定义的前面,可以被 IDE 识别:


   /**
    * Super Class
    *
    * @author  Author Name
    * @link    http://example.com
    */
   class Super_class {    
 
   /**
    * Encodes string for use in XML
    *
    * @param   string  $str    Input string
    */
   function xml_encode($str)

   /**
    * Data for class manipulation
    *
    * @var array
    */
   public $data = array();

TRUE、FALSE 和 NULL

TRUE 、 FALSE 和 NULL 这几个关键字全部使用大写。
错误的:

if ($foo == true)
$bar = false;
function foo($bar = null)

正确的:

if ($foo == TRUE)
$bar = FALSE;
function foo($bar = NULL)

逻辑操作符

谨慎使用 || 操作符,它在一些设备上看不清(可能看起来像是数字 11), 使用 && 操作符比使用 AND 要好一点,但是两者都可以接受。 另外,在 ! 操作符的前后都应该加一个空格。

对返回值进行比较以及类型转换

有一些PHP函数、渠道在失败时返回 FALSE ,但是也可能会返回 "" 或 0 这样的有效值, 这些值在松散类型比较时和 FALSE 是相等的。所以当你在条件中使用这些返回值作比较时, 一定要使用严格类型比较,确保返回值确实是你想要的,而不是松散类型的其他值。
在检查你自己的返回值和变量时也要遵循这种严格的方式,必要时使用 === 和 !== 。

调试代码

不要在你的提交中包含调试代码,就算是注释掉了也不行。 像 var_dump() 、 print_r() 、 die() 、 exit()、 Console::init() 、 Console::debug() 这样的函数,都不应该包含在你的代码里, 除非它们用于除调试之外的其他特殊用途。

文件中的空格

PHP起始标签的前面和结束标签的后面都不要留空格,输出是被缓存的,所以如果你的文件中有空格的话, 这些空格会在服务器输出它的内容之前被输出,从而会导致错误。

PHP版本兼容性

您的插件代码需要兼容PHP 5.3.X。
另外,不要使用那些需要额外安装的库的 PHP 函数,除非你能给出当该函数不存在时,有其他的函数能替代它。

换行

文件必须使用 Unix 的换行格式保存。这对于那些在 Windows 环境下的开发者可能是个问题, 但是不管在什么环境下,你都应该确认下你的文本编辑器已经配置好使用 Unix 换行符了。具体请参考本页开头文件格式一节。

代码缩进

中括号和小括号内的空格

私有方法和变量

那些只能在内部访问的方法和变量,例如供共有方法使用的那些工具方法或辅助函数,应该以下划线开头。

public function convert_text()
private function _convert_text()