Không dùng nữa - Kể từ 2019-08-10 PSR-2 đã được đánh dấu là không dùng nữa. PSR-12 hiện được khuyến nghị thay thế
Hướng dẫn này mở rộng và mở rộng trên PSR-1, tiêu chuẩn mã hóa cơ bản
Mục đích của hướng dẫn này là để giảm ma sát nhận thức khi quét mã từ các tác giả khác nhau. Nó làm như vậy bằng cách liệt kê một bộ quy tắc và kỳ vọng được chia sẻ về cách định dạng mã PHP
Các quy tắc phong cách ở đây bắt nguồn từ sự tương đồng giữa các dự án thành viên khác nhau. Khi các tác giả khác nhau cộng tác trong nhiều dự án, sẽ rất hữu ích khi có một bộ hướng dẫn được sử dụng trong tất cả các dự án đó. Do đó, lợi ích của hướng dẫn này không nằm ở bản thân các quy tắc, mà ở việc chia sẻ các quy tắc đó
Các từ khóa "PHẢI", "KHÔNG PHẢI", "BẮT BUỘC", "SẼ", "SẼ KHÔNG", "NÊN", "KHÔNG NÊN", "KHUYẾN NGHỊ", "CÓ THỂ" và "TÙY CHỌN" trong tài liệu này là
1. Tổng quan
Mã PHẢI tuân theo "hướng dẫn kiểu viết mã" PSR [PSR-1]
Mã PHẢI sử dụng 4 dấu cách để thụt lề, không phải tab
KHÔNG ĐƯỢC có giới hạn cứng về độ dài của dòng;
PHẢI có một dòng trống sau khai báo
3 và PHẢI có một dòng trống sau khối khai báobar[$arg1]; Foo::bar[$arg2, $arg3];
4bar[$arg1]; Foo::bar[$arg2, $arg3];
Dấu ngoặc mở cho lớp PHẢI ở dòng tiếp theo và dấu ngoặc đóng PHẢI ở dòng tiếp theo sau phần thân
Dấu ngoặc mở cho các phương thức PHẢI đi trên dòng tiếp theo và dấu ngoặc đóng PHẢI đi trên dòng tiếp theo sau phần thân
Khả năng hiển thị PHẢI được khai báo trên tất cả các thuộc tính và phương thức;
Từ khóa cấu trúc điều khiển PHẢI có một khoảng trắng sau chúng;
Dấu ngoặc mở cho cấu trúc điều khiển PHẢI đi trên cùng một dòng và dấu ngoặc đóng PHẢI đi trên dòng tiếp theo sau phần thân
Dấu ngoặc đơn mở cho cấu trúc điều khiển KHÔNG ĐƯỢC có khoảng trắng sau chúng và dấu ngoặc đơn đóng cho cấu trúc điều khiển KHÔNG ĐƯỢC có khoảng trắng phía trước
1. 1. Thí dụ
Ví dụ này bao gồm một số quy tắc bên dưới dưới dạng tổng quan nhanh
2. Chung
2. 1. Tiêu chuẩn mã hóa cơ bản
Mã PHẢI tuân theo tất cả các quy tắc được nêu trong PSR-1
2. 2. Các tập tin
Tất cả các tệp PHP PHẢI sử dụng kết thúc dòng Unix LF [linefeed]
Tất cả các tệp PHP PHẢI kết thúc bằng một dòng trống
Thẻ đóng
bar[$arg1];
Foo::bar[$arg2, $arg3];
8 PHẢI được bỏ qua trong các tệp chỉ chứa PHP2. 3. dòng
KHÔNG ĐƯỢC có giới hạn cứng về độ dài dòng
Giới hạn mềm về độ dài dòng PHẢI là 120 ký tự;
Các dòng KHÔNG NÊN dài hơn 80 ký tự;
KHÔNG ĐƯỢC có khoảng trắng ở cuối các dòng không trống
Các dòng trống CÓ THỂ được thêm vào để cải thiện khả năng đọc và để chỉ ra các khối mã có liên quan
KHÔNG ĐƯỢC có nhiều hơn một câu lệnh trên mỗi dòng
2. 4. thụt lề
Mã PHẢI sử dụng thụt lề 4 khoảng trắng và KHÔNG ĐƯỢC sử dụng các tab để thụt lề
N. b. Chỉ sử dụng khoảng trắng và không trộn lẫn khoảng trắng với các tab, giúp tránh các vấn đề về khác biệt, bản vá, lịch sử và chú thích. Việc sử dụng khoảng trắng cũng giúp dễ dàng chèn thụt lề phụ chi tiết để căn chỉnh giữa các dòng
2. 5. Từ khóa và Đúng/Sai/Không
Các từ khóa PHP PHẢI ở dạng chữ thường
Các hằng số PHP
bar[$arg1];
Foo::bar[$arg2, $arg3];
0, bar[$arg1];
Foo::bar[$arg2, $arg3];
1 và bar[$arg1];
Foo::bar[$arg2, $arg3];
2 PHẢI ở dạng chữ thường3. Không gian tên và sử dụng khai báo
Khi xuất hiện, PHẢI có một dòng trống sau khai báo
bar[$arg1];
Foo::bar[$arg2, $arg3];
3Khi có mặt, tất cả các khai báo
bar[$arg1];
Foo::bar[$arg2, $arg3];
4 PHẢI đi sau khai báo bar[$arg1];
Foo::bar[$arg2, $arg3];
3PHẢI có một từ khóa
bar[$arg1];
Foo::bar[$arg2, $arg3];
4 cho mỗi khai báoPHẢI có một dòng trống sau khối
bar[$arg1];
Foo::bar[$arg2, $arg3];
4Ví dụ
4. Các lớp, thuộc tính và phương thức
Thuật ngữ "lớp" dùng để chỉ tất cả các lớp, giao diện và đặc điểm
4. 1. Mở rộng và triển khai
Các từ khóa
bar[$arg1];
Foo::bar[$arg2, $arg3];
8 và bar[$arg1];
Foo::bar[$arg2, $arg3];
9 PHẢI được khai báo trên cùng một dòng với tên lớpDấu ngoặc mở đầu cho lớp PHẢI đi trên dòng riêng của nó;
Danh sách
bar[$arg1];
Foo::bar[$arg2, $arg3];
9 CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào một lần. Khi làm như vậy, mục đầu tiên trong danh sách PHẢI ở dòng tiếp theo và PHẢI chỉ có một giao diện trên mỗi dòng4. 2. Đặc tính
Khả năng hiển thị PHẢI được khai báo trên tất cả các thuộc tính
Từ khóa
bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
1 KHÔNG ĐƯỢC sử dụng để khai báo thuộc tínhKHÔNG ĐƯỢC có nhiều hơn một thuộc tính được khai báo trên mỗi câu lệnh
Tên thuộc tính KHÔNG NÊN có tiền tố là một dấu gạch dưới để biểu thị khả năng hiển thị được bảo vệ hoặc riêng tư
Một khai báo thuộc tính trông giống như sau
4. 3. phương pháp
Khả năng hiển thị PHẢI được khai báo trên tất cả các phương thức
Tên phương thức KHÔNG NÊN có tiền tố là một dấu gạch dưới để biểu thị khả năng hiển thị được bảo vệ hoặc riêng tư
Tên phương thức KHÔNG ĐƯỢC khai báo với dấu cách sau tên phương thức. Dấu ngoặc mở PHẢI đi trên dòng riêng của nó và dấu ngoặc đóng PHẢI đi trên dòng tiếp theo sau phần thân. KHÔNG ĐƯỢC có khoảng trắng sau dấu ngoặc đơn mở và KHÔNG ĐƯỢC có khoảng trắng trước dấu ngoặc đơn đóng
Một khai báo phương thức trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu phẩy, dấu cách và dấu ngoặc nhọn
4. 4. Đối số phương pháp
Trong danh sách đối số, KHÔNG ĐƯỢC có khoảng trắng trước mỗi dấu phẩy và PHẢI có một khoảng trắng sau mỗi dấu phẩy
Các đối số của phương thức với các giá trị mặc định PHẢI ở cuối danh sách đối số
Danh sách đối số CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào một lần. Khi làm như vậy, mục đầu tiên trong danh sách PHẢI ở dòng tiếp theo và PHẢI chỉ có một đối số trên mỗi dòng
Khi danh sách đối số được chia thành nhiều dòng, dấu ngoặc đơn đóng và dấu ngoặc mở PHẢI được đặt cùng nhau trên dòng riêng của chúng với một khoảng cách giữa chúng
4. 5. bar[$arg1];
Foo::bar[$arg2, $arg3];
5, bar[$arg1];
Foo::bar[$arg2, $arg3];
6 và bar[$arg1];
Foo::bar[$arg2, $arg3];
7
Khi có mặt, khai báo
bar[$arg1];
Foo::bar[$arg2, $arg3];
5 và bar[$arg1];
Foo::bar[$arg2, $arg3];
6 PHẢI đi trước khai báo khả năng hiển thịKhi có mặt, khai báo
bar[$arg1];
Foo::bar[$arg2, $arg3];
7 PHẢI xuất hiện sau khai báo khả năng hiển thị
4. 6. Gọi phương thức và hàm
Khi thực hiện lời gọi phương thức hoặc hàm, KHÔNG ĐƯỢC có khoảng trắng giữa tên phương thức hoặc hàm và dấu ngoặc đơn mở, KHÔNG ĐƯỢC có khoảng trắng sau dấu ngoặc đơn mở và KHÔNG ĐƯỢC có khoảng trắng trước dấu ngoặc đơn đóng. Trong danh sách đối số, KHÔNG ĐƯỢC có khoảng trắng trước mỗi dấu phẩy và PHẢI có một khoảng trắng sau mỗi dấu phẩy
bar[$arg1];
Foo::bar[$arg2, $arg3];
Danh sách đối số CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào một lần. Khi làm như vậy, mục đầu tiên trong danh sách PHẢI ở dòng tiếp theo và PHẢI chỉ có một đối số trên mỗi dòng
bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
5. Cấu trúc điều khiển
Các quy tắc kiểu chung cho các cấu trúc điều khiển như sau
- PHẢI có một khoảng trắng sau từ khóa cấu trúc điều khiển
- KHÔNG ĐƯỢC có khoảng trắng sau dấu ngoặc đơn mở
- KHÔNG ĐƯỢC có khoảng trắng trước dấu ngoặc đơn đóng
- PHẢI có một khoảng cách giữa dấu ngoặc đơn đóng và dấu ngoặc mở
- Thân cấu trúc PHẢI được thụt lề một lần
- Dấu đóng ngoặc PHẢI ở dòng tiếp theo sau phần thân
Phần thân của mỗi cấu trúc PHẢI được bao bọc bởi dấu ngoặc nhọn. Điều này chuẩn hóa giao diện của các cấu trúc và giảm khả năng xảy ra lỗi khi các dòng mới được thêm vào phần thân
5. 1. bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
8, bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
9, bar[$arg1];
Foo::bar[$arg2, $arg3];
20
Một cấu trúc
bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
8 trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọn; Từ khóa
bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
9 NÊN được sử dụng thay vì bar[$arg1];
Foo::bar[$arg2, $arg3];
25 để tất cả các từ khóa điều khiển giống như các từ đơn lẻ5. 2. bar[$arg1];
Foo::bar[$arg2, $arg3];
26, bar[$arg1];
Foo::bar[$arg2, $arg3];
27
Một cấu trúc
bar[$arg1];
Foo::bar[$arg2, $arg3];
26 trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọn. Câu lệnh bar[$arg1];
Foo::bar[$arg2, $arg3];
27 PHẢI được thụt vào một lần từ bar[$arg1];
Foo::bar[$arg2, $arg3];
26 và từ khóa bar[$arg1];
Foo::bar[$arg2, $arg3];
31 [hoặc từ khóa kết thúc khác] PHẢI được thụt vào cùng cấp với phần thân của bar[$arg1];
Foo::bar[$arg2, $arg3];
27. PHẢI có một nhận xét chẳng hạn như bar[$arg1];
Foo::bar[$arg2, $arg3];
33 khi cố ý rơi qua trong phần thân bar[$arg1];
Foo::bar[$arg2, $arg3];
27 không trống5. 3. bar[$arg1];
Foo::bar[$arg2, $arg3];
35, bar[$arg1];
Foo::bar[$arg2, $arg3];
36
Một câu lệnh
bar[$arg1];
Foo::bar[$arg2, $arg3];
35 trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọnTương tự, một câu lệnh
bar[$arg1];
Foo::bar[$arg2, $arg3];
36 giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọn5. 4. bar[$arg1];
Foo::bar[$arg2, $arg3];
39
Một tuyên bố
bar[$arg1];
Foo::bar[$arg2, $arg3];
39 trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọn5. 5. bar[$arg1];
Foo::bar[$arg2, $arg3];
41
Một tuyên bố
bar[$arg1];
Foo::bar[$arg2, $arg3];
41 trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọn5. 6. bar[$arg1];
Foo::bar[$arg2, $arg3];
43, bar[$arg1];
Foo::bar[$arg2, $arg3];
44
Một khối
bar[$arg1];
Foo::bar[$arg2, $arg3];
45 trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọn6. đóng cửa
Bao đóng PHẢI được khai báo với khoảng trắng sau từ khóa
bar[$arg1];
Foo::bar[$arg2, $arg3];
46 và khoảng trắng trước và sau từ khóa bar[$arg1];
Foo::bar[$arg2, $arg3];
4Dấu ngoặc mở PHẢI nằm trên cùng một dòng và dấu ngoặc đóng PHẢI nằm trên dòng tiếp theo sau phần thân
KHÔNG ĐƯỢC có khoảng trắng sau dấu ngoặc đơn mở của danh sách đối số hoặc danh sách biến và KHÔNG ĐƯỢC có khoảng trắng trước dấu ngoặc đơn đóng của danh sách đối số hoặc danh sách biến
Trong danh sách đối số và danh sách biến, KHÔNG ĐƯỢC có khoảng trắng trước mỗi dấu phẩy và PHẢI có một khoảng trắng sau mỗi dấu phẩy
Đối số đóng với giá trị mặc định PHẢI ở cuối danh sách đối số
Một tuyên bố đóng cửa trông giống như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu phẩy, dấu cách và dấu ngoặc nhọn
Danh sách đối số và danh sách biến CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào một lần. Khi làm như vậy, mục đầu tiên trong danh sách PHẢI ở dòng tiếp theo và PHẢI chỉ có một đối số hoặc biến trên mỗi dòng
Khi danh sách kết thúc [dù là đối số hay biến] được chia thành nhiều dòng, dấu ngoặc đơn đóng và dấu ngoặc mở PHẢI được đặt cùng nhau trên dòng riêng của chúng với một khoảng cách giữa chúng
Sau đây là các ví dụ về bao đóng có và không có danh sách đối số và danh sách biến được chia thành nhiều dòng
Lưu ý rằng các quy tắc định dạng cũng được áp dụng khi bao đóng được sử dụng trực tiếp trong lệnh gọi hàm hoặc phương thức làm đối số
7. Sự kết luận
Có nhiều yếu tố về phong cách và thực hành được cố ý bỏ qua trong hướng dẫn này. Chúng bao gồm nhưng không giới hạn ở
Khai báo biến toàn cục và hằng toàn cục
Khai báo hàm
Toán tử và phân công
Căn chỉnh giữa các dòng
Nhận xét và khối tài liệu
Tiền tố và hậu tố tên lớp
Thực hành tốt nhất
Các khuyến nghị trong tương lai CÓ THỂ sửa đổi và mở rộng hướng dẫn này để giải quyết những yếu tố đó hoặc các yếu tố khác của phong cách và thực hành
Phụ lục A. Sự khảo sát
Khi viết hướng dẫn về phong cách này, nhóm đã thực hiện một cuộc khảo sát các dự án thành viên để xác định các thông lệ chung. Cuộc khảo sát được giữ lại ở đây cho hậu thế
A. 1. Dữ liệu khảo sát
A. 2. chú thích khảo sát
bar[$arg1];
Foo::bar[$arg2, $arg3];
48. Kiểu thụt lề. bar[$arg1];
Foo::bar[$arg2, $arg3];
49 = "Sử dụng tab", bar[$arg1];
Foo::bar[$arg2, $arg3];
50 hoặc bar[$arg1];
Foo::bar[$arg2, $arg3];
51 = "số khoảng trắng"bar[$arg1];
Foo::bar[$arg2, $arg3];
52. Giới hạn độ dài dòng "mềm", tính bằng ký tự. bar[$arg1];
Foo::bar[$arg2, $arg3];
53 = không rõ ràng hoặc không có phản hồi, bar[$arg1];
Foo::bar[$arg2, $arg3];
54 có nghĩa là không có giới hạnbar[$arg1];
Foo::bar[$arg2, $arg3];
55. Giới hạn độ dài dòng "cứng", tính bằng ký tự. bar[$arg1];
Foo::bar[$arg2, $arg3];
53 = không rõ ràng hoặc không có phản hồi, bar[$arg1];
Foo::bar[$arg2, $arg3];
54 có nghĩa là không có giới hạnbar[$arg1];
Foo::bar[$arg2, $arg3];
58. Cách các lớp được đặt tên. bar[$arg1];
Foo::bar[$arg2, $arg3];
59 = chỉ chữ thường, bar[$arg1];
Foo::bar[$arg2, $arg3];
60 = chữ thường có dấu phân cách gạch dưới, bar[$arg1];
Foo::bar[$arg2, $arg3];
61 = StudlyCasebar[$arg1];
Foo::bar[$arg2, $arg3];
62. Dấu ngoặc mở đầu cho một lớp nằm trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
63 làm từ khóa lớp hay trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
64 sau nó?bar[$arg1];
Foo::bar[$arg2, $arg3];
65. Hằng số lớp được đặt tên như thế nào? bar[$arg1];
Foo::bar[$arg2, $arg3];
67. Các từ khóa bar[$arg1];
Foo::bar[$arg2, $arg3];
0, bar[$arg1];
Foo::bar[$arg2, $arg3];
1 và bar[$arg1];
Foo::bar[$arg2, $arg3];
2 được đánh vần là tất cả trường hợp bar[$arg1];
Foo::bar[$arg2, $arg3];
59 hay tất cả trường hợp bar[$arg1];
Foo::bar[$arg2, $arg3];
66?bar[$arg1];
Foo::bar[$arg2, $arg3];
73. Các phương thức được đặt tên như thế nào? bar[$arg1];
Foo::bar[$arg2, $arg3];
77. Dấu ngoặc nhọn mở đầu cho một phương thức có nằm trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
63 làm tên phương thức hay trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
64 không?bar[$arg1];
Foo::bar[$arg2, $arg3];
80. Dấu ngoặc mở cho cấu trúc điều khiển nằm trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
63 hay trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
64?bar[$arg1];
Foo::bar[$arg2, $arg3];
83. Có khoảng trắng sau từ khóa cấu trúc điều khiển không?bar[$arg1];
Foo::bar[$arg2, $arg3];
84. Các cấu trúc điều khiển có luôn sử dụng dấu ngoặc nhọn không?bar[$arg1];
Foo::bar[$arg2, $arg3];
85. Khi sử dụng bar[$arg1];
Foo::bar[$arg2, $arg3];
20 hoặc bar[
$longArgument,
$longerArgument,
$muchLongerArgument
];
9, nó sẽ nằm trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
63 như dấu ngoặc đóng trước đó hay nó sẽ nằm trên dòng bar[$arg1];
Foo::bar[$arg2, $arg3];
64?bar[$arg1];
Foo::bar[$arg2, $arg3];
00. Có bao nhiêu lần bar[$arg1];
Foo::bar[$arg2, $arg3];
27 và bar[$arg1];
Foo::bar[$arg2, $arg3];
31 được thụt vào từ một câu lệnh mở đầu bar[$arg1];
Foo::bar[$arg2, $arg3];
26?bar[$arg1];
Foo::bar[$arg2, $arg3];
04. Các lệnh gọi hàm có khoảng trắng sau tên hàm và trước dấu ngoặc đơn mở không?bar[$arg1];
Foo::bar[$arg2, $arg3];
05. Trong các tệp chỉ chứa PHP, thẻ đóng bar[$arg1];
Foo::bar[$arg2, $arg3];
8 có cần thiết không?bar[$arg1];
Foo::bar[$arg2, $arg3];
07. Loại kết thúc dòng nào được sử dụng?bar[$arg1];
Foo::bar[$arg2, $arg3];
08. Khi khai báo một phương thức, bar[$arg1];
Foo::bar[$arg2, $arg3];
7 có trước hay khả năng hiển thị có trước?bar[$arg1];
Foo::bar[$arg2, $arg3];
10. Trong một biểu thức cấu trúc điều khiển, có khoảng trắng sau dấu ngoặc đơn mở và khoảng trắng trước dấu ngoặc đơn đóng không? bar[$arg1];
Foo::bar[$arg2, $arg3];
15. Có dòng trống nào sau thẻ mở PHP không?bar[$arg1];
Foo::bar[$arg2, $arg3];
16. Một bản tóm tắt về dòng mà dấu ngoặc mở tiếp tục cho các lớp, phương thức và cấu trúc điều khiển