Coding convention là tập hợp những quy ước cụ thể khi viết code mà lập trình viên cần tuân theo. Việc tuân thủ những quy ước này sẽ giúp code dễ đọc, dễ quản lý.bảo trì, nâng cấp.

Tùy công ty sẽ có những quy chuẩn coding convention khác nhau nhưng hầu hết sẽ dựa trên các chuẩn phổ biến trên thế giới.

PHP có một chuẩn viết code là PSR. PSR là viết tắt của từ PHP Standards Recommendation. Hiện tại thì có 5 chuẩn từ PSR-0 đến PSR-4 và 2 chuẩn phổ biến nhất đó là PSR1 và PSR2:

• PSR1: https://www.php-fig.org/psr/psr-1/
• PSR2: https://www.php-fig.org/psr/psr-2/
• PSR4: https://www.php-fig.org/psr/psr-4/

Cú pháp: Ký tự đầu tiên của từ đầu tiên viết thường, những ký tự đầu tiên của những từ tiếp theo viết hoa.

Ví dụ: productName, productPrice, thisIsTheNameFollowTheCamelCase

Cú pháp: viết hoa chữ cái đầu tiên của mỗi từ.

Ví dụ: ProductName, ProductPrice, ThisIsTheNameFollowThePascalCase

Cú pháp: Tất cả các chữ cái đều viết thường, và các từ cách nhau bởi dấu gạch dưới. Ví dụ: product_name, product_price, this_is_the_name_follow_the_snake_case

Tuỳ vào mỗi ngôn ngữ lập trình và cộng đồng định nghĩa, ta sẽ lựa chọn cú pháp phù hợp.

• Tên lớp: đặt theo PascalCase.
• Tên biến, tên hàm: đặt theo camelCase hoặc snake_case.
• Hằng số: đặt theo UPPER_CASE. VD: CLICK_COUNTER.
• Tên biến, tên lớp: thường là danh từ, cụm danh từ hoặc tính từ. VD: UserModel, userName, downloadCounter, isDownloaded.
• Tên hàm thường bắt đầu bằng động từ. VD: getUserName, setUserName, increaseDownloadCounter.
• Tên phải có nghĩa, không được đặt tên kiểu viết tắt và không sai chính tả. VD: uName, pName, idl, a, a1, doFA.
• Tránh đặt những tên quá chung chung, tối nghĩa. VD: top, doIncrease, getAll.

Số lượng dòng code trong hàm/lớp, số lượng hàm trong lớp, số lượng lớp trong gói phải giữ ở một giới hạn nhất định, và nên giữ càng ít càng tốt.

• Hàm không nên quá 30 dòng.
• Lớp không nên vượt quá 500 dòng.
• Một hàm không được vượt quá 5 tham số, nên giữ ⇐ 3.
• Một hàm chỉ làm duy nhất 1 việc, trong trường hợp cần thiết, có thể cho phép làm 2 việc, tuy nhiên tên hàm phải nói rõ điều này. VD: increaseDownloadCounterAndSaveToDatabase.
• Khi khai báo biến, một dòng chỉ chứa một biến.
• Một dòng không nên dài quá 80 ký tự.
• Các câu lệnh lồng nhau tối đa 4 cấp.

• Nếu có dấu “,” thì xuống hàng sau dấu “,”.
• Xuống hàng trước toán tử + - …
• Nếu có nhiều cấp lồng nhau, thì xuống hàng theo từng cấp.
• Dòng xuống hàng mới thì được bắt đầu ở cùng cột với đoạn lệnh cùng cấp ở trên.

• Một class chỉ nên giữ 1 trách nhiệm duy nhất để tránh phình to về sau.
• Có thể thoải mái mở rộng 1 class, nhưng hạn chế sửa đổi bên trong class đó: mỗi khi muốn thêm chức năng, nên viết class mới mở rộng class cũ (bằng cách kế thừa hoặc sở hữu class cũ) không nên sửa đổi class cũ.
• Thay vì dùng 1 interface lớn, ta nên tách thành nhiều interface nhỏ, với nhiều mục đích cụ thể: Nguyên lý này khá dễ hiểu. Hãy tưởng tượng chúng ta có 1 interface lớn, khoảng 100 methods. Việc implements sẽ khá cực khổ, ngoài ra còn có thể dư thừa vì 1 class không cần dùng hết 100 method. Khi tách interface ra thành nhiều interface nhỏ, gồm các method liên quan tới nhau, việc implement và quản lý sẽ dễ hơn.
• Hạn chế viết code trong controller thay vì đó nên viết vào trong các service để đơn giản controller
• Các module nên viết theo package nếu cần thiết thì require vào composer và có thể dùng chung với các project khác
• Các pattern trong ứng dụng thì sử dụng Repository, Dependency injection giao tiếp bằng interface.

