ข้อกำหนดของสูตร

ข้อกำหนดของสูตร

สูตรที่รันได้ทุกสูตรในตำราการผสานการทำงานใช้สัญญาเดียวกัน หน้านี้อธิบายสัญญาดังกล่าวเพื่อให้คุณทราบว่าสูตรควรมีอะไร และผู้เขียนสูตรต้องจัดเตรียมอะไร หน้านี้มีลักษณะเชิงพรรณนา คือบันทึกข้อกำหนดไว้เท่านั้น ส่วนการบังคับใช้อยู่ในเครื่องมือของรีพอซิทอรีและชีตการแทนที่สไตล์ ไม่ได้อยู่ในหน้านี้

การผสานการทำงานแต่ละรายการเก็บสูตรของตนไว้ภายใต้ docs/public/ ในรีพอซิทอรีซอร์สของตนเอง และตัวรวบรวม (aggregator) จะดึงสูตรเหล่านั้นเข้ามายังไซต์นี้ ข้อกำหนดเหล่านี้มีผลใช้กับสูตรไม่ว่าจะอยู่ที่ใด

1. ตัวอย่างเป็นโค้ดจริง ไม่ใช่สนิปเปตที่พิมพ์ด้วยมือ

โค้ดของสูตรอยู่ในรีพอซิทอรี ไม่ใช่สนิปเปตที่พิมพ์ลงในเนื้อหาโดยตรง

• บล็อกโค้ด PHP ใดก็ตามที่ยาวเกินห้าบรรทัดต้องมาจากไดเรกทอรี examples/ ในรีพอซิทอรีที่เกี่ยวข้อง หรือจากไดเรกทอรี tests/Cookbook/
• บล็อกต้องประกาศแหล่งที่มาของตนไว้ในสตริงข้อมูลของ fenced-block เช่น title="examples/standalone.php"
• การทดสอบที่เกี่ยวข้องยืนยันว่าตัวอย่างยังคอมไพล์ได้และให้ผลลัพธ์ตรงตามเอกสาร ดังนั้นหน้าที่เรนเดอร์จึงไม่คลาดเคลื่อนจากโค้ดที่แสดง

ข้อกำหนดนี้มาจากชีตการแทนที่สไตล์เอกสาร §3.4 (“Samples must be runnable”) สูตรที่แสดงโค้ดโดยไม่มีตัวอย่างหรือการทดสอบรองรับถือว่าไม่เป็นไปตามข้อกำหนด

2. หนึ่งภาษาต่อหนึ่งบล็อก พร้อมแสดงการจัดการข้อผิดพลาดให้เห็น

• บล็อกโค้ดแบบ fenced มีเพียงหนึ่งภาษาเท่านั้น และประกาศภาษาไว้อย่างชัดเจน ( ```php, ```bash, ```yaml, ```json) ไม่ใช้ fence เปล่าที่ไม่ระบุภาษา
• สูตรที่ทำเครื่องหมายว่าเป็นวิธีการที่พร้อมใช้งานจริง (production-ready how-to) จะแสดง try / catch อย่างชัดเจน จับชนิดของ exception ที่เฉพาะเจาะจงที่สุดเท่าที่ใช้ได้แทนการใช้ \Exception เปล่า และบล็อก catch จะทำสิ่งที่ผู้อ่านนำไปใช้ต่อได้ เช่น บันทึกล็อก ส่งต่อ exception ใหม่ หรือคืนค่าอ็อบเจกต์ข้อผิดพลาดที่กำหนดไว้ ไม่ใช้บล็อก catch ที่ว่างเปล่า
• สำหรับการผสานการทำงานที่ใช้การส่งผ่านแบบ Hypertext Transfer Protocol (HTTP) สูตรจะแยกความล้มเหลวของการส่งผ่านออกจากสถานะ HTTP ที่ไม่สำเร็จเป็นคนละกรณี ไคลเอนต์แบบ PHP Standards Recommendation (PSR)-18 จะยก client exception ที่มีชนิดเฉพาะก็ต่อเมื่อส่งคำขอไม่ได้เท่านั้น การตอบกลับแบบ 4xx หรือ 5xx คือค่าที่คืนมาตามปกติซึ่งสูตรจะตรวจสอบ ไม่ใช่ exception ที่สูตรจับ

3. front-matter ของความสามารถในการทำซ้ำ

สูตรแต่ละสูตรประกาศว่าผลลัพธ์ของตนทำซ้ำได้ในระดับใด สูตรใช้สัญญา front-matter §5.1 ซึ่ง content schema ของไซต์บังคับใช้ ฟิลด์ที่เกี่ยวข้องมีดังนี้

