Hướng dẫn viết code PHP chuẩn – PSR tiêu chuẩn khi lập trình PHP

ledung

8 years ago

Mục lục

PSR là gì?
1. PSR-1 Basic Coding Standard (Tiêu chuẩn cơ bản khi viết code PHP)
2. PSR-2 Coding Style Guide (Tiêu chuẩn trình bày code)
3. PSR-3 Logger Interface (Giao diện logger)
4. PSR-4 Autoloading Standard (Tiêu chuẩn về tự động nạp)
5. PSR-6 Caching Interface (Giao diện về Caching)
6. PSR-7 HTTP Message Interface (Tiêu chuẩn Giao diện thông điệp HTTP)
7. Các tiêu chuẩn khác

Lý do bạn nên viết code theo tiêu chuẩn PSR:

PSR là tiêu chuẩn code được áp dụng vào các dự án lớn hoặc framework PHP (Cakephp, Composer, Phalcon, Magento,…).
Viết code chuẩn giúp bạn và đồng đội dễ dàng hiểu code của nhau.
Thống nhất chung về cách thức viết code, tổ chức các class,…
Dễ dàng đọc, hiểu, trình bày khỏi mất công bản thân “tự chế” kiểu code không giống ai.

PSR là gì?

PSR có nghĩa là PHP Standards Recommendations, nó là tiêu chuẩn được khuyến nghị áp dụng khi lập trình PHP và được các lập trình viên, tổ chức chấp nhận sử dụng.

PSR được soạn thảo, đánh giá và khuyến khích sử dụng bởi một nhóm chuyên gia PHP những người phát triển cho các Framework và hệ thống PHP phổ biến (thành viên PSR).

PSR bao gồm 7 phần (http://www.php-fig.org/psr/) từ PSR-1, PSR-2, PSR-3, PSR-4, PSR-6, PSR-7. Các tiêu chuẩn thành phần hoàn chỉnh của PSR đó gồm:

Basic Coding Standard: Tiêu chuẩn cơ bản khi viết code PHP
Coding Style Guide: Tiêu chuẩn trình bày code
Logger Interface: Giao diện logger
Autoloading Standard: Tiêu chuẩn về tự động nạp
Caching Interface: Giao diện về Caching
HTTP Message Interface: Tiêu chuẩn Giao diện thông điệp HTTP

1. PSR-1 Basic Coding Standard (Tiêu chuẩn cơ bản khi viết code PHP)

PRS-1 là các nguyên tắc mỗi lập trình viên PHP nên theo để đảm bảo code dễ đọc, bảo trì, và dễ sử dụng lại cũng như chia sẻ cho đồng đội.

1. Nguyên tắc chung nhất khi code PHP

Các file code PHẢI sử dụng thẻ <?php hoặc <?
File code PHP sử dụng encode: UTF-8 without BOOM
Các Files NÊN hoặc dùng để khai báo các thành phần PHP (các lớp, hàm, hằng …) hoặc dùng với mục đích làm hiệu ứng phụ (như include, thiết lập ini cho PHP …), nhưng KHÔNG NÊN dùng cả 2 cùng lúc trong 1 file (Xem ví dụ này ở Ví dụ 1)
Các Namespace và classes PHẢI theo chuẩn “autoloading” PSR: [PSR-4]
Tên lớp PHẢI có dạng NameClass (chữ không nameclass, Nameclass, namClass …)
Hằng số trong class tất cả PHẢI viết HOA và chia ra bởi dấu _ (ví dụ ahdsoft_member).
Tên phương thức của lớp PHẢI ở dạng camelCase (từ đầu viết thường, ví dụ: helloWorld).

Ví dụ 1)

File PHP viết không theo chuẩn, trộn lẫn lung tung hiệu ứng phụ và khai báo các đối tượng ngôn ngữ PHP.

<?php
// hiệu ứng phụ: đổi thiết lập ini
ini_set('error_reporting', E_ALL);

// hiệu ứng phụ: nạp file vào
include "file.php";

// hiệu ứng phụ: xuất dữ liệu
echo "<html>\n";

// khai báo hàm
function foo()
{
    // function body
}

Đoạn mã PHP sau đúng chuẩn, đã khai báo thì không gồm hiệu ứng phụ

<?php
// declaration
function foo()
{
    // function body
}

if (! function_exists('bar')) {
     //Khai báo hàm
    function bar()
    {
        // function body
    }
}

2. Các Namespace và tên Class

