Pro รุ่น

ไปป์ไลน์เอาต์พุต

ภาพรวมโดยสังเขป

Output Pipeline รันแมนิเฟสต์เชิงประกาศของขั้นตอน PDF ตามลำดับการพึ่งพา พร้อมการลองใหม่ต่อขั้นตอนและตัวเลือกหยุดเมื่อเกิดข้อผิดพลาด ขั้นตอนบางประเภทต้องใช้ความสามารถ Enterprise Pack เพิ่มเติม

การพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองสิทธิ์ใช้งานระดับ Pro การปรับใช้ที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอรับสิทธิ์ใช้งาน

ตัวดำเนินการไปป์ไลน์เองเป็นส่วนหนึ่งของรุ่น Pro ขั้นตอนสามประเภทต้องการความสามารถ Enterprise Pack ที่ระบุชื่อเพิ่มเติม ได้แก่ ขั้นตอนการปิดบังต้องการความสามารถ Privacy Pack และขั้นตอนการสกัดและ OCR-overlay ต้องการความสามารถ Intelligence Pack ขั้นตอนที่ถูกเกตและไม่มีสิทธิ์ใช้งานจะล้มเหลวแบบปิด ( fail closed ) ในระหว่างการดำเนินการ โดยให้ผลลัพธ์ขั้นตอนที่ล้มเหลวและไม่เรียกใช้ resolver ของมันเลย แทนที่จะยกเลิกการรันทั้งหมด

การติดตั้ง

composer require nextpdf/pro:^3

โค้ดอยู่ภายใต้เนมสเปซ NextPDF\Pro\OutputPipeline

ภาพรวมเชิงแนวคิด

PipelineExecutor รับ PipelineManifest เรียงขั้นตอนตามลำดับ topological และส่งแต่ละขั้นตอนไปยัง resolver ที่ลงทะเบียนใน StepResolverRegistry เอาต์พุตของขั้นตอนถูกจัดเก็บใน PipelineContext สำหรับขั้นตอนถัดไป ตัวดำเนินการบังคับใช้การหมดเวลาแบบรวม รองรับการลองใหม่ต่อขั้นตอน และสามารถดำเนินการต่อจากขั้นตอนที่ระบุชื่อได้ มันถูกออกแบบมาให้รันภายใน job worker แบบอะซิงโครนัส ไม่ใช่รันโดยตรงจาก request handler

ขั้นตอนในตัวได้แก่ generate, merge, split, inspect, compress, sign และ convert ประเภทขั้นตอนการปิดบัง การสกัด และ OCR-overlay ต้องมีสิทธิ์ใช้งานความสามารถและแมปไปยังความสามารถ Enterprise Pack

เหตุใดจึงทำงานเช่นนี้

ตัวดำเนินการทำหน้าที่ประสานงานเท่านั้น มันเรียงขั้นตอน บังคับใช้เกตสิทธิ์ใช้งาน และส่งแต่ละขั้นตอนไปยัง resolver ที่ลงทะเบียนไว้ แต่ไม่ได้ทำงาน PDF ใด ๆ เอง การแยกส่วนนี้ทำให้แมนิเฟสต์เดียวรันได้ทั้งผ่านเส้นทาง PHP แบบลำดับนี้ หรือผ่าน worker นอกวงที่ส่งขั้นตอนแบบขนาน โดยไม่ต้องเปลี่ยนโค้ดที่เรียกใช้ การออกแบบมุ่งไปที่ job worker แบบอะซิงโครนัสมากกว่า request handler เพราะไปป์ไลน์แบบหลายขั้นตอนมักมีอายุยาวเกินงบประมาณของคำขอเป็นปกติ และคิวขยายปริมาณงานได้ด้วยการเพิ่ม worker การหมดเวลาแบบรวมถูกตรวจสอบระหว่างขั้นตอนด้วยเหตุผลเดียวกัน คือ ขั้นตอนทั้งขั้นเป็นหน่วยงานที่ส่งมอบให้ resolver และตัวประสานงานไม่เข้าไปยุ่งกับการรันของ resolver นั้น ความล้มเหลวปรากฏเป็นค่า StepResult ต่อขั้นตอนแทนที่จะเป็นข้อยกเว้นที่ถูกโยน ดังนั้นขั้นตอนที่ล้มเหลวหนึ่งขั้นจึงไม่ทำให้ PipelineResult แบบรวมที่ worker รายงานล่มลง

ที่มาของการออกแบบ: High-volume document generation

สัญญาพฤติกรรม

