Output Pipeline — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยสรุป

หน้านี้เป็นเอกสารอ้างอิงเชิงลึกสำหรับพื้นผิวสาธารณะของ NextPDF\Pro\OutputPipeline ครอบคลุมการสร้างและตรวจสอบ manifest ลำดับการดำเนินการเชิง topological ความหมายของการลองใหม่และการหมดเวลา พฤติกรรมการทำงานต่อ และเกตความสามารถของ pack แบบ fail-closed ระบุพารามิเตอร์ ค่าเริ่มต้น และโหมดความล้มเหลวของทุกสัญลักษณ์สาธารณะ โปรดอ่าน หน้าความสามารถ Output Pipeline ก่อนเพื่อดูคำแนะนำเวิร์กโฟลว์

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

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

executor และเจ็ดในสิบชนิดขั้นตอนไม่มีแฟล็กเฉพาะฟีเจอร์ ส่วนอีกสามชนิดขั้นตอนต้องใช้ความสามารถ Pack เพิ่มเติม:

ชนิดขั้นตอน	ค่า manifest	ความสามารถที่ต้องใช้	Pack
Redact	redact	pack.privacy.redact	Privacy Pack
Extract	extract	pack.intelligence.extract	Intelligence Pack
OCR overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

เกตถูกบังคับใช้ในเวลาดำเนินการ แบบ fail-closed ก่อนที่ขั้นตอนจะถึง resolver ของมัน ขั้นตอนที่ถูกจำกัดสิทธิ์โดยไม่มีใบอนุญาตจะให้ผลลัพธ์ขั้นตอนแบบ Failed ที่มีรหัส SPEC-LIC-001 และความสามารถที่ต้องใช้ โดยไม่มีการเรียก resolver เลย ไปป์ไลน์ที่ไม่มีการฉีด capability resolver จะปฏิเสธทุกขั้นตอนที่ถูกจำกัดสิทธิ์

พื้นผิว API สาธารณะ

composer require nextpdf/pro:^3