Namespace và Lớp PHẢI theo chuẩn “autoloading” PSR: [PSR-4]

Có nghĩa là mỗi lớp được khai báo trên mỗi file PHP riêng và namespace tối thiểu có một cấp, cấp đầu là tên vendor.

Tên lớp lại PHẢI đúng dạng NameClass.

Ví dụ đúng chuẩn:

<?php
namespace Vendor\Model;

class Foo
{
}

3. Hằng, Thuộc tính và Phương thức của lớp

Hằng theo chuẩn ở trên, tất cả PHẢI viết hoa, phân cách từ bởi _

Ví dụ hằng đúng chuẩn:

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

2. PSR-2 Coding Style Guide (Tiêu chuẩn trình bày code)

PSR-2 sẽ tạo cho bạn thói quen viết code đúng chuẩn, dễ đọc, đẹp.

Tổng quan về trình bày code PHP

Code PHẢI tuân thủ PSR-1
Code PHẢI sử dụng 4 ký tự space để lùi khối (không dùng tab)
Mỗi dòng code PHẢI dưới 120 ký tự, NÊN dưới 80 ký tự.
PHẢI có 1 dòng trắng sau namespace, và PHẢI có một dòng trắng sau mỗi khối code.
Ký tự mở lớp { PHẢI ở dòng tiếp theo, và đóng lớp } PHẢI ở dòng tiếp theo của thân class.
Ký tự { cho hàm PHẢI ở dòng tiếp theo, và ký tự } kết thúc hàm PHẢI ở dòng tiếp theo của thân hàm.
Các visibility (public, private, protected) PHẢI được khai báo cho tất cả các hàm và các thuộc tính của lớp;
Các từ khóa điều khiển khối(if, elseif, else) PHẢI có một khoảng trống sau chúng; hàm và lớp thì KHÔNG ĐƯỢC làm như vậy.
Mở khối { cho cấu trúc điều khiển PHẢI trên cùng một dòng; và đóng khối này } với ở dòng tiếp theo của thân khối.
Hằng số true, false, null PHẢI viết với chữ thường.
Từ khóa extends và implements phải cùng dòng với class.
implements nhiều lớp, thì mỗi lớp trên một dòng
keyword var KHÔNG ĐƯỢC dùng sử dụng khai báo property.
Tên property KHÔNG NÊN có tiền tố _ nhằm thể hiện thuộc protect hay private.
Tham số cho hàm, phương thức: KHÔNG được thêm space vào trước dấu , và PHẢI có một space sau ,. Các tham số CÓ THỂ trên nhiều dòng, nếu làm như vậy thì PHẢI mỗi dòng 1 tham số.
abstract, final PHẢI đứng trước visibility, còn static phải đi sau.

Ví dụ:

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{
    public function sampleFunction($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // method body
    }
}

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // constants, properties, methods
}

Gọi phương thức và hàm

Khi gọi một hàm hay phương thức của lớp, KHÔNG ĐƯỢC có khoảng trắng giữa phương thức, hàm và toán tử và dấu ( đồng thời không được có khoảng trắng sau (. không có khoảng trắng trước ), như phần trên không được có khoảng trắng trước , nhưng PHẢI có khoảng trắng sau ,.

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

IF, ELSE, SWITCH, CASE

<?php
if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}

<?php
switch ($expr) {
    case 0:
        echo 'First case, with a break';
        break;
    case 1:
        echo 'Second case, which falls through';
        // no break
    case 2:
    case 3:
    case 4:
        echo 'Third case, return instead of break';
        return;
    default:
        echo 'Default case';
        break;
}

WHILE

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

FOR

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

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

TRY,CATCH

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

Trình bày Closure