• reproducibility_profile — หนึ่งในค่า bitwise, structural หรือ semantic bitwise หมายความว่าไบต์ของผลลัพธ์เหมือนกันทุกครั้งที่รันเมื่อใช้อินพุตที่ตรึงไว้ structural หมายความว่าโครงสร้างของเอกสารเหมือนกัน แต่ไบต์ที่ไม่สำคัญ เช่น ค่าเวลาและลำดับของอ็อบเจกต์ อาจแตกต่างได้ semantic หมายความว่าผลลัพธ์ที่เรนเดอร์มีค่าเทียบเท่ากัน โดยไม่รับประกันระดับไบต์หรือโครงสร้าง สูตรต้องระบุโปรไฟล์ที่แข็งแกร่งที่สุดที่ตนรองรับได้อย่างซื่อตรง ไม่ใช่โปรไฟล์ที่แข็งแกร่งที่สุดในตัวเลือก
• output_hash — เมื่อโปรไฟล์เป็น bitwise ฟิลด์นี้คือค่า SHA-256 ของผลลัพธ์ที่คาดหวัง เพื่อให้ผู้อ่านตรวจสอบผลลัพธ์ตามเอกสารได้ เว้นว่างไว้เมื่อโปรไฟล์ไม่รองรับแฮชที่เสถียร
• runnable_example — พาธ examples/… ที่สร้างผลลัพธ์ของสูตร โดยผูกหน้านี้เข้ากับตัวอย่างที่อ้างอิงจากซอร์สใน §1
• performance_budget — เพดานเวลาตามนาฬิกาจริง (wall-clock) และหน่วยความจำสูงสุดที่สูตรระบุได้ตามต้องการ เพื่อให้สูตรที่อ้างเรื่องประสิทธิภาพยังมีขอบเขตจำกัดและทดสอบได้
• compatibility — เวอร์ชัน PHP ที่สูตรอ้างว่ารันได้ สูตรใช้ค่าเริ่มต้นเป็น PHP 8.4 สูตรที่ระบุฟีเจอร์เฉพาะของ 8.4 จะแสดงรายการ backport ไว้ใน front-matter ของตน และระบุฟีเจอร์นั้นในบล็อกโค้ด

โปรไฟล์ความสามารถในการทำซ้ำคือสัญญาความสามารถในการทำซ้ำ §8.4 คุณใช้โปรไฟล์นี้เพื่อระบุว่า “ผลลัพธ์” หมายถึงไบต์ที่ตรงกันทุกประการหรือเอกสารที่เทียบเท่ากัน

4. เกตการเผยแพร่

ทุกหน้าในตำราเล่มนี้กำกับด้วย publish: false จนกว่าจะผ่าน Writing Gate ค่าเริ่มต้นคือไม่อนุญาตให้เผยแพร่ การ merge หน้าใดหน้าหนึ่งไม่ได้ทำให้หน้านั้นเผยแพร่ได้ มีเพียงการตัดสินอย่างชัดเจนที่ Writing Gate ซึ่งบันทึกไว้ใน front-matter เท่านั้นที่ทำให้เผยแพร่ได้ สูตรที่ไม่สามารถตรึงการอ้างอิงเชิงบรรทัดฐานได้เนื่องจาก compliance-engine ขัดข้องจริง จะกำกับด้วยเครื่องหมายการอ้างอิงที่ยังไม่ได้แก้ไขด้วย หน้านั้นยังคงเป็น publish: false จนกว่าการอ้างอิงจะถูกตรึงใหม่ โปรโตคอลสำรองกรณีโครงสร้างพื้นฐานขัดข้องของ retrieval-augmented generation (RAG) ในรีพอซิทอรีเป็นตัวกำกับเครื่องหมายนั้น ผู้เขียนสูตรปฏิบัติตามโปรโตคอลดังกล่าวแทนที่จะแต่งการอ้างอิงขึ้นมาเองหรือตัดคำกล่าวอ้างนั้นทิ้ง

5. ตัวรวบรวมเป็นผู้กรอกฟิลด์ที่มา (provenance)

ผู้เขียนสูตรไม่เขียนฟิลด์ที่มาของซอร์สสี่ฟิลด์ที่เป็นของตัวรวบรวมด้วยมือ ได้แก่ source_repo, source_ref, source_hash และ manifest_hash ตัวรวบรวมเป็นผู้กรอกฟิลด์เหล่านั้นเมื่อดึงสูตรมาจากรีพอซิทอรีซอร์สของสูตร ดังนั้นหน้าที่เผยแพร่จึงบันทึกได้อย่างแม่นยำว่ารีวิชันใดของรีพอซิทอรีเป็นต้นทางของหน้านั้น หากผู้เขียนปล่อยค่าตัวยึดตำแหน่งไว้ในฟิลด์ใดฟิลด์หนึ่งเหล่านี้ ตัวรวบรวมจะเขียนทับค่านั้น ตัวยึดตำแหน่งจะไม่มีทางไปถึงหน้าที่เผยแพร่

สรุป

สูตรในตำราเล่มนี้มีโค้ดที่อ้างอิงจากซอร์สพร้อมการทดสอบ หนึ่งภาษาต่อหนึ่งบล็อก การจัดการข้อผิดพลาดอย่างชัดเจนสำหรับวิธีการที่ใช้งานจริง โปรไฟล์ความสามารถในการทำซ้ำที่ซื่อตรง ค่าเริ่มต้นเป็น publish: false จนกว่าจะผ่าน Writing Gate และฟิลด์ที่มาที่ตัวรวบรวมเป็นผู้กรอก หน้าที่ครบทั้งหกข้อจึงเป็นสูตร ส่วนหน้าที่ไม่ครบคือฉบับร่าง

ดูเพิ่มเติม

• ตำราการผสานการทำงาน — เอกสารอ้างอิงของแพ็กเกจและข้อจำกัดของคอร์
• เลือกการผสานการทำงาน — เมทริกซ์การตัดสินใจตามกรณีการใช้งาน