开始

遵守良好的开发规范更易于维护，阅读。请开发人员理解并遵守以下规范。

文件格式

常规

对于只包含有 PHP 代码的文件，结束标志（?>）是不允许存在的，PHP自身不需要（?>）, 这样做, 可以防止它的末尾的被意外地注入。

缩进

使用Tab缩进并将其定义为4个空格的宽度。编辑器推荐使用NetBeans。编辑器-》格式设置如图：

行的最大长度

一行 80 字符以内是比较合适的。

就是说，我们应当努力在可能的情况下保持每行代码少于 80 个字符，在有些情况下，长点也可以, 但最多为 120 个字符。 NetBeans 里有参考线，以不超过这行参考线为宜。

文件名

类文件名使用大驼峰风格，即每个单词的首字母大写并连在一起。

只有字母字符可用，空格是绝对不允许的。

视图文件使用小驼峰。即首个单词小写。

包含任何 PHP 代码的任何文件应当以 .php 扩展名结尾。

以下是一些可用的例子：

命名约定

类

使用驼峰风格，无空格。如果不是单词而是单词缩写，则可以都是大写。如以下这个例子是可以接受的。

class DashboardBaseController extends ICController

函数和方法

函数名只包含字母字符，下划线是不允许的。

函数名总是以小写开头，当函数名包含多个单词，每个子的首字母必须大写，这就是所谓的 “驼峰” 格式。

一般鼓励使用冗长的名字，函数名应当长到足以说明函数的意图和行为。

这些是可接受的函数名的例子：

function fetchOnlineStatusByUid(){}
function deleteBySession{}

对于面向对象编程，实例或静态变量的访问器总是以 get 或 set 为前缀。

全局函数 (如：floating functions ) 允许但大多数情况下不鼓励，建议把这类函数封装到静态类里。

变量

变量只包含字母字符，下划线不接受。

在类或对象中的变量，声明为 private 的， 名称的首字符必须是一个单个的下划线，这是唯一的下划线在类中的用法。

像函数名（见上面）一样，变量名总以小写字母开头并遵循 “驼峰式” 命名约定。

一般鼓励使用冗长的名字，这样容易理解代码，知道把数据存到哪里。除非在小循环里，否则不鼓励使用简洁的名字如 $i 和 $n 。

如果一个循环超过 20 行代码，索引的变量名必须有个具有描述意义的名字。

常量

常量包含字母字符和下划线。

常量名的所有字母必须大写。

常量中的单词必须以下划线分隔，例如可以这EMBED_SUPPRESS_EMBED_EXCEPTION

但不许这样 EMBED_SUPPRESSEMBEDEXCEPTION

类常量必须通过 const 定义为类的成员，在类中强烈不推荐使用 define 定义的全局常量。

编码风格

字符串

字符串文字

当字符串是文字(不包含变量)，应当用单引号来括起来：

$a = 'Example String'; // 包含单引号（'）的字符串文字

当文字字符串包含单引号就用双引号括起来，特别在 SQL 语句中有用 ( 注：SQL语句的关键字建议为大写以便区分 )：

$sql = "SELECT `id`, `name` FROM `people` WHERE `name`='Fred' OR `name`='Susan'";
// 在转义单引号时，上述语法是首选的，因为很容易阅读。

变量替换

推荐使用以下这个形式：

$greeting = "Hello {$name}, welcome back!";

为保持一致，这个形式不允许：

$greeting = "Hello ${name}, welcome back!";

字符串连接

字符串必需用 . 操作符连接，在它的前后加上空格以提高可读性：

$company = 'IBOS' . ' ' . 'Company';

当用 . 操作符连接字符串，鼓励把代码可以分成多个行，也是为提高可读性。在这些例子中，每个连续的行应当由 whitespace 来填补，例如 . 和 = 对齐：

$sql = "SELECT `id`, `name` FROM `people` " 
 . "WHERE `name` = 'Susan' " 
 . "ORDER BY `name` ASC ";

数组

数字索引数组

索引不能为负数，建议数组索引从 0 开始。

当用 array 函数声明有索引的数组，在每个逗号的后面间隔空格以提高可读性：

$sampleArray = array(1, 2, 3, 'IBOS', 'Inc');

可以用 array 声明多行有索引的数组，在每个连续行的开头要用空格填补对齐：