<?php
$closureWithArgs = function ($arg1, $arg2) {
    // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

3. PSR-3 Logger Interface (Giao diện logger)

PSR-3 Logger Interface: trình bày về các thành phần cần phải có của một Logger (ghi lại dấu vết của ứng dụng).

1. Các đặc điểm kỹ thuật

LoggerInterface với 8 phương thức ghi log theo chuẩn RFC 5424 thương sẽ được chia thành key log: debug, info, notice, warning, error, critical, alert, emergency.
Mọi method chỉ chấp nhận một string tin nhắn, hoặc object dùng method a__toString() để chuyển tất cả sang tring.
Message phải chứa placeholders với implementors phải replace giá trị từ array.
Tên placeholders phải phù hợp với key log.
Tên placeholders phải được phân cách bằng dấu ngoặc nhọn { và dấu ngoặc nhọn }.
KHÔNG được chứa bất kỳ khoảng trắng giữa các ký tự tên placeholders.
chỉ NÊN gồm các ký tự A-Z, a-z, 0-9, dấu gạch dưới _, và thời gian,.. Việc sử dụng các ký tự khác thì để xem trong tương lai có được áp dụng không.Implementors CÓ THỂ sử dụng giữ chỗ để thực hiện các chiến lược thoát khác nhau và dịch các bản ghi để hiển thị. Người dùng KHÔNG NÊN pre-escape giá trị giữ chỗ vì họ không thể biết trong đó bối cảnh các dữ liệu sẽ được hiển thị.

Ví dụ:

/**
   * Interpolates context values into the message placeholders.
   */
  function interpolate($message, array $context = array())
  {
      // build a replacement array with braces around the context keys
      $replace = array();
      foreach ($context as $key => $val) {
          // check that the value can be casted to string
          if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) {
              $replace['{' . $key . '}'] = $val;
          }
      }

      // interpolate replacement values into the message and return
      return strtr($message, $replace);
  }

  // a message with brace-delimited placeholder names
  $message = "User {username} created";

  // a context array of placeholder names => replacement values
  $context = array('username' => 'bolivar');

  // echoes "User bolivar created"
  echo interpolate($message, $context);

2. Package

Các Interface và Class được mô tả chi tiết trong gói psr/log.

3. Psr\Log\LoggerInterface

<?php

namespace Psr\Log;

/**
 * Describes a logger instance
 *
 * The message MUST be a string or object implementing __toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context array can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Exception instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 */
interface LoggerInterface
{
    /**
     * System is unusable.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function emergency($message, array $context = array());

    /**
     * Action must be taken immediately.
     *
     * Example: Entire website down, database unavailable, etc. This should
     * trigger the SMS alerts and wake you up.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function alert($message, array $context = array());

    /**
     * Critical conditions.
     *
     * Example: Application component unavailable, unexpected exception.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function critical($message, array $context = array());

    /**
     * Runtime errors that do not require immediate action but should typically
     * be logged and monitored.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function error($message, array $context = array());

    /**
     * Exceptional occurrences that are not errors.
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things
     * that are not necessarily wrong.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function warning($message, array $context = array());

    /**
     * Normal but significant events.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function notice($message, array $context = array());

    /**
     * Interesting events.
     *
     * Example: User logs in, SQL logs.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function info($message, array $context = array());

    /**
     * Detailed debug information.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function debug($message, array $context = array());

    /**
     * Logs with an arbitrary level.
     *
     * @param mixed $level
     * @param string $message
     * @param array $context
     * @return null
     */
    public function log($level, $message, array $context = array());
}

4. Psr\Log\LoggerAwareInterface

<?php

namespace Psr\Log;

/**
 * Describes a logger-aware instance
 */
interface LoggerAwareInterface
{
    /**
     * Sets a logger instance on the object
     *
     * @param LoggerInterface $logger
     * @return null
     */
    public function setLogger(LoggerInterface $logger);
}

5. Psr\Log\LogLevel

<?php

namespace Psr\Log;

/**
 * Describes log levels
 */
class LogLevel
{
    const EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';
}

4. PSR-4 Autoloading Standard (Tiêu chuẩn về tự động nạp)

PSR-4 Autoloading Standard: trình bày về cách chỉ định ứng dụng tự động nạp (giống include, require) các file php, lớp, hàm khi nó cần dùng đến.

