PHP CODING STANDARD

Một coding standard tốt hết sức quan trọng cho bất kỳ một dự án nào, nhất là đối với các project nhiều người.

Coding standard góp một phần lớn tron việc đảm bảo chất lượng source code, ít lỗi và dễ bảo trì, sửa chữa.

I. FILE FORMATTING

PHP Tags

• PHP code phải sử dụng tag đầy đủ <?php ?> (Không nên dùng tag <? ?> hoặc short-echo <?= ?> tags)

• Trong một file chỉ bao gồm code PHP thì không được viết tag đóng ?>.

1. Canh lề - Indenting

Code không dùng tab, mà phải sử dụng 4 dấu cách làm indent.

2. Lines

Việc giới hạn số ký tự trên 1 dòng code nhằm giúp cho lập trình viên nhìn code được dễ dàng. Một dòng code nên chỉ có 80 ký tự và tối đa là 120 ký tự.

3. Namespace và tên Class

Namespaces và tên classes phải tuân theo quy chuẩn "autoloading" của PSR

Điều này có nghĩa là mỗi class phải được viết vào một file, và phải có ý nhất 1 level trong namespace.

• Tên class phải được viết dưới dạng StudlyCaps.

• Chữ cái đầu tiên viết hoa, các từ được kết hợp bởi chữ cái la tinh viết liền nhau. Được phân biệt với nhau bằng chữ viết hoa.

Code với phiên bản PHP 5.3 trở lên phải dùng đúng namespaces.

<?php
// PHP 5.3 and later:
namespace VendorModel;

class Foo
{
}

Code với phiên bản 5.2.x trở xuống nên dùng pseudo-namespace với Vendor_ là prefix.

<?php
// PHP 5.2.x and earlier:
class Vendor_Model_Foo
{
}

II. Class Constants, Properties, và Methods

Constants

Constants của class phải được viết hoa toàn bộ và sử dụng gạch dưới ngăn cách giữa các từ. Ví dụ:

<?php
namespace VendorModel;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '27/08/2015';
}

Properties

Bộ quy tắc này không đưa ra quy định hay gợi ý về việc nên viết properties như thế nào, theo dạng $StudlyCaps,$camelCase, hay $$nder_score. Dù sử dụng quy tắc đặt tên nào đi chăng nữa thì nó cần phải được thực hiện thống nhất trong một vendor, package, class, method ..

<?php
namespace VendorPackage;

class ClassName
{
    public $foo = null;
}

• Tên property không nên được prefix bởi dấu gạch dưới _ để biểu thị tính protected hay private.

Method

Tên Method phải được viết dưới dạng camelCase.

• Các method phải được khai báo với các từ : privated, protected, public. Không được bỏ trống

• Static method phải được khai báo với theo độ ưu tiên của visibility trong script

public    static foo() { ... }
private   static bar() { ... }
protected static goo() { ... }

public function functionName()
{
    return $this->varName;
}

Hàm, method và sử dụng

Tham số của hàm phải được cách bởi 1 kí tự khoảng trắng . Ví dụ sau gọi hàm 3 tham số

getContent(1, 2, 3);

Nếu muốn truyền tham trị, thì phải đặt & ở trước biến trong hần khai báo hàm , không được khi sử dùng hàm mới thêm dấu & .

Câu lệnh điều khiển

If/ Else/ Elseif