execute($manifest, $variables) คืนค่าผลลัพธ์พร้อมสถานะโดยรวม ผลลัพธ์ต่อขั้นตอน ระยะเวลา และจำนวนขั้นตอนที่เสร็จสมบูรณ์และล้มเหลว
ขั้นตอนรันตามลำดับ topological การไม่มี resolver สำหรับประเภทขั้นตอนหนึ่งจะให้ขั้นตอนที่ล้มเหลวพร้อมข้อความที่ชัดเจน
PipelineOptions::$stopOnError หยุดการดำเนินการเมื่อล้มเหลวครั้งแรก มิฉะนั้นการดำเนินการจะดำเนินต่อและสถานะสุดท้ายสะท้อนความล้มเหลวใด ๆ
การหมดเวลาแบบรวม เมื่อตั้งค่าไว้ จะทำให้ไปป์ไลน์ล้มเหลวหากเกินก่อนที่ขั้นตอนถัดไปจะเริ่ม
การลองใหม่ต่อขั้นตอนถูกจำกัดด้วยค่าสูงสุดที่กำหนดค่าไว้ มีเพียงความล้มเหลวที่ไม่เป็นที่สิ้นสุดเท่านั้นที่ถูกลองใหม่
การดำเนินการต่อจากขั้นตอนข้ามขั้นตอนก่อนหน้าจนกว่าจะถึงขั้นตอนที่ระบุชื่อ
ประเภทขั้นตอนที่ถูกเกตด้วยความสามารถจะล้มเหลวแบบปิดในระหว่างการดำเนินการพร้อมรหัสข้อผิดพลาดสิทธิ์ใช้งานเมื่อไม่มีความสามารถ Pack ที่ต้องการ โดยไม่เรียกใช้ resolver เลย

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

ต่อไปนี้สะท้อน public API ที่จัดทำเอกสารไว้ repository ไม่ได้มาพร้อมตัวอย่างที่รันได้สำหรับโมดูลนี้

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

ตัวอย่างโค้ด — การใช้งานจริง

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

กรณีขอบและข้อควรระวัง

ไปป์ไลน์มีไว้ให้รันแบบอะซิงโครนัสผ่านระบบ job การรันแบบ inline จะบล็อกผู้เรียกใช้ตลอดระยะเวลาทั้งหมดของไปป์ไลน์
ประเภทขั้นตอนที่ไม่มี resolver ลงทะเบียนจะทำให้ขั้นตอนนั้นล้มเหลวแทนที่จะยกเลิกทั้งไปป์ไลน์ (เว้นแต่จะตั้งค่าหยุดเมื่อเกิดข้อผิดพลาด)
การหมดเวลาแบบรวมถูกตรวจสอบระหว่างขั้นตอน ไม่ใช่กลางขั้นตอน ขั้นตอนที่ทำงานยาวนานสามารถใช้เกินงบประมาณก่อนที่การตรวจสอบจะทำงาน

ประสิทธิภาพ

ระยะเวลารวมคือผลรวมของระยะเวลาแต่ละขั้นตอนบวกกับโสหุ้ยการลองใหม่ การหมดเวลาแบบรวมจำกัดเวลา wall-clock ในกรณีเลวร้ายที่สุด ไม่มีตัวเลขปริมาณงานที่เผยแพร่ ต้นทุนไปป์ไลน์ถูกครอบงำโดยขั้นตอนที่คุณรวมไว้ วัดผลด้วยแมนิเฟสต์ที่เป็นตัวแทน

หมายเหตุด้านความปลอดภัย

ตัวดำเนินการส่งเอกสารอินพุตและตัวแปรไปยัง step resolver ให้ถือว่าสิ่งเหล่านั้นไม่น่าเชื่อถือและตรวจสอบภายใน resolver แต่ละตัว ขั้นตอนที่ถูกเกตด้วยความสามารถจะ fail closed เมื่อไม่มีสิทธิ์ใช้งาน ตัวดำเนินการไม่บันทึกเนื้อหาเอกสาร

การเป็นไปตามข้อกำหนด

ตัวดำเนินการไม่ได้ทำงานด้านความสอดคล้องของรูปแบบใด ๆ เอง ความสอดคล้องขึ้นอยู่กับ step resolver แต่ละตัว (generate, merge, split, sign, convert) คลังข้อมูล RAG ไม่พร้อมใช้งานในเวลาเขียน หน้านี้จึงไม่อ้างตัวระบุข้อภายนอก

หมายเหตุขอบเขตของ Enterprise

Enterprise เพิ่มความสามารถ Pack ที่ปลดล็อกประเภทขั้นตอนที่ถูกเกต (การปิดบัง การสกัด OCR overlay) ในระดับพฤติกรรม หากไม่มี Pack เหล่านั้น ไปป์ไลน์ยังคงรันทุกขั้นตอนที่ไม่ได้ถูกเกต รายละเอียดภายในของ Pack อยู่นอกขอบเขตที่นี่

ทางเลือกสำรองของ Core

หากไม่มี Pro ให้ประสานการดำเนินการ PDF แบบ imperative ด้วย API ของ NextPDF Core ส่วนแมนิเฟสต์เชิงประกาศ การจัดลำดับการพึ่งพา และการลองใหม่เป็นส่วนเพิ่มของ Pro

ขอบเขตการเผยแพร่

หน้านี้จัดทำเอกสารเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น พาธเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าหมายเลขทิกเก็ตอยู่นอกขอบเขต