เมทาแพ็กเกจ nextpdf/premium ติดตั้งโค้ด nextpdf/pro โมดูลนี้อยู่ภายใต้เนมสเปซ NextPDF\Pro\OutputPipeline

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	ผูก resolver registry ในตัวและแหล่งสิทธิ์ที่เป็นทางเลือก	PipelineExecutor	ไม่มีการประกาศ	capability resolver ที่เป็น null จะปฏิเสธทุกขั้นตอนที่จำกัดสิทธิ์ตาม pack
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	รันขั้นตอนตามลำดับ topological และรวมผลลัพธ์	PipelineResult	ไม่มีการประกาศ; ความล้มเหลวของ resolver ถูกจับเป็นผลลัพธ์ขั้นตอนแบบ Failed	ออกแบบมาเพื่อรันภายใน job worker แบบ asynchronous
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	ตรวจสอบกราฟขั้นตอนขณะสร้าง	PipelineManifest	InvalidArgumentException เมื่อรายการขั้นตอนว่าง มี step ID ซ้ำ มีการอ้างอิงที่ไม่รู้จัก มีวงจร ชนิดเอาต์พุตไม่ตรงกัน หรือไม่มีขั้นตอน resume; OverflowException เมื่อเกิน 10 000 ขั้นตอน	การตรวจสอบทั้งหมดเสร็จสิ้นก่อนการดำเนินการใด ๆ
PipelineManifest::topologicalOrder	none	จัดลำดับขั้นตอนโดยให้การพึ่งพาอยู่ก่อนผู้ที่พึ่งพา	list<PipelineStep>	ไม่มีการประกาศ	กำหนดผลแน่นอนสำหรับ manifest ที่กำหนด
PipelineManifest::getStep	string $stepId	ค้นหาแบบเชิงเส้นด้วย step ID	?PipelineStep	ไม่มีการประกาศ	null สำหรับ ID ที่ไม่รู้จัก
PipelineManifest::rootSteps	none	คืนค่าขั้นตอนที่ไม่มีการพึ่งพา	list<PipelineStep>	ไม่มีการประกาศ	ขั้นตอนรากรันก่อน
PipelineManifestBuilder::create	string $manifestId	เริ่ม builder ใหม่	self	ไม่มีการประกาศ	constructor เป็น private นี่คือทางเข้าเดียว
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	ต่อท้ายขั้นตอน; ชนิดเอาต์พุตที่เป็น null จะถูกอนุมานจากชนิดขั้นตอน	self	ไม่มีการประกาศ	การตรวจสอบถูกเลื่อนไปที่ build()
PipelineManifestBuilder::stopOnError	bool $stop = true	ตั้งค่าให้หยุดเมื่อล้มเหลวครั้งแรก	self	ไม่มีการประกาศ	ค่าเริ่มต้นคือ true
PipelineManifestBuilder::maxRetries	int $retries	ตั้งค่าเพดานการลองใหม่ต่อขั้นตอน	self	ไม่มีการประกาศ	ค่าเริ่มต้นคือ 0 (ไม่ลองใหม่)
PipelineManifestBuilder::timeout	int $timeoutMs	ตั้งค่าการหมดเวลาแบบ global ของไปป์ไลน์	self	ไม่มีการประกาศ	0 ปิดการหมดเวลา
PipelineManifestBuilder::resumeFrom	string $stepId	ตั้งค่าจุด resume	self	ไม่มีการประกาศ	ขั้นตอนต้องมีอยู่ในเวลา build()
PipelineManifestBuilder::build	none	สร้าง manifest ที่ผ่านการตรวจสอบ	PipelineManifest	เช่นเดียวกับ PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	ตัวเลือกการดำเนินการที่ไม่เปลี่ยนแปลง	PipelineOptions	ไม่มีการประกาศ	ออบเจ็กต์ค่าแบบ readonly
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	นิยามขั้นตอนที่ไม่เปลี่ยนแปลง	PipelineStep	ไม่มีการประกาศ	การสร้างโดยตรงตั้งค่าชนิดเอาต์พุตเริ่มต้นเป็น PDF สำหรับทุกชนิด
PipelineStep::isRoot	none	เป็น true เมื่อขั้นตอนไม่มีการพึ่งพา	bool	ไม่มีการประกาศ	—
PipelineStepType (enum)	—	สิบเคสที่รองรับด้วยสตริง: generate, merge, split, inspect, compress, sign, convert พร้อมด้วยเคสที่จำกัดสิทธิ์ redact, extract, ocr_overlay	—	—	หนึ่งเคสต่อหนึ่งการดำเนินการในตัว
PipelineStepType::requiresPack	none	เป็น true สำหรับ Redact, Extract และ OcrOverlay	bool	ไม่มีการประกาศ	เคสอื่นทั้งหมดคืนค่า false
PipelineStepType::requiredCapability	none	แมปเคสที่จำกัดสิทธิ์ไปยังรหัสความสามารถ	?string	ไม่มีการประกาศ	null สำหรับเคสที่ไม่จำกัดสิทธิ์
PipelineStatus (enum)	—	ห้าเคส: pending, running, completed, failed, cancelled	—	—	ใช้ร่วมกันโดยผลลัพธ์ของไปป์ไลน์และขั้นตอน
PipelineStatus::isTerminal	none	เป็น true สำหรับ Completed, Failed และ Cancelled	bool	ไม่มีการประกาศ	Pending และ Running ไม่ใช่ขั้นสิ้นสุด
StepOutputType (enum)	—	สามเคส: pdf, json, metadata	—	—	ขับเคลื่อนการตรวจสอบขอบในเวลา build
StepOutputType::forStepType	PipelineStepType $stepType	ชนิดเอาต์พุตเริ่มต้นสำหรับชนิดขั้นตอน	self	ไม่มีการประกาศ	Inspect และ Extract แมปเป็น JSON; ชนิดอื่นทั้งหมดแมปเป็น PDF
StepOutputType::isCompatibleWith	self $expectedInput	เป็น true สำหรับการจับคู่ชนิดเดียวกันหรือเอาต์พุต PDF	bool	ไม่มีการประกาศ	ตัวช่วย; PDF เป็นอินพุตสากล
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	context ในหน่วยความจำต่อการรัน	PipelineContext	ไม่มีการประกาศ	ไม่มี TTL การหมดอายุ การคงอยู่ หรือที่จัดเก็บสำรอง
PipelineContext::setStepResult / ::getStepResult	string $stepId (+ StepResult on set)	บันทึกหรืออ่านผลลัพธ์ขั้นตอน	void / ?StepResult	ไม่มีการประกาศ	null สำหรับขั้นตอนที่ยังไม่ได้ดำเนินการ
PipelineContext::setStepOutput / ::getStepOutput	string $stepId (+ mixed on set)	จัดเก็บหรืออ่านเอาต์พุตระหว่างกลาง	void / mixed	ไม่มีการประกาศ	null สำหรับเอาต์พุตที่ไม่มี
PipelineContext::hasStepResult	string $stepId	ว่าขั้นตอนถูกดำเนินการแล้วหรือไม่	bool	ไม่มีการประกาศ	รองรับการตรวจสอบ resume
PipelineContext::allStepResults	none	ผลลัพธ์ทั้งหมดที่บันทึกไว้จนถึงตอนนี้	array<string, StepResult>	ไม่มีการประกาศ	จัดคีย์ด้วย step ID
PipelineContext::isResume	none	ว่าการรันดำเนินต่อจากขั้นตอนหรือไม่	bool	ไม่มีการประกาศ	—
PipelineResult::isSuccess	none	เป็น true เฉพาะเมื่อสถานะโดยรวมเป็น Completed	bool	ไม่มีการประกาศ	ผลลัพธ์ถูกสร้างโดย executor
PipelineResult::getStepResult	string $stepId	ค้นหาผลลัพธ์ขั้นตอนหนึ่งด้วย ID	?StepResult	ไม่มีการประกาศ	null สำหรับขั้นตอนที่ข้ามหรือไม่รู้จัก
PipelineResult::failedSteps	none	กรองผลลัพธ์ขั้นตอนที่ล้มเหลว	list<StepResult>	ไม่มีการประกาศ	รายการว่างเมื่อสำเร็จทั้งหมด
StepResult::isSuccess	none	เป็น true เฉพาะเมื่อสถานะขั้นตอนเป็น Completed	bool	ไม่มีการประกาศ	มี stepId, type, status, durationMs, error, output
CapabilityResolverInterface::hasCapability	string $capability	การทดสอบสิทธิ์เชิงยืนยันสำหรับรหัสความสามารถหนึ่งรหัส	bool	ต้องไม่โยนข้อยกเว้น	ปฏิเสธโดยการละเว้น: false สำหรับรหัสที่ไม่รู้จัก หมดอายุ หรือไม่ได้แมป