• Các câu điều kiện phải có 1 khoảng trắng ở giữa từ “if”, “elseif” và ngoặc mở “(“ . Thêm 1 khoảng trắng nữa giữa ngoặc đóng “)” và ngoặc cong “{“.

• Ở trong ngoặc đơn “()”, giữa 2 bên của các toán tử so sánh phải có khoảng trắng để dễ đọc .

• Ngoặc cong mở “{“ phải viết chung hàng với lệnh if . Ngoặc cong đóng phải ở hàng của riêng nó

// hợp lệ
if ($a != 2){
    $a = 2;
}
// Không hợp lệ
if ($a != 2)
{
    $a = 2;}

• Với những lệnh if mà có thêm else, elseif thì phải tuân theo ví dụ sau

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

Switch

• Tương tự, giữa chữ “switch” và ngoặc mở “(“ phải có 1 khoảng trắng, và giữa ngoặc đóng “)” và “{“ phải có 1 khoảng trắng nữa .

• Ngoặc cong mở “{“ phải nằm chung hàng với if , và ngoặc cong đóng “}” phải nằm ở hàng của riêng nó

• Tất cả các nội dung bên trog switch phải được thục dòng 4 khoảng trắng . Và nội dung của mỗi “case” phải được thục dòng thêm 4 khoảng trắng nữa !

switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}

while, do while

Một câu lệnh while được viết như sau. Hãy chú ý vào vị trí của dấu ngoặc đơn, khoảng trắng và dấu ngoặc nhọn.

<?php
while ($expr) {
    // structure body
}

Tương tự như vậy, một câu lệnh do while được viết như sau. Hãy chú ý vào vị trí của dấu ngoặc đơn, khoảng trắng và dấu ngoặc nhọn.

<?php
do {
    // structure body;
} while ($expr);

for

Một câu lệnh for được viết như sau. Hãy chú ý vào vị trí của dấu ngoặc đơn, khoảng trắng và dấu ngoặc nhọn.

<?php
for ($i = 0; $i < 10; $i++) {
    // for body
}

** foreach**

Một câu lệnh foreach được viết như sau. Hãy chú ý vào vị trí của dấu ngoặc đơn, khoảng trắng và dấu ngoặc nhọn.

<?php
foreach ($iterable as $key => $value) {
    // foreach body
}

try, catch

<?php
try {
    // try body
} catch (FirstExceptionType $e) {
    // catch body
} catch (OtherExceptionType $e) {
    // catch body
}

Một block try catch được viết như sau. Hãy chú ý vào vị trí của dấu ngoặc đơn, khoảng trắng và dấu ngoặc nhọn.

Inline Documentation

Files:

Trong mỗi file chứa PHP code, chúng ta phải có 1 block ở trên đầu file để miêu tả về file . Bạn có thể làm như sau :

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * LICENSE: Some license information
 *
 * @copyright  2006 Zend Technologies
 * @license    [url]http://www.zend.com/license/3_0.txt[/url]   PHP License 3.0
 * @version    $Id$
 * @link       [url]http://dev.zend.com/package/PackageName[/url]
 * @since      File available since Release 1.2.0
 */

Classes

Tương tự như vậy, các class cũng cần phải có

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @copyright  2006 Zend Technologies
 * @license    [url]http://www.zend.com/license/3_0.txt[/url]   PHP License 3.0
 * @version    Release: @package_version@
 * @link       [url]http://dev.zend.com/package/PackageName[/url]
 * @since      Class available since Release 1.2.0
 */

Functions

Với mỗi hàm, bao gồm cả các hàm dc định nghĩa trong class, cần có 1 block gồm:

Miêu tả cơ bản về hàm

• Tất cả các biến của hàm
• Tất ca các giá trị trả về của hàm
• Nếu 1 hàm hay 1 method trong class có “throw exception” thì dùng @throw

/**
 * Does something interesting
 *
 * @param  Place    $where  Where something interesting takes place
 * @param  integer  $repeat How many times something interesting should happen
 * @throws Some_Exception_Class If something interesting cannot happen
 * @return Status
 */
public function doSomethingInteresting(Place $where, $repeat = 1)
{
    // implementation...
}

Require và include

Include, include_once, require, require_once hok nên dùng () .

 Hợp lệ
 include 'header.php';
 Không hợp lệ
 include ('header.php');

Các tài liệu tham khảo

http://www.php-fig.org/psr/psr-1/

http://phpdoc.org/