$sampleArray = array (
        1, 2, 3, 'Zend', 'Studio', 
        $a, $b, $c, 
        56.44, $d, 500
);

关联数组

当用声明关联数组，我们鼓励把代码分成多行，在每个连续行的开头用空格填补来对齐键和值：

$sampleArray = array (
        'firstKey'  => 'firstValue', 
        'secondKey' => 'secondValue'
);

类的补充

类的声明

每个类必须有一个符合 PHPDocumentor 标准的文档块。

类中所有代码必需用一个Tab的缩进。

每个 PHP 文件中只有一个类。

放另外的代码到类里允许但不鼓励。在这样的文件中，用两行空格来分隔类和其它代码。

类成员变量

变量的声明必须在类的顶部，在方法的上方声明。

不允许使用 var ，要用 private、 protected 或 public。 直接访问 public 变量是允许的但不鼓励，最好使用访问器 （setter/getter）。

强烈反对使用全局函数。

控制语句

使用 if and elseif 的控制语句在条件语句的圆括号前后都必须有一个空格。

在圆括号里的条件语句，操作符必须用空格分开，鼓励使用多重圆括号以提高在复杂的条件中划分逻辑组合。

前花括号必须和条件语句在同一行，后花括号单独在最后一行，其中的内容用一个 Tab 缩进。

if ( $a != 2 ) { 
    $a = 2; 
}

对包括 elseif 或 else 的 if 语句，和 if 结构的格式类似， 下面的例子示例 if 语句， 包括 elseif 或 else 的格式约定：

if ( $a != 2 ) { 
    $a = 2; 
} else { 
    $a = 7; 
} 

if ( $a != 2 ) { 
    $a = 2; 
} elseif ( $a == 3 ) { 
    $a = 4; 
} else { 
    $a = 7; 
}

在有些情况下， PHP 允许这些语句不用花括号，但在 IBOS 代码标准里，它们（if、 elseif 或 else 语句）必须使用花括号。

elseif 是允许的但强烈不鼓励，我们支持 else if 组合。

Switch

在 switch 结构里的控制语句在条件语句的圆括号前后必须都有一个单个的空格。

switch 里的代码必须有一个 Tab 的缩进，在 case 里的代码再缩进一个 Tab。

switch ( $numPeople ) { 
    case 1: 
        break; 

    case 2: 
        break; 

    default: 
        break; 
}

switch 语句应当有 default。

注： 有时候，在跳到下个case的case语句中不写 break or return 很有用。

为了区别于 bug，任何 case 语句中，所有不写 break or return 的地方应当有一个

// break intentionally omitted

这样的注释来表明 break 是故意忽略的。

注释文档

格式

所有文档块 (docblocks) 必须和 phpDocumentor 格式兼容，phpDocumentor 格式的描述超出了本文档的范围，关于它的详情，参考：http://phpdoc.org/。

所有类文件必须在文件的顶部包含文件级 （file-level）的 docblock ，在每个类的顶部放置一个 class-level 的 docblock。

文件

每个包含 PHP 代码的文件必须至少在文件顶部的 docblock 包含这些 phpDocumentor 标签：

/**
* 继承到CController的IBOS controller文件.
*
* @author banyanCheung 
* @link http://www.ibos.com.cn/
* @copyright Copyright © 2008-2013 IBOS Inc
* 
*/

类

每个类必须至少包含这些 phpDocumentor 标签：

/** 
 * 类的简述 
 * 
 * 类的详细描述 （如果有的话）... ... 
 * 
 * @copyright  Copyright (c) 2008-2013 IBOS Inc. (http://www.ibos.com.cn) 
 * @version    $Id$ 
 * @link       http://www.ibos.com.cn/ 
 * @since      Class available since Release 1.0.0 
 * @deprecated Class deprecated in Release 1.0.0 
 */

函数

每个函数，包括对象方法，必须有最少包含下列内容的文档块（docblock）：

• 函数的描述
• 所有参数
• 所有可能的返回值

因为访问级已经通过 public、 private 或 protected 声明， 不需要使用 @access。 如果函数/方法抛出一个异常，使用 @throws 于所有已知的异常类：@throws exceptionclass [description]

/**
 * Ajax方式返回数据到客户端
 * @param mixed $data 要返回的数据
 * @param String $type AJAX返回数据格式
 * @return void
 */
protected function ajaxReturn( $data, $type = '' ) {}

参照