ลายเซ็นจุดเข้าใช้งาน

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

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

การตรวจสอบความถูกต้องของ manifest

การตรวจสอบทำงานใน constructor ของ PipelineManifest ก่อนการดำเนินการใด ๆ ตามลำดับ: รายการขั้นตอนต้องไม่ว่าง; จำนวนขั้นตอนถูกจำกัดที่ 10 000 โดยแปลงห่วงโซ่การพึ่งพาที่ลึกแบบเป็นปฏิปักษ์ให้เป็น OverflowException ที่จับได้แทนที่จะเป็นการหมดสแต็กแบบเนทีฟ; step ID ต้องไม่ซ้ำกัน; การอ้างอิง dependsOn ทุกรายการต้องแก้ไขได้; กราฟการพึ่งพาต้องไม่มีวงจร; ชนิดเอาต์พุตต้องเข้ากันได้; ขั้นตอน resume ที่ประกาศไว้ต้องมีอยู่ การละเมิดแต่ละอย่างจะเกิด InvalidArgumentException พร้อมข้อความเฉพาะ

การตรวจสอบชนิดเอาต์พุตใช้กับขั้นตอนที่ชนิดของมันแมปเป็นเอาต์พุต PDF: การพึ่งพาทุกอย่างของขั้นตอนดังกล่าวต้องสร้างเอาต์พุต PDF ด้วยตัวมันเอง ขอบการพึ่งพาที่เข้าสู่ชนิดขั้นตอนที่สร้าง JSON (inspect, extract) จะไม่ถูกตรวจสอบชนิดในรุ่นนี้

ลำดับการดำเนินการ การ resume และการหมดเวลา

execute($manifest, $variables) สร้าง PipelineContext ใหม่ คำนวณลำดับ topological และรันขั้นตอนตามลำดับนั้นทีละขั้น เมื่อมีการตั้งจุด resume ขั้นตอนก่อนหน้าจะถูกข้ามจนกว่าจะถึงขั้นตอนที่ระบุชื่อ ขั้นตอนก่อนหน้าที่ถูกข้ามจะไม่ถูกรันซ้ำและเอาต์พุตของมันจะไม่ถูกกู้คืน: context เป็นแบบต่อการรันและอยู่ในหน่วยความจำ ดังนั้นขั้นตอนที่ resume ซึ่งอ่านเอาต์พุตของขั้นตอนก่อนหน้าที่ถูกข้ามจะพบค่า null