Đây là các chuẩn dùng để viết code, có một vài quy tắc đơn giản như sau:

• Code phải được viết trong cặp thẻ <?php ?> và nên sử dụng cặp thẻ ngắn <?= ?> thay cho echo.
• Mỗi một file PHP chỉ nên làm 1 nhiệm vụ duy nhất, tránh chồng chéo (gọi là side effect).
• Code chỉ được sử dụng UTF-8 không có BOM (BOM - Byte Order Mark là các chuỗi EF,BB,BF ở đầu file cho phép phần mềm biết đây là 1 file UTF-8).
• Namespace phải tuân theo chuẩn PSR “autoloading” (PSR-0, PSR-4).
• Tên class phải viết theo quy tắc PascalCase( hay tên khác StudlyCaps).
• Các hẳng số phải viết hoa tất cả các chữ, cách nhau bằng dấu gạch chân.
• Tên phương thức viết theo quy tắc camelCase.

• Code phải tuân thủ PSR-1 & PSR-0.
• Sử dụng 4 khoảng trắng(spaces) để thụt dòng, tuyệt đối không dùng tab (bạn có thể khai báo trong công cụ lập trình để khi ấn tab nó tương đương với việc thụt vào 4 spaces).
• Trên 1 dòng không vượt quá 120 kí tự, tốt nhất nên nhỏ hơn hoặc bằng 80 kí tự, không nên có kí tự trắng ở cuối dòng.
• Phải có 1 dòng trắng sau khi khai báo namespace và phải có 1 dòng trắng sau các khai báo use.
• Thẻ đóng và mở của 1 hàm {} phải nằm riêng biệt trên một dòng.
• Trước thẻ mở và đóng hàm {} thì không được có 1 dòng trắng.
• Phải dùng dấu nháy đơn ‘ để khai báo chuỗi không chứa biến, nếu chuỗi có chứa kí tự ‘ thì dùng dấu nháy kép để bọc bên ngoài (chúng ta rất hay nhầm vấn đề này).
• Dùng dấu . để nối chuỗi, chú ý trước và sau dấu chấm . phải có khoảng trắng. Nếu chuỗi quá dài thì tách làm nhiều dòng và dấu chấm được đặt đầu dòng ngang với dấu bằng.
• Các tham số truyền vào hàm phải có 1 dấu cách trước dấu phẩy, bạn có thể tách thành nhiều dòng nhưng phải thụt lề 1 đơn vị.
• Đối với khối lệnh switch case thì case phải lùi 4 khoảng trắng so với switch, và các lệnh trong case cũng phải lùi 4 khoảng trắng so với case. Phải có từ khóa break hoặc return, trong trường hợp nào không có thì phải comment
• Nếu phải sử dụng abstract và final hay static để khai báo hàm thì bạn phải khai báo theo thứ tự.
• Phải có 1 khoảng trắng trước và sau phép toán, khi ép kiểu thì phải có 1 khoảng trắng ngăn cách giữa kiểu dữ liệu và biến được ép kiểu.

PHP Code Sniffer (hay còn gọi là phpcs) là một cộng cụ phục vụ lập trình viên trong việc check các coding convention.

PHP Code Sniffer bao gồm 2 tập lệnh PHP:

• Tập lệnh phpcs là tập lệnh chính mã hóa các tệp PHP, Javascript, CSS để phát hiện các vi phạm coding convention.
• Tập lệnh phpcbf để tự động sửa các phần code vi phạm tiêu chuẩn coding convention.

Đây là 1 công cụ phát triển thiết yếu để đảm bảo mã của bạn sạch sẽ, tuân thủ các coding convention mà bạn không phải mất thời gian rà soát lại code để check.

Package: https://packagist.org/packages/squizlabs/php_codesniffer

Sử dụng:

$ ./vendor/bin/phpcs -i
The installed coding standards are PEAR, Zend, PSR2, MySource, Squiz, PSR1 and PSR12
$ ./vendor/bin/phpcs -h
$ ./vendor/bin/phpcbf -h

Chuẩn PEAR là chuẩn mặc định mà PHP Code Sniffer dùng để kiểm tra.

Kiểm tra 1 file có tuân thủ chuẩn PEAR hay không:

$ ./vendor/bin/phpcs src/Commands/ModuleMakeCommand.php
FILE: /Sources/Packages/laravel-module/src/Commands/ModuleMakeCommand.php
--------------------------------------------------------------------------------------------------------------------
FOUND 57 ERRORS AND 27 WARNINGS AFFECTING 79 LINES
--------------------------------------------------------------------------------------------------------------------
   2 | ERROR   | [ ] Missing file doc comment
  11 | ERROR   | [x] There must be exactly one blank line before the tags in a doc comment
  12 | ERROR   | [ ] Missing @category tag in class comment
  12 | ERROR   | [ ] Missing @author tag in class comment
  12 | ERROR   | [ ] Missing @license tag in class comment
  12 | ERROR   | [ ] Missing @link tag in class comment

Kiểm tra toàn bộ thư mục:

TungNT:laravel-module tungnt$ sudo ./vendor/bin/phpcs src/
 
FILE: /Sources/Packages/laravel-module/src/Stubs/configs/example.stub.php
-------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-------------------------------------------------------------------------
 2 | ERROR | Missing file doc comment
-------------------------------------------------------------------------

Kiểm tra theo chuẩn khác, sử dụng –standard. Ví dụ:

TungNT:laravel-module tungnt$ sudo ./vendor/bin/phpcs --standard=PSR2 src/
 
FILE: /Sources/Packages/laravel-module/src/Stubs/configs/example.stub.php
-------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-------------------------------------------------------------------------
 5 | ERROR | [x] Expected 1 newline at end of file; 0 found
-------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-------------------------------------------------------------------------

Tự động sửa các vi phạm Theo chuẩn:

$ ./vendor/bin/phpcbf --standard=PSR2 src/
 
PHPCBF RESULT SUMMARY
--------------------------------------------------------------------------------------------
FILE                                                                        FIXED  REMAINING
--------------------------------------------------------------------------------------------
/Sources/Packages/laravel-module/src/Stubs/configs/example.stub.php         1      0
/Sources/Packages/laravel-module/src/ModuleGeneratorServiceProvider.php     3      0
--------------------------------------------------------------------------------------------
A TOTAL OF 4 ERRORS WERE FIXED IN 2 FILES
--------------------------------------------------------------------------------------------
 
Time: 129ms; Memory: 6MB
 
$ vendor/bin/phpcs --standard=ruleset.xml tests/
 
FILE: /Sources/Packages/codesniffer/tests/helpers.php
-----------------------------------------------------------------------
FOUND 0 ERRORS AND 3 WARNINGS AFFECTING 3 LINES
-----------------------------------------------------------------------
 10 | WARNING | Line longer than 80 characters; contains 94 characters
 21 | WARNING | Line longer than 80 characters; contains 99 characters
 32 | WARNING | Line longer than 80 characters; contains 90 characters
-----------------------------------------------------------------------
 
Time: 103ms; Memory: 6MB
$ vendor/bin/phpcs --standard=src/Standards/OneSite/ tests/

Config Standars:

TungNT:codesniffer tungnt$ vendor/bin/phpcs --standard=OneSite tests/
ERROR: the "OneSite" coding standard is not installed. The installed coding standards are PEAR, Zend, PSR2, MySource, Squiz, PSR1 and PSR12
TungNT:codesniffer tungnt$ sudo ./vendor/bin/phpcs --config-show
Password:
Using config file: /Sources/Packages/codesniffer/vendor/squizlabs/php_codesniffer/CodeSniffer.conf

TungNT:codesniffer tungnt$ sudo ./vendor/bin/phpcs --config-set installed_paths src/Standards/OneSite/
Using config file: /Sources/Packages/codesniffer/vendor/squizlabs/php_codesniffer/CodeSniffer.conf

Config value "installed_paths" added successfully
TungNT:codesniffer tungnt$ sudo ./vendor/bin/phpcs --config-show
Using config file: /Sources/Packages/codesniffer/vendor/squizlabs/php_codesniffer/CodeSniffer.conf

installed_paths: src/Standards/OneSite/
TungNT:codesniffer tungnt$ cat /Sources/Packages/codesniffer/vendor/squizlabs/php_codesniffer/CodeSniffer.conf
<?php
 $phpCodeSnifferConfig = array (
  'installed_paths' => 'src/Standards/OneSite/',
)
?>TungNT:codesniffer tungnt$ vendor/bin/phpcs -i
The installed coding standards are PEAR, Zend, PSR2, MySource, Squiz, PSR1, PSR12 and OneSite
TungNT:codesniffer tungnt$ sudo ./vendor/bin/phpcs --config-delete src/Standards/OneSite/
TungNT:codesniffer tungnt$ ./vendor/bin/phpcs --standard=OneSite tests/

FILE: /Sources/Packages/codesniffer/tests/helpers.inc
-----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
-----------------------------------------------------------------------
  8 | ERROR | Variable "_suffix" must not contain a leading underscore
 10 | ERROR | Variable "_suffix" must not contain a leading underscore
-----------------------------------------------------------------------

Time: 72ms; Memory: 6MB