PHP Coding Standard

o $ name!';
echo $hello; //will out: hello $var
$hello = ‘hello’ . $name //will out: hello john
Sql string
Sql string là chuỗi dùng để truy vấn câu lệnh sql. Một số các quy tắc cho Sql string sau:
Viết hoa các Sql keywork.
Ngắt xuống dòng đối với các câu lệnh dài.
Ví dụ
// Short SQL Query
$sql = "SELECT name FROM people WHERE id = '" . $id . "'";
// Long SQL Query
14/24
“SELECT 
people_id
, people_name
, people_phone
FROM 
people 
WHERE 
name = 'Fred'
OR name = 'Susan'
. “ORDER BY name ASC ”
      . “LIMIT 20”;
Nên viết thế này 
ngắn gọn dễ nhìn 
hơn(với sql long)
PHP CODING STANDARD v.1.0
$sql =  “SELECT people_id”
. “ , people_name” 
. “ , people_phone”
. “FROM people ”
. “WHERE name = 'Fred' ”
. “ OR name = 'Susan' ”
. “ORDER BY name ASC ”
      . “LIMIT 20”;
Việc ngắt mỗi trường thành một dòng rất dễ nhìn đồng thời dễ cho việc sửa đổi câu lệnh, chỉ 
cần copy một dòng và sửa lại tên trường là có thể cho hiển thị thêm các trương khác trong câu 
truy vấn. Đồng thời việc để dấu phẩy (‘,’) đằng trước tên trường giúp cho việc copy thêm trường 
hiển thị vào cuối lệnh SELECT được thuận tiện hơn, không xảy ra lỗi.
Ví dụ:
// Long SQL Query
$sql =  “SELECT people_id, ”
. “ people_name, ” 
. “ people_phone”
. “ people_name, ”  //copy from line 2 made error
. “FROM people ”;
4.3 Mảng
Chỉ mục của mạảng không được phép là số âm và default là từ 0.
Các giá trị của mạảng cách nhau bởi dấu phẩy và nên tuân theo quy tắc văn bản: them một 
khoảng trắng sau dấu phẩy
Ví dụ:
$sampleArray arr_eg = array(1, 2, 3, 'Zend', 'Studio');
Nên khai báo mạảng tường minh chỉ mục và giá trị theo định dạng sau:
$ arr_eg sampleArray = array('firstKey'  => 'firstValue'
      , 'secondKey' => 'secondValue'
      , 'thirdKey' => 'thirdValue'
      , 'fourthKey' => 'fourthValue');
15/24
“SELECT 
people_id
, people_name
, people_phone
FROM 
people 
WHERE 
name = 'Fred'
OR name = 'Susan'
. “ORDER BY name ASC ”
      . “LIMIT 20”;
PHP CODING STANDARD v.1.0
4.4 Lớp
Khai báo lớp
Lớp được đặt tên theo đúng naming conventions.
Trước khai báo class luôn đặt một khối comment (xem cụ thể 4.7).
Mỗi file chỉ nên chứa 1 class và không chứa các dòng code ngoài class.
/**
 * Documentation Block Here
 */
class SampleClass
{
    // entire content of class
    // must be indented four spaces
}
Biến
Tên biến trong class được đặt theo đúng naming conventions.
Khai báo phạm vi biến phải tường minh. Không dùng var mà phải chỉ rõ private, protected hay 
public.
Biến phải được khai báo trước mọi phương thức.
Nên có khối comment trước mỗi biến quan trọng.
/**
 * Class Docblock Here
 */
class Test
{
    /**
     * Variable Docblock Here
     */
    private var $mAbc = null;
    /**
     * Variable Docblock Here
     */
    protected var $mCdf = null;
16/24
PHP CODING STANDARD v.1.0
    /**
     * Variable Docblock Here
     */
    public $mPub = null;
}
4.5 Hàm và phương thức
Tên hàm và phương thức đặt theo đúng naming conventions.
Khai báo phạm vi hàm và phương thức phải tường minh. Chỉ rõ private, protected  hay public.
Trước mỗi khai báo hàm (phương thức) đặt một khối comment về hàm (phương thức) đó.
Các function cách nhau một dòng trắng.
/**
 * Class Docblock Here
 */