การหมดเวลาแบบ global เมื่อเป็นค่าบวก จะถูกประเมินระหว่างขั้นตอน ก่อนที่แต่ละขั้นตอนจะเริ่ม เมื่อหมดเวลา สถานะไปป์ไลน์จะกลายเป็น Failed และขั้นตอนที่เหลือจะไม่เริ่ม ขั้นตอนที่กำลังรันอยู่แล้วจะไม่ถูกขัดจังหวะกลางการดำเนินการ ดังนั้นขั้นตอนยาวขั้นตอนเดียวอาจใช้เวลาเกินงบประมาณได้

การลองใหม่และการเก็บบันทึกความล้มเหลว

แต่ละขั้นตอนได้รับความพยายามมากที่สุด maxRetries + 1 ครั้ง ความพยายามที่สำเร็จจะคืนค่าทันที ความพยายามที่ล้มเหลวใด ๆ — ผลลัพธ์ Failed จาก resolver หรือ Throwable ที่ถูกโยน — จะถูกลองใหม่ขณะที่ยังมีความพยายามเหลืออยู่; ผลลัพธ์ของความพยายามครั้งสุดท้ายจะถูกคืนค่า Throwable ที่เกิดขึ้นภายใน resolver จะถูกลดระดับเป็นผลลัพธ์ขั้นตอนแบบ Failed ที่มีข้อความข้อยกเว้น หรือ Unknown error เมื่อข้อความว่างเปล่า ดังนั้น execute() จึงคืนค่า PipelineResult เสมอ โดยไม่เคยส่งต่อความล้มเหลวของ resolver

ชนิดขั้นตอนที่ไม่มี resolver ลงทะเบียนจะให้ผลลัพธ์ขั้นตอนแบบ Failed พร้อมข้อความที่ชัดเจน โดยไม่ยกเลิกการรัน เมื่อ stopOnError เป็น true (ค่าเริ่มต้น) การดำเนินการจะหยุดที่ขั้นตอนแรกที่ล้มเหลวและสถานะไปป์ไลน์จะเป็น Failed เมื่อเป็น false การดำเนินการจะดำเนินต่อและสถานะสุดท้ายจะเป็น Failed หากมีขั้นตอนใดล้มเหลว มิฉะนั้นจะเป็น Completed

เกตความสามารถของ pack

ก่อนการส่งไปยัง resolver ใด ๆ ทุกขั้นตอนที่จำกัดสิทธิ์ตาม pack (Redact, Extract, OcrOverlay) จะถูกตรวจสอบกับ CapabilityResolverInterface ที่ฉีดเข้ามา เกตเป็นแบบ fail-closed: resolver ที่ขาดหายไป คำตอบ false หรือรหัสความสามารถที่ไม่ได้แมป ล้วนปฏิเสธขั้นตอน การปฏิเสธจะสร้างผลลัพธ์ขั้นตอนแบบ Failed ซึ่งข้อผิดพลาดมีรหัส SPEC-LIC-001 ชนิดขั้นตอน และความสามารถที่ต้องใช้ การปฏิเสธที่จำกัดสิทธิ์จะไม่ใช้ความพยายามลองใหม่และรายงานระยะเวลาเป็น 0.0 การนำ resolver ไปใช้ต้องคืนค่า true เฉพาะสำหรับสิทธิ์ที่ถือครองเชิงยืนยันเท่านั้น และต้องไม่โยนข้อยกเว้น

การรวมผลลัพธ์

PipelineResult รายงาน manifest ID สถานะโดยรวม ผลลัพธ์ต่อขั้นตอนตามลำดับการดำเนินการ ระยะเวลารวมเป็นมิลลิวินาที และจำนวนขั้นตอนทั้งหมด ที่สำเร็จ และที่ล้มเหลว stepsTotal นับทุกขั้นตอนใน manifest รวมถึงขั้นตอนที่ถูกข้ามโดย resume หรือที่ไปไม่ถึงหลังจากหยุด; stepsCompleted และ stepsFailed นับเฉพาะขั้นตอนที่ถูกดำเนินการ

กรณีขอบและโหมดความล้มเหลว