Các lớp có thể được load tự động khi dùng đến bằng cách sử dụng cơ chế autoload của PHP (http://php.net/autoload).

Để thống nhất và sử dụng dễ dàng, phù hợp với nhiều mã Autoload khác nên viết các lớp theo quy tắc sau:

* “lớp” ở đây ám chỉ cho: class, interface,traits

* Tên xác định đầy đủ của một lớp có dạng:

\<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>

Tên xác định đầy đủ PHẢI có một namespace gốc (hiểu là tên vendor)
Tên xác định đầy đủ có thể có một hoặc nhiều namespace con.
Tên đầy đủ nó phải có một tên lớp kết thúc (ClassName)

* Khi một nạp một file thì nó phải tương ứng với một tên xác định đầy đủ của lớp.

Mỗi tên xác định đầy đủ phải tương ứng với một cấu trúc thư mục
Tên lớp kết thúc tương ứng với tên file:

<ClassName>.php

Khi viết các lớp, theo quy tắc đó thì dễ dàng phát triển một bộ tự động nạp. Autoloader để khởi tạo ứng dụng.

Tham khảo mẫu Autoloader tự động đăng ký các lớp tự động tải vào khi dùng đến, với điều kiện các lớp viết theo PSR-4.

https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader-examples.md

Các Framework PHP phổ biến hầu hết theo chuẩn PSR-4, nên chúng đều có bộ Autoloader tương tự.

5. PSR-6 Caching Interface (Giao diện về Caching)

PSR-6 Caching Interface là tiêu chuẩn cần có của một bộ ứng dụng caching (lưu tạm dữ liệu và database, đĩa, RAM …)

Tham khảo thông tin tại đây

6. PSR-7 HTTP Message Interface (Tiêu chuẩn Giao diện thông điệp HTTP)

PSR-7 HTTP Message Interface là tiêu chuẩn về giao diện (thành phần cần có) của một ứng dụng sử dụng thông điệp HTTP (HTTP Message – request và respone), nó căn cứ vào các tiêu chuẩn RFC 7230, RFC 7231, RFC 3986.

Thông điệp HTTP là nền tảng của ứng dụng web. Các Web Browser và các trình khách HTTP như cURL tạo ra một thông điệp HTTP (HTTP request message), rồi gửi nó đến web server, server nhận được thông điệp (có thể hiểu là yêu cầu) đó, nó sẽ gửi về một thông điệp HTTP (HTTP Response message).

Cấu tạo các HTTP MESSAGE

Các HTTP message thường thì không được nhìn thấy, không cần phải hiểu bởi người dùng, nhưng với người phát triển web thì rất nên hiểu về cấu trúc để sử dụng chúng thi hành các tác vụ theo yêu cầu.

Mọi HTTP Request Message đều có dạng:

POST /path HTTP/1.1
Host: example.com

foo=bar&baz=bat

Dòng đầu tiên yêu cầu, theo thứ tự chứa thông tin: phương thức yêu cầu (POST,GET …), đích yêu cầu (thường là URI hoặc đường dẫn trên web), và phiên bản của giao thức HTTP. Theo sau là các dòng HTTP header nếu nó, một dòng trống, cuối cùng là nội dung message.

Mọi HTTP Response Message đều có dạng:

HTTP/1.1 200 OK
Content-Type: text/plain

This is the response body

Dòng đầu là dòng trạng thái, theo thứ tự chứa phiên bản giao thức HTTP, mã trả về, và dòng mô tả mã. Tiếp theo là các dòng header nếu có, tiếp theo một dòng trống và cuối cùng là nội dung của HTTP Response Message.

Thuật ngữ gợi ý của PSR bạn lưu ý đó là: PHẢI, KHÔNG PHẢI, KHUYẾN NGHỊ … đó là các từ để căn cứ để bạn quyết định áp dụng phần nào của kỹ thuật vào ứng dụng.

Tiếp theo là các mô tả và namespace, interface class, các phương thức nên theo.

Các đặc điểm kỹ thuật về HTTP MESSAGE

1) Thông điệp (Message)

Một thông điệp HTTP có thể là yêu cầu gửi đi từ client hoặc thông điệp đáp trả từ server cho client. Như vậy cần phải có các lớp định nghĩa giao diện cho các thông điệp yêu cầu (request) Psr\Http\Message\RequestInterface và giao diện thông điệp đáp trả (response) Psr\Http\Message\ResponseInterface. Cả hai loại thông điệp này đều kế thừa từ một giao diện chung có Psr\Http\Message\MessageInterface.

Psr\Http\Message\MessageInterface CÓ THỂ được viết trực tiếp, nhưng bạn NÊN có kế từ cho Psr\Http\Message\RequestInterface và Psr\Http\Message\ResponseInterface.

2) Về các HTTP Header

Không phân biệt chữ hoa – thường

Các header được truy cập bởi tên của header đó trong bởi phương thức (withHeader) trong MessageInterface và phương thức này không phân biệt chữ hoa và chữ thường.

Ví dụ:

$message = $message->withHeader('foo', 'bar');

echo $message->getHeaderLine('foo');
// Outputs: bar

echo $message->getHeaderLine('FOO');
// Outputs: bar

$message = $message->withHeader('fOO', 'baz');
echo $message->getHeaderLine('foo');
// Outputs: baz

Bởi vì tên của header khi các server trả về có chữ hoa, chữ thường nên bạn PHẢI xử lý việc này trong hàm getHeaders().

Header nhiều giá trị

