BIWEB-PHP-编码规则.doc

BIWEB PHP 编码规则
2005-6-29制定
V1.0
Arthur
2007-10-10调整
V1.1
Arthur
2009-12-28新拟定
V2.0
Arthur
2010-1-15更新
V2.1
Arthur
目录
BIWEB PHP 编码规则 1
目标 2
内容： 2
一．命名规则 2
二．目录结构 2
三．文件 3
3.1文件编码 3
3.2文件名 3
3.3 文件头 4
四．函数 6
4.1 函数名 6
4.2 函数头 6
五. 常量 6
六．变量 6
七. 排版 7
7.1养成缩排习惯 7
7.2 {}编码规则 7
八． 注意单引号和双引号的区别，尽量多使用单引号双引号内可以直接写变量 7
九.数据编码 7
十.输入输出值检查 8
十一.SQL 语句 8
十二.字符集设置charset=UTF-8 8
十三．空行的使用 8
十四．Smarty 8
十五. 模板的结构 9
十六. 模板图片调用规则 9
十七. 模板文件存放规则 9
十八. 各功能栏目中变量的设定规则 9
十九. 区块Block的应用 9
二十 配置变量的命名规则 10
二十一 底层主类调用 10
二十二 底层扩展函数调用 10
二十三BIWEB文件调用关系 11
二十四 URL静态优化配置 11

二十五 URL静态优化调用文件 11
二十六 纯静态文件生成 12
二十七BIWEB虚拟主机的完整配置文件 12

目标
如果您已经决定向BIWEB贡献代码，请详细阅读以下规范，并严格遵守。这样在保证您代码可读性的同时还可以大大减少我们的工作量。
内容：
一．命名规则
目录、文件、函数、变量的命名要以英文进行命名，不使用汉字，名称要有意义，更要容易理解，其中目录名、文件名都采用小写字母，这样在linux下不会产生因为大小写而出现找不到链接的错误；而函数名的首字母要大写；变量命名由多个单词组成的时候，每个单词首字母大写，对于变量名的前面要加小写变量类型前缀，前缀后面的首字母大写变量类型前缀参看第5点变量命令规则。
二．目录结构
按照功能设置目录，并根据目录的层级可以了解各功能的相互关系。
网站总体架构说明

 整站配置文件目录

 新闻栏目目录

 新闻栏目配置文件目录

 新闻栏目后台管理目录

三．文件
3.1文件编码
请调整您的编辑器文件编码为**UTF-8**，并**关闭UTF-8 BOM**的功能。请不要使用windows自带的记事本编辑项目文件。
3.2文件名
类文件：类名称.class.php
例如：database.class.php 调用mysql类文件
webservice.class.php 网站service类文件
smtp.class.php 发送smtp的类文件
注：公共类文件存放在web_common5.8目录中
所有文件以Unicode的方式存储，文件名全部小写

函数文件：××.func.php
××.func.js
注：website_common/php_includes/_common 目录的公共函数文件，前面必须加g，其他目录的函数文件不需加g
例如：gcommon_func.php 公共函数文件
gjs_func.js 公共js文件
input_func.php 非公共函数文件
包含文件：该文件非独立使用，被其他程序所包含的文件。文件名.inc.php
3.3 文件头
每个文件都需要写文件头 file header: (Sample)
to the named scale
*
* @access public
* @author Jimmy Boy
* @copyright Jimmy Boy Inc
* @version 1.0
* @param numeric $temp temperature
* @param string $scale scale to convert to; must be either C or F
* @return numeric $newTemp converted temperature
*/
/**
* new temperature value after conversion
*
* @access private
* @var numeric
*/
function convertTemp($temp, $scale) {

var $newTemp;

if ($scale == 'F'){
$newTemp = ((9/5)*$temp)+32;
}else{
$newTemp = (5/9)*($temp-32);
}
return $newTemp;
}
?>
註解是遵循PhpDocumentor的規則，PhpDocumentor标记的基本元素名为DocBlock，即一个多行注解块，它可以出现在任何PHP construct，类，或者函数之前，如下所示：
/**
 * text here
 *
 */