class Buxa_Foo
{
    /**
     * Method Docblock Here
     */
    public function SampleMethod($a)
    {
        // Entire content of function must be indented four spaces
    }
    /**
     * Method Docblock Here
     */
    protected function AnotherMethod()
    {
        // ...
    }
    /**
     * Method Docblock Here
     */
    private function AnotherNewMethod(Array $b)
    {
17/24
PHP CODING STANDARD v.1.0
        // ...
    }
}
4.6 Câu lệnh điều khiển
4.7 If / Else / Elseif
Khối điều kiện đặt trong cặp ngoặc tròn “()” và có một khoảng trắng trước từ khóa if để dễ nhìn.
Cặp {} được trình bày như ví dụ dưới:
if (condition)                 // Comment
{
}
else if (condition)          // Comment
{
}
else                             // Comment
{
}
Nếu bạn sử dụng câu lệnh “if … then” thì là 1 ý kiến hay và bạn luôn luôn phải có 1 block khác 
cho việc tìm ra những trường hợp không thực hiện được. Hãy đưa vào 1 thông báo khi có hành 
động không chính xác sảy ra. 
1.1 Switch
Khối điều kiện đặt trong cặp ngoặc tròn “()” và có một khoảng trắng trước từ khóa “switch”.
Tất cả nội dung bên trong mệnh đề “switch” đều phải thụt vào 1 tab. Nội dung bên dưới mỗi 
mệnh đề  “case” đều phải thụt vào thêm 1 tab nữa
Cấu trúc “default” không được phép bỏ qua trong câu lệnh “switch”.
Chú ý: đôi khi sẽ rất hữu ích khi ta viết câu lệnh “case” trong những trường hợp tiếp sau không 
gồm “break” hoặc “return”. Để phân biệt  những trường hợp này với các lỗi, mỗi mệnh đề “case” 
phải bao gồm cả những dòng chú thích
18/24
PHP CODING STANDARD v.1.0
Ví dụ
switch ($sampleNumber) 
{
 case 1:
 // ...
 break;
 case 2:
 // ...
 break;
 default:
 // ...
 break;
}
1.2 Continue,break and ?:
Continue và Break 
Hạn chế tối đa việc dùng continue và break. Thường các khối lệnh dùng continue và break đều 
có thể khử bằng việc sử dụng các câu lệnh lặp và rẽ nhánh.
Nếu sử dụng continue và break phải comment về flow. 
?: 
Vấn đề là mọi thường cố gắng và nhồi nhét quá nhiều đoạn code giữa dấu ? và dấu :. Sau đây 
là 1 số quy tắc: 
• Đặt điều kiện chính nổi bật hơn để thiết lập những đoạn code khác
• Nếu có thể, các actions cho việc kiểm tra nên xây dựng theo function đơn giản. 
• Đặt những action nay trong câu lệnh "Then" và  "Else" trong các dòng tách biệt nếu 
không thì có thể đặt chúng rõ ràng trong cùng 1 dòng. 
Ví dụ
   (condition) ? funct1() : func2();
   hoặc đặt như sau nếu quá dài
   (condition)
      ? long statement
      : another long statement;
19/24
PHP CODING STANDARD v.1.0
4.8 Cách trình bày cho các khối 
• Các khối nên được trình bày cho đúng canh lề level. 
• Rõ ràng. 
• Tương tự các block khởi tạo của biến cũng nên được xếp thành bảng. 
• Dấu hiệu ‘&’ nên được sử dụng liền sát với kiểu , không liền sát với tên. 
Ví dụ
   var        $mDate
   var&      $mrDate
   var&      $mrName
   var        $mName
   $mDate      = 0;
   $mrDate     = NULL;
   $mrName   = 0;
   $mName     = NULL;
