Quy ước cho recipe

Mọi recipe có thể chạy được trong cookbook tích hợp đều tuân theo cùng một hợp đồng. Trang này ghi lại hợp đồng đó để bạn biết có thể kỳ vọng gì ở một recipe và người viết recipe phải cung cấp những gì. Trang này chỉ mang tính mô tả: nó ghi lại quy ước. Việc thực thi nằm trong công cụ của repository và bảng ghi đè style, không nằm ở đây.

Mỗi tích hợp lưu các recipe của mình trong thư mục docs/public/ của source repository riêng, rồi aggregator kéo chúng vào trang web này. Các quy ước này áp dụng cho mọi nơi đặt recipe.

1. Mẫu là code thực, không phải đoạn code viết tay

Code của một recipe tồn tại trong repository. Nó không phải là đoạn code được gõ trực tiếp vào phần văn bản.

Mọi khối code PHP dài hơn năm dòng đều đến từ thư mục examples/ trong repository tương ứng, hoặc từ thư mục tests/Cookbook/.
Khối code khai báo nguồn gốc của nó trong chuỗi thông tin của fenced-block, ví dụ title="examples/standalone.php".
Một test tương ứng xác nhận rằng ví dụ vẫn biên dịch được và tạo ra đúng kết quả đã ghi trong tài liệu, nhờ đó trang đã kết xuất không thể lệch khỏi đoạn code mà nó hiển thị.

Quy ước này đến từ bảng ghi đè style của tài liệu §3.4 (“Mẫu phải chạy được”). Một recipe hiển thị code nhưng không có ví dụ hoặc test hỗ trợ thì không đáp ứng quy ước.

2. Mỗi khối một ngôn ngữ, có xử lý lỗi hiển thị rõ

Một fenced code block chỉ chứa một ngôn ngữ và phải khai báo tường minh ( ```php, ```bash, ```yaml, ```json). Không dùng fence trống không khai báo ngôn ngữ.
Một recipe được đánh dấu là hướng dẫn sẵn sàng cho production phải hiển thị try / catch một cách tường minh, bắt loại exception cụ thể nhất có thể áp dụng thay vì \Exception trống, và khối catch thực hiện một việc mà người đọc có thể sao chép (ghi log, ném lại hoặc trả về một đối tượng lỗi đã định nghĩa). Không dùng khối catch rỗng.
Đối với các tích hợp dùng transport Hypertext Transfer Protocol (HTTP), recipe xem lỗi transport và trạng thái HTTP không thành công là hai trường hợp riêng biệt. Một client theo PHP Standards Recommendation (PSR)-18 chỉ ném ra một client exception có kiểu khi không gửi được request. Phản hồi 4xx hoặc 5xx là một giá trị trả về bình thường mà recipe kiểm tra, không phải một exception để bắt.

3. Front-matter về reproducibility

Mỗi recipe khai báo mức độ có thể tái tạo của kết quả mà nó tạo ra. Recipe dùng hợp đồng front-matter §5.1 do content schema của trang web thực thi. Các trường liên quan là:

reproducibility_profile — một trong các giá trị bitwise, structural, hoặc semantic. bitwise nghĩa là các byte đầu ra giống hệt nhau giữa các lần chạy với cùng đầu vào đã được ghim cố định. structural nghĩa là cấu trúc tài liệu giống hệt nhau, trong khi các byte phụ (dấu thời gian, thứ tự đối tượng) có thể khác nhau. semantic nghĩa là kết quả đã kết xuất là tương đương, nhưng không bảo đảm về byte hay cấu trúc. Một recipe nêu profile mạnh nhất mà nó thật sự có thể hỗ trợ, không phải profile mạnh nhất hiện có.
output_hash — khi profile là bitwise, đây là giá trị SHA-256 của kết quả mong đợi, để người đọc có thể xác minh kết quả đã ghi trong tài liệu. Để trống khi profile không hỗ trợ hash ổn định.
runnable_example — đường dẫn examples/… tạo ra kết quả của recipe, gắn trang này với mẫu dựa trên mã nguồn ở §1.
performance_budget — giới hạn tùy chọn về thời gian thực và bộ nhớ đỉnh cho recipe, để recipe có tuyên bố về hiệu năng luôn nằm trong giới hạn và có thể kiểm thử được.
compatibility — các phiên bản PHP mà recipe tuyên bố là chạy được. Recipe mặc định dùng PHP 8.4; recipe nào nêu một tính năng chỉ có ở 8.4 sẽ liệt kê bản backport trong front-matter và chỉ rõ tính năng đó trong khối code.

Reproducibility profile chính là hợp đồng về reproducibility §8.4. Bạn dùng nó để biết “kết quả đầu ra” có nghĩa là các byte chính xác hay một tài liệu tương đương.

4. Cổng xuất bản

Mọi trang trong cookbook này đều đặt publish: false cho đến khi vượt qua Writing Gate. Mặc định là từ chối: việc merge một trang không xuất bản trang đó; chỉ một quyết định cổng tường minh được ghi trong front-matter mới làm điều đó. Recipe nào có trích dẫn chuẩn tắc không thể ghim cố định do sự cố thật sự của compliance-engine cũng mang dấu unresolved-citation. Recipe đó vẫn giữ publish: false cho đến khi trích dẫn được ghim lại. Giao thức dự phòng của repository dành cho sự cố hạ tầng retrieval-augmented generation (RAG) quản lý dấu đó; người viết recipe tuân theo giao thức ấy thay vì bịa ra trích dẫn hoặc bỏ tuyên bố.

5. Bộ aggregator ghi các trường provenance

Người viết recipe không tự tay viết bốn trường source-provenance thuộc quyền của aggregator: source_repo, source_ref, source_hash, và manifest_hash. Aggregator điền các trường đó khi kéo recipe từ source repository, nên trang đã xuất bản ghi lại chính xác bản sửa đổi nào của repository đã tạo ra nó. Nếu người viết để lại placeholder trong bất kỳ trường nào trong số này, aggregator sẽ ghi đè lên nó; placeholder không bao giờ đến được trang đã xuất bản.

Tóm tắt

Một recipe trong cookbook này có code dựa trên mã nguồn thực kèm test, mỗi khối một ngôn ngữ, xử lý lỗi tường minh cho hướng dẫn dành cho production, reproducibility profile trung thực, mặc định publish: false cho đến khi vượt qua Writing Gate, và provenance do aggregator chèn vào. Trang nào đáp ứng cả sáu điều là recipe; trang nào đáp ứng ít hơn là bản nháp.

Xem thêm

Cookbook tích hợp — tài liệu tham khảo về package và ràng buộc cốt lõi.
Chọn một tích hợp — ma trận quyết định theo trường hợp sử dụng.