在这一DocBlock之中，PhpDocumentor接收三种类型的选项：一个简短描述，一个比较长的描述，以及一系列以@符号前缀的特定标签，如表C所示。这些标签为可选择性，然而它能够使最终文档变得更加精确。以下为PhpDocumentor支持的常用标签：
@access: 函数为私有或为公共
@author: 函数作者的名字和邮箱地址
@version: 函数的版本数
@copyright: 函数的版权(如果需要)
@package: 函数从属的封装包
@param: 函数变量，包括类型及其描述
@return: 从一个函数中返回值，包括类型及其描述
@var: 变量类型和描述，包括函数中的类变量或本地变量
@global: 变量类型和描述，包括函数中的公共变量
@see: 与元素相关的其它名称
@todo: 仍然需要完成的选项

对于使用哪些标签及在哪使用，没有固定的规则。然而通用规则为只使用相关标签以避免最后文档的混乱。例如，可以使用用于函数和方法的@param和 @return，但使用这两个标签来操作变量就不适合。
四．函数
4.1 函数名
函数名使用骆驼法则，首字母小写。公共函数，请前面加G，并在函数头中写上调用的例子。（注意大小写保持一致）
例如：GSendBulkEmail($From,$FromName,$toAddress,$strSubject,$strBody,$strHTML,$smtp_host =SMTP_SERVER)
4.2 函数头 
每个函数都需要写函数头：function header: (Sample) 詳細的請參照上面的文件頭，簡單例子如下：
/**
* new temperature value after conversion
*
* @access private
* @var numeric
/

五. 常量
所有字母大写，前加上双下划线，单词之间用下划线分割。
define('__TYPECHO_DB_ADAPTER', 'Mysql');

六．变量
变量第一次使用要有注释, 变量前后加空格
$a = $a + 1
$a = $a + ($b +$c) // ( ) 和变量相邻不用加空格
注：习惯用 isset 来判断变量类等是否创建

一般变量命名规则
使用骆驼法则，首字母小写。变量必须使用下列前缀。请尽可能遵守，以便开发员一目了然。
Data Type
Prefix
Example
Boolean
is
isValid
Date (and Time)
dt
dtStart
Integer
int
intCounter
Double
dbl
dblNumber
String
str
strDepartmentName
Object
obj
objPrint
Array
arr
arrSetNo

七. 排版
7.1养成缩排习惯
BIWEB项目中的代码缩进使用的是【制表符(tab) 】，而不是4个空格(space)，制表符为4个空格宽，不是2个空格，请务必调整。
EditPlus2.1.2简体中文版，可以使用 【TAB】or【Shift + TAB】,
UltraEdit v11版，有标记对应隐藏功能，方便调试。
7.2 {}编码规则
尽量使用紧凑布局原则，如下：
if ($iBook == 1) {
$iNumber = 1;
} else{
$iNumber = 2;
}
对于单行语句体，请跟其尾部，如下：
if ($iBook == 1) $iNumber = 1;
else $iNumber = 2;
八． 注意单引号和双引号的区别，尽量多使用单引号双引号内可以直接写变量
$str = “Menber”; $str = “$str Key”;
九.数据编码
页面传输数据必要时要编码，如有中文时、参数之间有空格时、有特殊字符时；
Ex：传递 url 时： 使用 urlencode
传递二进制流时：使用GEnc()/GDec()
十.输入输出值检查
完整的值域检查会减少很多事后的bugs
Ex：程序一开始检查所有的request 变量是否有效，过程中的输出(DB, Screen…)检查；
建議每做一個功能改動，就測試是否正確，保證每個改動的功能正確才能更加有效的完成整個功能需求。
十一.SQL 语句
1. 语法规范
SQL 语句一定要写明具体的字段名，不用使用*
select * from tblTable
应该写为:
SELECT `Name`, `Age` FROM `tblTable`

Insert into tblTable values(‘White jane’, 24)
应该写为:
INSERT INTO `tblTable` ( `Name`, `Age`) VALUES (‘White jane’, 24)

十二.字符集设置charset=UTF-8
记得加：
这样比较不会造成一些网页编辑器的乱码或是IE的误判语系问题，以及达到整合多语使用环境。 注：该条标记请写在模板中。数据库字符集也应设置为UTF-8模板中的文字要正常显示保存模板的时候也必须使用utf-8格式
十三．空行的使用
使用空行可以分割代码的不同区块。但建议具体请各位自己把握。请不要使用每行一个空行编码风格，也不要乱空行，尽量保持一个重要区块一个空行的良好习惯。
十四．Smarty
Smarty tag:
Smarty 模板目录: templates/
Smarty 模板編譯目录: compile/
編譯目錄結構應該和模板目錄結構保持一致，並且設置為777可寫權限
十五. 模板的结构
templates/目录下的每一个目录为独立的一套模板，BIWEB程序中设定的模板文件为frame.html所以所有的模板中include的文件必须从frame.html所在位置开始计算。theme目录是里面的title.html、head.html和foot.html是模板的重要组成部分。其他的各个html模板仅仅是frame.html中MAIN部分。
十六. 模板图片调用规则
由于image和css都是在模板目录中所调用，所以模板中图片调用必须使用/images/调用图片，css亦是。前台模板提交数据时，必须在提交路径前加上网站前缀变量。例如：

/plug-in/commonJS/common.js" type="text/javascript">

十七. 模板文件存放规则
BIWEB的模板的命名是对应栏目程序文件命名的。
例如：prdocut/include/index.inc.php对应的模板就是 templates/模板名/product/index.html

模板目录下存放的模板文件只能是跟栏目程序对应的文件，模板中的block，存放在该模板目录中的block目录中。切记block模板文件不能放在跟主模板文件同目录下。
例如：首页调用了最新产品的block（product/block/top_index.php），其模板是存放在templates/模板名/product/top_index.html

有时整个栏目都拥有相同的左边栏，我们会把左边栏做成一个被所有该栏目模板共同调用的模板文件。该模板起名为_left.html或者_right.html。命名为一个下划线开头，表明该文件是不独立使用的，需要被当前目录下的文件所包含的。
例如：模板目录product/有index.html、list.html、detail.html，这三个模板文件都有共同的左边栏，为了便于修改，我们就在模板目录product/建立一个_left.html，该_left.html中存放着共同的左边拦的html代码，供三个模板文件所引用。
十八. 各功能栏目中变量的设定规则
BIWEB快速开发之所以能够实现，有很大程度上是取决于变量的命名。所以每个功能栏目的主程序传送给smarty的变量取名都是通用变量名。例如：分类是$arrMType，列表是$arrInfoList，详细是$arrData，图片显示路径变量是$FileCallPath。在主栏目中我们尽量不要使用跟栏目相关的变量传给smarty。例如$arrPorductList。

十九. 区块Block的应用
区块block就是跨栏目可被多次调用的程序功能模块，也就是block目录中程序都是在其他主程序调用的，而其自身并不独立使用。BIWEB的每个功能栏目都非常的独立，对于在其他栏目需要实现该栏目的功能，就必须在该栏目的block目录做成block程序供其他栏目调用，例如：网站首页需要实现一个最新产品的功能，那么就要调用产品目录下的block中的最新产品区块来实现。我们一般取名为top_index.php，top为置顶或最新的意思，而index代表为首页使用的。Block中的变量命名一定要跟栏目相关，千万不能使用通用变量名，因为Block会被其他栏目调用，如果用了通用变量名就会跟主栏目的变量名起冲突。区块中变量命名为了替换方便，全部采用小写。例如：正规写法$arrProductList，区块写法$arrproductList。

二十 配置变量的命名规则
BIWEB有很多的配置数组，全局配置数组会在之前变量类型前缀之后加一个大写的G，如果是栏目配置数组则会在变量前缀之后加一个大写的M。具体的配置数组如下：
$arrGWeb
全站基本参数配置数组
$arrGPdoDB
数据库配置数组
$arrGCache
静态页面缓存参数
$arrGSmarty
Smarty配置参数
$arrGMeta
网页优化配置数组
$arrGPage
翻页参数
$arrGPic
上传图片配置参数
$arrGKeywords
关键字广告配置数组
$arrGIllegal
非法关键字配置数组
$arrGModule
底层可选功能模块数组
$arrMOutput
栏目Smarty输出数组
$arrMType
栏目文件分类数组
二十一 底层主类调用
底层主函数是保存在web_common5目录下的php_common.php，类名是ArthurXF，主类实现了BIWEB基本上通用的功能，遇到一个新功能开发的时候，可以先到底层类中查找相关的函数没必要立即动手新写一个函数。底层类的调用都是通过调用全局配置文件global.inc.php自动调用了。可以直接使用，同时底层类直接调用了如下常用类，这些常用类可直接实例化使用。
smarty.class.php
Smarty扩展类
pdodb.class.php
PDO数据库类
check.class.php
常用函数封装类
gdimage.class.php
GD图形处理类
pdo_page.class.php
PDO翻页处理类
cache.class.php
静态页面处理类

二十二 底层扩展函数调用
BIWEB使用了PHP5的魔法函数__autoload调用底层的扩展功能类，其$arrGModule配置保存在/config/module.inc.php中。对于底层扩展类可以不用先包含，而是由魔法函数自动包含，但是一定要注意的，就是数组中的键名一定要和调用的类名统一。
例如：调用ip查地域功能类
类名为QQWry，调用数组键名一定要对应，$arrGModule['QQWry']，要注意区分大小写。

二十三BIWEB文件调用关系

二十四 URL静态优化配置
BIWEB可以实现伪静态和纯静态两种URL优化，伪静态又因为有些IIS不支持pathinfo，所以BIWEB会做成两种伪静态链接。
1.
^\.]*.$">
ForceType application/x-httpd-php
。
2.
二十五 URL静态优化调用文件
一般URL静态优化仅仅是针对前台页面的，管理后台就没必要在URL优化了。所以BIWEB一般会针对前台的程序文件做优化。BIWEB在功能栏目中提供了的index.php和index，其实这两个文件都不是真实的程序文件，真实的程序文件在include\index.inc.php。为什么要这么做呢？因为纯正的伪静态链接会访问没有后缀名的index文件，而不太纯正的伪静态链接会访问index.php。所以我们会这样制作。如果你自己制作的新文件要使用静态链接优化的话，就也要做两个文件哦。伪静态的URL在模板中制作需要使用BIWEB特有的smarty函数
例如：不会生成纯静态页面的，伪静态优化链接

这个函数会自动在链接前加上网站前缀，并且会自动判断生成纯正的或者不纯正的伪静态链接，亦或者生成没有优化的链接。特别注意：后面的参数是可以多个的。跟正常的参数一样用&符号连接即可。
例如：会生成静态页面的静态化链接
about' cache = '1'}?>
其实写法跟上面的没什么区别，就是多了一个cache=1，这个参数表明该链接会生成纯静态页面。

因为BIWEB很可能会被放在一个目录下使用，所以BIWEB系统的链接都不直接写常规链接的，都是调用这个函数处理的，这样可以确保你的网站链接不会错误。

二十六 纯静态文件生成
BIWEB只要系统设定了生成静态页面，那么BIWEB就会在信息发布的同时自动生成静态页面，同时会把相关的缓存文件都清除。BIWEB采用了404独立生成静态文件系统，所以静态文件存放的文件夹HTML下所有的文件均可删除，当访问者访问该页面时，如果发现这个文件不存在，将会通过BIWEB自定义的404文件自动生成纯静态文件。如有的虚拟主机不支持自定义404文件，那么必须在后台关闭纯静态页面生成选项，才能正常的使用BIWEB。
需要开通自定义404的话，必须在apache的配置文件中加入
ErrorDocument 404 /plug-in/404/404.php
ErrorDocument 301 /plug-in/404/404.php
二十七BIWEB虚拟主机的完整配置文件

# ServerAdmin webmaster@dummy-
ErrorDocument 404 /plug-in/404/404.php
ErrorDocument 301 /plug-in/404/404.php

ForceType application/x-httpd-php

DocumentRoot D:\AppServ\

php_flag engine off

php_flag engine off

ServerName
ServerAlias
# ErrorLog logs/dummy--error_log
# CustomLog logs/dummy--access_log common

你可以自由替换其中的域名，如果使用繁简转换电话，必须保留big5的域名，此域名是用来访问繁体中文网站的，中间有两段php_flag engine off，这两段是封掉上传目录的PHP执行，避免黑客利用漏洞把PHP上传到服务器来执行。
14