Mỗi phát biểu trên 1 hàng 
Sau tên biến là dấu tab(4 khoảng trắng – vì nhiều biến có tên dài) sau đó tới dấu = và tiếp theo 
là 1 khoảng trắng rồi đến gtrị.
Nên để duy nhất 1 phát biểu trên 1 hàng trừ khi những phát biểu đó có liên quan chặt chẽ với 
nhau. 
4.9 Comment
1.3 Documentation Format
Tất cả các khối chú thích (“docblock”) phải tương thích định dạng phpDocumentor. Đặc tả 
chuẩn chú thích của phpDocument không nằm trong phạm vi của tài liệu này, các thông tin chi 
tiết có thể tìm hiểu tại  Sau đây là một số chuẩn quy định trong tài liệu này:
20/24
   $mDate      = 0;
Yêu cầu:
Sau tên biến là dấu tab(4 khoảng trắng – vì 
nhiều biến có tên dài) sau đó tới dấu = và tiếp 
theo là 1 khoảng trắng rồi đến gtrị.
PHP CODING STANDARD v.1.0
1.4 Files
Tất cả các file chứa mã PHP đều phải có khối chú thích đầu file, tối thiểu gồm các trường thông 
tin sau:
/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * LICENSE: Some license information
 *
 * @copyright 2006 BuxaprojectsXCMS
 * @license  Buxa
XCMS Licence 1.0
 * @version $Id$1.0
 * @link 
id=c81e728d9d4c2f636f067f89cc14862c
ckage/PackageName
 * @since File available since Release 1.0
 */
1.5 Lớp
Tất cả các lớp chứa mã PHP đều phải có khối chú thích đầu class, tối thiểu gồm các trường 
thông tin sau:
/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @copyright 2006 XCMS2006 Buxaprojects
 * @license XCMS 
Buxa Licence 1.0
 * @version Release: @package_version1.0@
 * @link http
id=c81e728d9d4c2f636f067f89cc14862c://dev.buxaprojects.com/packag
e/PackageName
 * @since Class available since Release 1.0
 */
1.6 Hàm
Tất cả các hàm bao gồm cả phương thức của lớp đều phải có chú thích gồm tối thiểu các 
trường sau: Description, param(nếu có), Return Values.
/**
 * Short description for the function
 *
 * Long description for the function (if any)...
 *
 * @param array $array Description of array
 * @param string $string Description of string
21/24
PHP CODING STANDARD v.1.0
 * @return boolean
 */
Nếu hàm throw an exeption phải sử dụng thêm trường “@throws”
@throws Exception_Class_Name Description
1.7 Biến
Các biến thuộc class phải có khối chú thích miêu tả và kiểu biến
/**
 * Description for the variable
 * @var array
 */
1.8 Comment Keywords 
• :TODO: topic
Có rất nhiều vấn đề ở đây. 
• :BUG: [bugid] topic
Vấn đề về các lỗi, giải thích chúng. 
• :KLUDGE:
Khi bạn làm một việc gì đó rất tệ và bạn cần giải thích bạn làm cách nào để nó tốt hơn 
nếu bạn có thêm 1 chút thời. 
• :TRICKY:
Nói cho mọi người biết đoạn code sau đây rất tồi, vì vậy đừng sửa chữa nó nếu không 
suy nghĩ. 
• :WARNING:
Thận trọng với 1 cái gì đó. 
• :PARSER:
Đôi khi bạn cần phải phân tích lại vấn đề, hãy lấy dẫn chứng bằng tài liệu, vấn đề sẽ 
được giải quyết thấu đáo. 
• :ATTRIBUTE: value
Theo cách thông thường của một thuộc tính nhúng trong chú thích. Bạn có thể tự tạo 
ra các thuộc tính và chúng sẽ rất thú vị. 
Ví dụ
   // :TODO: tmh 960810: possible performance problem
22/24
PHP CODING STANDARD v.1.0
   // We should really use a hash table here but for now we'll
   // use a linear search.
   // :KLUDGE: tmh 960810: possible unsafe type cast
   // We need a cast here to recover the derived type. It should
   // probably use a virtual method or template.
23/24
PHP CODING STANDARD v.1.0
5 PHỤ LỤC
5.1 Các tài liệu tham khảo
[1] – PHP Coding Standard (Fredrik Kristiansen / DB Medialab, Oslo 2000­2003) ­ 
[2] – PHP coding guidelines – BuxaProjects ­ 
[3] ­ PHP coding guidelines – Zend Frameword ­ ­
standard.html 
[4] – PHP Documentor ­  
24/24