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à
Tổng quan
Thông số kỹ thuật này mở rộng, mở rộng và thay thế PSR-2, hướng dẫn kiểu mã hóa và yêu cầu tuân thủ PSR-1, tiêu chuẩn mã hóa cơ bản
Giống như PSR-2, mục đích của thông số kỹ thuật 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. PSR này tìm cách cung cấp một cách thiết lập mà các công cụ kiểu mã hóa có thể triển khai, các dự án có thể tuyên bố tuân thủ và các nhà phát triển có thể dễ dàng liên hệ giữa các dự á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 đó. Vì vậy, 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à là việc chia sẻ các quy tắc đó
PSR-2 đã được chấp nhận vào năm 2012 và kể từ đó, một số thay đổi đã được thực hiện đối với PHP, điều này có ý nghĩa đối với các nguyên tắc về phong cách viết mã. Trong khi PSR-2 rất toàn diện về chức năng PHP đã tồn tại tại thời điểm viết, chức năng mới rất dễ hiểu. Do đó, PSR này tìm cách làm rõ nội dung của PSR-2 trong bối cảnh hiện đại hơn với chức năng mới có sẵn và biến lỗi thành ràng buộc PSR-2
Phiên bản ngôn ngữ trước
Xuyên suốt tài liệu này, mọi hướng dẫn CÓ THỂ bị bỏ qua nếu chúng không tồn tại trong các phiên bản PHP được hỗ trợ bởi dự án của bạn
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
Thuật ngữ 'StudlyCaps' trong PSR-1 PHẢI được hiểu là PascalCase trong đó chữ cái đầu tiên của mỗi từ được viết hoa bao gồm cả chữ cái đầu tiên
2. 2 tệp
Tất cả các tệp PHP PHẢI sử dụng chỉ 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 không trống, được kết thúc bằng một LF
Thẻ đóng
9 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 dò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 trừ khi bị cấm rõ ràng
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ề gồm 4 khoảng trắng cho mỗi mức thụt lề và KHÔNG ĐƯỢC sử dụng các tab để thụt lề
2. 5 từ khóa và các loại
Tất cả các loại và từ khóa dành riêng cho PHP [1][2] PHẢI ở dạng chữ thường
Mọi loại và từ khóa mới được thêm vào các phiên bản PHP trong tương lai PHẢI ở dạng chữ thường
Dạng viết tắt của từ khóa PHẢI được sử dụng i. e.
new Foo[];
0 thay vì new Foo[];
1, new Foo[];
2 thay vì new Foo[];
3, v.v.3. Khai báo câu lệnh, không gian tên và câu lệnh nhập
Tiêu đề của tệp PHP có thể bao gồm một số khối khác nhau. Nếu có, mỗi khối bên dưới PHẢI được phân tách bằng một dòng trống và KHÔNG ĐƯỢC chứa một dòng trống. Mỗi khối PHẢI theo thứ tự được liệt kê bên dưới, mặc dù các khối không liên quan có thể bị bỏ qua
- Mở đầu
4new Foo[];
new Foo[];
5 báo cáo nhập khẩunew Foo[];
6 dựa trên chức năngnew Foo[];
6 dựa trên hằng sốnew Foo[];
8new Foo[];
9 [với dấu chấm phẩy tùy chọn]Các câu lệnh khai báo khối được cho phép và PHẢI được định dạng như bên dưới. Lưu ý vị trí của dấu ngoặc nhọn và khoảng cách
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
Bất kỳ dấu ngoặc nhọn nào KHÔNG ĐƯỢC theo sau bởi bất kỳ nhận xét hoặc tuyên bố nào trên cùng một dòng
Khi khởi tạo một lớp mới, dấu ngoặc đơn PHẢI luôn có mặt ngay cả khi không có đối số nào được truyền cho hàm tạo
new Foo[];
4. 1 Mở rộng và Triển khai
Các từ khóa
0 và 1 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ó;
Dấu ngoặc mở PHẢI ở trên dòng riêng của chúng và KHÔNG được đặt trước hoặc theo sau bởi một dòng trống
Dấu ngoặc nhọn PHẢI ở trên dòng riêng của chúng và KHÔNG ĐƯỢC đứng trước một dòng trống
Danh sách
1 và, trong trường hợp giao diện, 0 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 Sử dụng đặc điểm
Từ khóa
new Foo[];
6 được sử dụng bên trong các lớp để triển khai các đặc điểm PHẢI được khai báo ở dòng tiếp theo sau dấu ngoặc nhọn mở đầuMỗi đặc điểm riêng lẻ được nhập vào một lớp PHẢI được đưa vào từng dòng một và mỗi lần đưa vào PHẢI có câu lệnh nhập khẩu
new Foo[];
6 của riêng nóKhi lớp không có gì sau câu lệnh nhập
new Foo[];
6, dấu ngoặc đóng của lớp PHẢI ở dòng tiếp theo sau câu lệnh nhập new Foo[];
6. Nếu không, nó PHẢI có một dòng trống sau câu lệnh nhập khẩu
new Foo[];
6. Các toán tử 9 và 0 chúng phải được sử dụng như sau, lưu ý về thụt đầu dòng, khoảng cách và các dòng mới1 từ khóa KHÔNG ĐƯỢC sử dụng để khai báo một 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 ĐƯỢC thêm tiền tố bằng 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ư. Đó là, một tiền tố gạch dưới rõ ràng không có ý nghĩa
PHẢI có khoảng cách giữa khai báo kiểu và tên thuộc tính
Một khai báo thuộc tính trông giống như sau
2 trước một đối số, KHÔNG ĐƯỢC có khoảng trắng sau nó, như trong ví dụ trướcKHÔNG ĐƯỢC có khoảng cách giữa toán tử ba chấm biến thiên và tên đối số
Khi kết hợp cả toán tử tham chiếu và toán tử ba chấm biến thiên, KHÔNG ĐƯỢC có bất kỳ khoảng trống nào giữa hai toán tử này
4. 6 3, 4 và 5
Khi có, các khai báo
3 và 4 PHẢI đi trước khai báo khả năng hiển thịKhi xuất hiện, khai báo
5 PHẢI xuất hiện sau tuyên bố về khả năng hiển thị4. 7 Lời 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
1Danh 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. Một đối số duy nhất được chia thành nhiều dòng [có thể là trường hợp với một hàm hoặc mảng ẩn danh] không cấu thành việc phân tách chính danh sách đối số
25. 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
- Phần thân PHẢI ở dòng tiếp theo sau dấu ngoặc mở
- 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 9, 0, 1
Một cấu trúc
9 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
0 NÊN được sử dụng thay vì 6 để tất cả các từ khóa điều khiển trông giống như các từ đơn lẻBiểu thức trong ngoặc CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào ít nhất một lần. Khi làm như vậy, điều kiện đầu tiên PHẢI ở dòng tiếp theo. Dấu ngoặc đóng và dấu ngoặc mở PHẢI được đặt cùng nhau trên một dòng riêng với một khoảng cách giữa chúng. Các toán tử Boolean giữa các điều kiện PHẢI luôn ở đầu hoặc cuối dòng, không kết hợp cả hai
5. 2 7, 8
Một cấu trúc
7 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 8 PHẢI được thụt vào một lần từ 7 và từ khóa 2 [hoặc cá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 8. PHẢI có một nhận xét chẳng hạn như 4 khi cố tình rơi xuyên qua một cơ thể 8 không trốngBiểu thức trong ngoặc CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào ít nhất một lần. Khi làm như vậy, điều kiện đầu tiên PHẢI ở dòng tiếp theo. Dấu ngoặc đóng và dấu ngoặc mở PHẢI được đặt cùng nhau trên một dòng riêng với một khoảng cách giữa chúng. Các toán tử Boolean giữa các điều kiện PHẢI luôn ở đầu hoặc cuối dòng, không kết hợp cả hai
5. 3 6, 7
Một câu lệnh
6 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ọnBiểu thức trong ngoặc CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào ít nhất một lần. Khi làm như vậy, điều kiện đầu tiên PHẢI ở dòng tiếp theo. Dấu ngoặc đóng và dấu ngoặc mở PHẢI được đặt cùng nhau trên một dòng riêng với một khoảng cách giữa chúng. Các toán tử Boolean giữa các điều kiện PHẢI luôn ở đầu hoặc cuối dòng, không kết hợp cả hai
Tương tự, một câu lệnh
7 có dạng như sau. Lưu ý vị trí của dấu ngoặc đơn, dấu cách và dấu ngoặc nhọnBiểu thức trong ngoặc CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào ít nhất một lần. Khi làm như vậy, điều kiện đầu tiên PHẢI ở dòng tiếp theo. Các toán tử Boolean giữa các điều kiện PHẢI luôn ở đầu hoặc cuối dòng, không kết hợp cả hai
5. 4 0
Một câu lệnh
0 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ọnBiểu thức trong ngoặc CÓ THỂ được chia thành nhiều dòng, trong đó mỗi dòng tiếp theo được thụt vào ít nhất một lần. Khi làm như vậy, biểu thức đầu tiên PHẢI ở dòng tiếp theo. Dấu ngoặc đóng và dấu ngoặc mở PHẢI được đặt cùng nhau trên một dòng riêng với một khoảng cách giữa chúng
5. 5 2
Một câu lệnh
2 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 4, 5, 6
Một khối
7 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. nhà điều hành
Các quy tắc kiểu cho toán tử được nhóm theo thứ hạng [số lượng toán hạng mà chúng sử dụng]
Khi khoảng trống được cho phép xung quanh một toán tử, nhiều khoảng trắng CÓ THỂ được sử dụng cho mục đích dễ đọc
Tất cả các toán tử không được mô tả ở đây đều không được xác định
6. 1. toán tử đơn nguyên
Các toán tử tăng/giảm KHÔNG ĐƯỢC có bất kỳ khoảng trắng nào giữa toán tử và toán hạng
3Các toán tử truyền kiểu KHÔNG ĐƯỢC có bất kỳ khoảng trống nào trong dấu ngoặc đơn
46. 2. toán tử nhị phân
Tất cả các toán tử số học nhị phân, so sánh, gán, bitwise, logic, chuỗi và loại PHẢI được đặt trước và theo sau bởi ít nhất một khoảng trắng
56. 3. nhà khai thác ternary
Toán tử có điều kiện, còn được gọi đơn giản là toán tử bậc ba, PHẢI được đặt trước và theo sau ít nhất một khoảng trắng xung quanh cả hai ký tự
8 và 96Khi toán hạng ở giữa của toán tử điều kiện bị bỏ qua, toán tử PHẢI tuân theo các quy tắc kiểu giống như các toán tử so sánh nhị phân khác
77. đóng cửa
Bao đóng PHẢI được khai báo với khoảng trắng sau từ khóa
0 và khoảng trắng trước và sau từ khóa new Foo[];
6Dấu ngoặc mở PHẢI nằm trên cùng một dòng và dấu ngoặc nhọn 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ố
Nếu có kiểu trả về, nó PHẢI tuân theo các quy tắc giống như với các hàm và phương thức thông thường;
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ố