• executor ออกแบบมาเพื่อการดำเนินการแบบ asynchronous ภายใน job worker การใช้งานแบบ inline จะบล็อกผู้เรียกใช้ตลอดระยะเวลาทั้งหมดของไปป์ไลน์
• การหมดเวลาแบบ global เป็นการตรวจสอบระหว่างขั้นตอน ขั้นตอนยาวขั้นตอนเดียวอาจใช้เวลาเกินงบประมาณได้; ไม่มีขั้นตอนใดถูกขัดจังหวะระหว่างทาง
• resume ข้ามขั้นตอนภายในการดำเนินการเดียวกันเท่านั้น ไม่กู้คืนเอาต์พุตจากที่จัดเก็บใด ๆ; การ resume ข้ามการรันพร้อมเอาต์พุตที่แคชไว้ไม่ได้ถูกนำมาใช้
• การสร้าง PipelineStep โดยตรงตั้งค่าชนิดเอาต์พุตเริ่มต้นเป็น PDF สำหรับทุกชนิดขั้นตอน ให้ใช้ builder หรือส่งชนิดเอาต์พุตอย่างชัดเจน เพื่อให้ขั้นตอน inspect และ extract ประกาศเอาต์พุต JSON และการตรวจสอบขอบยังคงมีความหมาย
• ข้อยกเว้นของ resolver ที่มีข้อความว่างเปล่าจะถูกทำให้เป็นมาตรฐานเป็น Unknown error ในผลลัพธ์ขั้นตอน
• ผลลัพธ์ขั้นตอนแบบ Failed ที่สร้างโดยเกตหรือโดย resolver ที่ขาดหายไปจะรายงานระยะเวลาเป็น 0.0
• PipelineResult::getStepResult() คืนค่า null ทั้งสำหรับ ID ที่ไม่รู้จักและสำหรับขั้นตอนที่ถูกข้ามโดย resume หรือการหยุด; แยกความแตกต่างผ่าน stepsTotal เทียบกับความยาวของรายการผลลัพธ์
• โมดูลนี้ไม่ทำการดำเนินการเชิงการเข้ารหัสลับใด ๆ และไม่นิยามพฤติกรรมเฉพาะ FIPS ท่าทีด้าน FIPS สำหรับขั้นตอน sign ถูกกำกับโดยโมดูลการลงนาม ไม่ใช่โดยไปป์ไลน์

ความสอดคล้อง

ไปป์ไลน์ไม่ทำงานด้านความสอดคล้องของรูปแบบด้วยตัวเอง ความสอดคล้องของแต่ละอาร์ติแฟกต์ที่สร้างขึ้นเป็นของโมดูลที่อยู่เบื้องหลังขั้นตอนที่ดำเนินการ — การลงนาม การเพิ่มประสิทธิภาพ การแปลง และอื่น ๆ — และถูกบันทึกไว้ในหน้าอ้างอิงของโมดูลเหล่านั้น หน้านี้ไม่ยืนยันตัวระบุข้อกำหนดภายนอกใด ๆ; ทุกข้อความมีพื้นฐานจากซอร์สของผลิตภัณฑ์ NextPDF ไม่อ้างการรับรองใด ๆ

หมายเหตุการพัฒนา

• ซอร์สของโมดูลมี @since 2.2.0; เอกสารอ้างอิงนี้บันทึกพื้นผิวตามที่จัดส่งใน nextpdf/pro 3.1.0
• คลาสทั้งหมดเป็น final; ชนิด manifest ตัวเลือก ขั้นตอน และผลลัพธ์เป็นออบเจ็กต์ค่าแบบ readonly สร้างอินสแตนซ์ใหม่แทนการเปลี่ยนแปลง
• StepResolverInterface และ StepResolverRegistry เป็น @internal step resolver เป็นแบบในตัวเท่านั้น; ตัวจัดการขั้นตอนแบบกำหนดเองที่ผู้ใช้นิยามไม่ได้รับการรองรับในรุ่นนี้
• CapabilityResolverInterface เป็นตะเข็บสิทธิ์สาธารณะ การนำไปใช้ต้องเป็นแบบปฏิเสธโดยการละเว้นและต้องไม่อนุญาตโดยค่าเริ่มต้น
• executor PHP นี้เป็นเส้นทางการตรวจสอบ manifest และการดำเนินการตามลำดับ; การปรับใช้ในโปรดักชันอาจส่งผ่าน sidecar เพื่อการจัดการแบบขนาน เกตความสามารถบนเส้นทาง PHP เป็นแบบ fail-closed อย่างเป็นอิสระในทั้งสองกรณี
• รายละเอียดกลไกภายในอยู่ในเอกสารภายในของที่เก็บซอร์สและอยู่นอกขอบเขตของคู่มือนี้

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

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

ดูเพิ่มเติม

• Output Pipeline — หน้าความสามารถสำหรับคำแนะนำเวิร์กโฟลว์
• Output Pipeline — เอกสารอ้างอิงเชิงลึก NextPDF Enterprise — การจัดการแบบแบตช์ข้าม manifest
• Document — เอกสารอ้างอิงเชิงลึก
• Accelerator — เอกสารอ้างอิงเชิงลึก