* @link http://www.ibos.com.cn/
* @copyright Copyright © 2008-2013 IBOS Inc
* @author banyanCheung 
*/

/**
* 全局控制器必须继承自CController
* @package application.core.controllers
* @todo 权限控制
* @version $Id$
*/
class ICController extends CController {

    /**
     * 默认编码
     */

    const CHARSET = CHARSET;

    /**
     * 默认Jsonp回调函数
     */
    const DEFAULT_JSONP_HANDLER = 'jsonpReturn';

    /**
     * 布局类型
     * @var string 
     */
    public $layout = '';

    /**
     * 当前模块可访问的静态资源文件路径
     * @var string 
     */
    private $_assetUrl = '';

    /**
     * 错误异常处理
     * @return void 
     */
    public function actionError() {
        $error = Yii::app()->errorHandler->error;
        if ( $error ) {
            if ( Yii::app()->request->isAjaxRequest ) {
                $this->ajaxReturn( $error['message'], 'EVAL' );
            } else {
                $this->render( 'error', array( 'error' => $error['message'] ) );
            }
        }
    }

    /**
     * 覆盖父类渲染视图方法，在视图变量处增加静态资源路径，合并语言包文件方法
     * @param string $view @see CController::render
     * @param array $data @see CController::render
     * @param $return @see CController::render
     */
    public function render( $view, $data = null, $return = false, $langSource = array( ) ) {
        if ( is_null( $data ) ) {
            $data = array( );
        }
        $data['assetUrl'] = $this->getAssetUrl();
        $data['lang'] = $this->loadLangSource( $langSource );
        return parent::render( $view, $data, $return );
    }

    /**
     * Ajax方式返回数据到客户端
     * @param mixed $data 要返回的数据
     * @param String $type AJAX返回数据格式
     * @return void
     */
    protected function ajaxReturn( $data, $type = '' ) {
        if ( empty( $type ) ) {
            $type = 'json';
        }
        switch ( strtoupper( $type ) ) {
            case 'JSON' :
                // 返回JSON数据格式到客户端 包含状态信息
                header( 'Content-Type:application/json; charset=' . self::CHARSET );
                exit( CJSON::encode( $data ) );
                break;
            case 'XML' :
                // 返回xml格式数据
                header( 'Content-Type:text/xml; charset=' . self::CHARSET );
                exit( xml_encode( $data ) );
                break;
            case 'JSONP':
                // 返回JSON数据格式到客户端 包含状态信息
                header( 'Content-Type:application/json; charset=' . self::CHARSET );
                $handler = isset( $_GET['callback'] ) ? $_GET['callback'] : self::DEFAULT_JSONP_HANDLER;
                exit( $handler . '(' . CJSON::encode( $data ) . ');' );
                break;
            case 'EVAL' :
                // 返回可执行的js脚本
                header( 'Content-Type:text/html; charset=' . self::CHARSET );
                exit( $data );
                break;
        }
    }

    /**
     * 获取控制器所属模块的静态资源发布文件夹
     * @param String $module 模块名
     * @return String 文件夹路径
     * @final
     * @throws EnvException 如果是初始化模块行为之前调用此方法,会抛出一个异常
     */
    protected final function getAssetUrl( $module = '' ) {
        if ( empty( $this->_assetUrl ) ) {
            if ( empty( $module ) ) {
                $module = Ibos::getCurrentModuleName();
                // 尽量不要在初始化模块行为时调用此方法 
                if ( is_null( $module ) ) {
                    throw new EnvException(
                        Ibos::lang( 'Cannot call this method until the module has been initialization', 'default' )
                    );
                }
            }
            $this->_assetUrl = Yii::app()->assetManager->getAssetsUrl( $module );
        }
        return $this->_assetUrl ;
    }

    /**
     * 加载当前模块下语言文件，为空则加载default,有多个则合并
     * @param array $langSource 要加载的语言包文件
     * @return array 合并后的语言数组
     */
    protected function loadLangSource( array $langSource ) {
        if ( empty( $langSource ) ) {
            $langSource[] = 'default';
        }
        $language = Yii::app()->getLanguage();
        $lang = array( );
        foreach ( $langSource as $source ) {
            $sourceLang = Yii::app()->getMessages()->loadMessages( Ibos::getCurrentModuleName() . 
            '.' . $source, $language );
            $lang = array_merge( $lang, (array) $sourceLang );
        }
        return $lang;
    }

}