Bài viết được sự cho phép của tác giả Lê Chí Dũng
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ưngKHÔ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.
Đoạn mã PHP sau đúng chuẩn, đã khai báo thì không gồm hiệu ứng phụ
Xem ngay tin tuyển dụng PHP lương cao trên TopDev
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:
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:
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àmPHẢ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ớiclass
. - 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ướcvisibility
, cònstatic
phải đi sau.
Ví dụ:
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 ,
.
IF, ELSE, SWITCH, CASE
WHILE
FOR
TRY,CATCH
Trình bày Closure
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ụ:
2. Package
Các Interface và Class được mô tả chi tiết trong gói psr/log.
3. PsrLogLoggerInterface
4. PsrLogLoggerAwareInterface
5. PsrLogLogLevel
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:
- 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:
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:
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:
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) PsrHttpMessageRequestInterface và giao diện thông điệp đáp trả (response) PsrHttpMessageResponseInterface. Cả hai loại thông điệp này đều kế thừa từ một giao diện chung có PsrHttpMessageMessageInterface.
PsrHttpMessageMessageInterface CÓ THỂ
được viết trực tiếp, nhưng bạn NÊN
có kế từ cho PsrHttpMessageRequestInterface và PsrHttpMessageResponseInterface.
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ụ:
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ụ:
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ụ:
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/