Thông lệ thì các header với nhiều giá trị vẫn được dùng, header có thể nhận được từ MessageInterface như là một mảng hoặc chuỗi. Sử dụng phương thức getHeaderLine() để nhận chuỗi có chứa giá trị phân cách bởi dấu ,. Sử dụng getHeader để nhận mảng tất cả giá trị header.

Ví dụ:

$message = $message
    ->withHeader('foo', 'bar')
    ->withAddedHeader('foo', 'baz');

$header = $message->getHeaderLine('foo');
// $header chứa: 'bar, baz'

$header = $message->getHeader('foo');
// ['bar', 'baz']

Host trong Header

Khi khởi tạo thông điệp Request PHẢI thiết lập Host header từ một URI nếu Host chưa được thiết lập. Hàm RequestInterface::withUri() làm điều này.

3) Streams – Các luồng

HTTP message chứa dòng bắt đầu, các header và body(nội dung). Phần body của thông điệp có thể rất nhở hoặc rất lớn. Nếu cố tình nhét tất cả dữ liệu vào body với kiểu chuỗi thì có vẻ dễ nhưng nhiều trường hợp ảnh hưởng nghiêm trọng đến bộ nhớ lưu giữ body. Khi dữ liệu lớn bạn sẽ sử dụng StreamInterface để diễn tả dữ liệu được đọc/ghi của body. Nhưng trường hợp này chuỗi dữ liệu body của thông điệp được sử dụng từ php://memory hoặc php://temp. (php://memory và php://temp là luồng chuẩn PHP xem tại php://)

Các Stream có thể dùng ba phương thức: isReadable(), isWritable(), isSeekable() để kiểm tra giới hạn của Stream (đọc, ghi, tìm).

Cuối cùng StreamInterface định nghĩa phương thức __toString() để nhận hoặc chuyển dữ liệu.

4) Request Targets và URIs

Request target(mục tiêu – đích của HTTP mgs) có thể ở dạng sau:

origin-form, chứa đường dẫn URL
absolute-form, chứa scheme và người gửi authority (“[user-info@]host[:port]”)
authority-form, chỉ chứa authority
asterisk-form, kiểm tra khả năng.

URL được định nghĩa bởi UriInterface, nó cung cấp __toString() để lấy URI. Nhận request target bằng phương thức getRequestTarget().

Ví dụ:

$request = $request
    ->withMethod('OPTIONS')
    ->withRequestTarget('*')
    ->withUri(new Uri('https://example.org/'));

5) Server-side Request – các request tại server

PHP cung cấp các biến toàn cục:

$_COOKIE, truy cập các cookie HTTP
$_GET, truy cập các tham số của chuỗi query (query trong url)
$_POST, truy cập các tham số urlencoded được chuyển đến bởi HTTP POST
$_FILES, chứa thông tin mô tả về các file được upload
$_SERVER, truy cập các biến môi trường CGI/SAPI, chứa nhiều thứ gồm request method, scheme, URI, header.

ServerRequestInterface mở rộng từ RequestInterface cung cấp lớp trừu tượng bao học hết các biến toàn cục trên, nó thêm một property là “attributes” dùng truy cập các thông tin.

6 Uploaded files – các file upload

ServerRequestInterface có phương thức getUploadedFiles() để nhận một cây mô tả file upload, mà mỗi lá của cây là một UploadedFileInterface. Có các phương thưc để làm việc với file, moveTo($targetPath) , _uploaded_file()

Chuẩn giao diện thông điệp HTTP bắt đầu được cung cấp bởi hầu hết các Framework PHP phổ biến. Trong tiêu chuẩn này gợi ý xây dựng các Interface, Method, Atribute để trừu tượng hóa HTTP Message.

Gợi ý này được đóng gói và được nhiều Framework làm theo, bạn lấy Package này tại https://github.com/php-fig/http-message

Các Framework xây dựng sẵn cho bạn theo PSR-7

Symfony : http://symfony.com/blog/psr-7-support-in-symfony-is-here

Zend Framework : https://zendframework.github.io/zend-expressive/

Laravel : https://laravel.com/docs/5.1/requests

7. Các tiêu chuẩn khác

PHPDoc Standard (PSR-5), Huggable Interface(PSR-8), Security Disclosure(PSR-9), Security Advisories(PSR-10),Container Interface(PSR-11),Extended Coding Style Guide(PSR-12),Hypermedia Links(PSR-13). Bạn có thể tham khảo tại http://www.php-fig.org/psr/