دليل المطوّر لحزمة Artisan

لمحة سريعة

تتولّى حزمة ⁨Artisan⁩ مسؤوليتين مترابطتين: تصيير لغة ترميز النص الفائق (⁨HTML⁩) عبر ⁨Chrome⁩، واستيراد صفحة صيغة المستند المحمول (⁨PDF⁩) الناتجة إلى مستند ⁨NextPDF.⁩ عند تنقيح المشكلات، افصل بوضوح بين حدود ⁨Chrome⁩ والمُحلِّل والمُستورِد.

استخدم هذا الدليل عند كتابة تكاملات المُصيِّر، أو العمليات المُعالِجة طويلة العمر، أو تشخيصات المُحلِّل، أو الاختبارات الخاصة بـ nextpdf/artisan.

حدود المعمارية

الطبقة	مملوكة لـ	المسؤولية	لا تضع هنا
التطبيق	التطبيق	تفويض إنشاء ⁨HTML⁩ واختيار إعدادات المُصيِّر.	إدارة عملية المتصفح.
سياسة ⁨HTML⁩	التطبيق والحزمة	رفض ⁨HTML⁩ غير الآمن أو الزائد في الحجم قبل التصيير.	تفويض المستأجر أو القرارات التجارية.
مُصيِّر ⁨Chrome⁩	`nextpdf/artisan`	تصيير ⁨HTML⁩ إلى ملف ⁨PDF⁩ مستقل يُنتجه ⁨Chrome.⁩	إصلاح ⁨PDF⁩ عمومًا أو تحرير ⁨PDF⁩ على نحو تعسّفي.
المُحلِّل/المُستورِد	`nextpdf/artisan`	تحليل ملف ⁨PDF⁩ المُصيَّر واستيراد صفحة واحدة بوصفها كائن نموذج ⁨XObject.⁩	التحقّق الكامل من مطابقة ⁨PDF.⁩
المحرّك الأساسي	`nextpdf/nextpdf`	وضع كائنات النموذج المُستورَدة وكتابة المستند النهائي.	إدارة دورة حياة بروتوكول أدوات مطوّري ⁨Chrome⁩ (⁨CDP⁩).

دورة حياة التشغيل

المرحلة	السلوك	إجراء المطوّر
إنشاء الإعدادات	يعرّف `ChromeRendererConfig` الملف الثنائي والمهلة وأوراق الأنماط المتراصّة (⁨CSS⁩) وحجم الإدخال وسلوك الصندوق الرملي.	استخدم إعدادات خاصة بالبيئة بدلاً من تخمينات وقت التشغيل المُثبَّتة في الشيفرة.
إنشاء المُصيِّر	يمتلك `ChromeHtmlRenderer` كائن `BrowserPool`.	أعد استخدام المُصيِّر داخل العملية المُعالِجة، ثم أغلقه أثناء إيقاف التشغيل.
التحقّق من ⁨HTML⁩	تتحقّق سياسة الأمان من الحجم وتُحيط المستند بأوراق أنماط ⁨CSS⁩ الافتراضية.	تحقّق من تفويض المُستدعي قبل هذه المرحلة.
طباعة ⁨Chrome⁩	يُصيِّر ⁨CDP⁩ ملف ⁨PDF⁩ مستقلاً.	أبقِ الموارد الخارجية محظورة ما لم تسمح بها سياسة خضعت للمراجعة.
تحليل ⁨PDF⁩	يقرأ `PdfReader::parse()` بيانات المرجع التبادلي ⁨xref⁩ والصفحات والكائنات والموارد والمراجعات.	عامِل إخفاقات المُحلِّل مثل إخفاقات التصيير ما لم تكن التشخيصات هي الهدف.
استيراد الصفحة	`PageImporter::import()` يستخرج محتوى الصفحة وصندوق الوسائط والموارد والكائنات المُضمَّنة.	استورِد الصفحة `0` ما لم يختر سير العمل صفحة أخرى عن قصد.

بنية التطبيق المُوصى بها

المسار	الغرض
`app/Pdf/Renderers/*`	غلاف التطبيق حول `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	تصيير قوالب ⁨HTML⁩ وتعيين كائن نقل البيانات (⁨DTO⁩) إلى العرض.
`app/Pdf/Policies/*`	سياسة تصيير حجم ⁨HTML⁩ والموارد والمستأجر.
`tests/Pdf/Renderer/*`	اختبارات دخان للمُصيِّر باستخدام عيّنات ⁨HTML⁩ صغيرة.
`tests/Pdf/Parser/*`	عيّنات المُحلِّل لمُخرَجات ⁨Chrome⁩ المُستورَدة.

افصل تصيير القوالب عن تصيير المتصفح. مرّر إلى المُصيِّر ملف ⁨HTML⁩ النهائي وعرض صفحة معروفًا.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

$result = $renderer->render($html, widthPt: 595.28);

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

نمط المُصيِّر

أنشئ مُصيِّرًا واحدًا لكل عملية مُعالِجة أو لكل نطاق طلب. أعد استخدامه لتجنّب تكلفة بدء تشغيل ⁨Chrome⁩ المتكرّرة. أغلقه صراحةً لمنع تسرّب العمليات عند إيقاف تشغيل العملية المُعالِجة.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

نمط تشخيص المُحلِّل

استخدم واجهات برمجة التطبيقات (⁨APIs⁩) الخاصة بالمُحلِّل عند إخفاق استيراد مُخرَجات ⁨Chrome.⁩ أبقِ التشخيصات للقراءة فقط، وتجنّب تغيير حالة المُحلِّل بعد أي استيراد ناجح.

سؤال التشخيص	الواجهة البرمجية المستخدَمة	الإشارة المتوقّعة
هل يمكن تحليل الملف؟	`PdfReader::parse()`	يطلق استثناءً عند وجود بنية ⁨PDF⁩ غير صالحة.
هل توجد الصفحة `0`؟	`PdfReader::getPage(0)`	يُعيد كائن `PdfObject`.
هل يوجد محتوى؟	`PdfReader::getPageContentStream($page)`	دفق محتوى غير فارغ.
هل الموارد موجودة؟	`PdfReader::getPageResources($page)`	مصفوفة قاموس الموارد.
هل توجد مراجعات تزايدية؟	`PdfReader::getRevisionCount()`	عدد أكبر من واحد.
أيُّ كائن أخفق؟	`PdfTokenizer::getOffset()` وسياق استثناء المُحلِّل.	إزاحة بايت تساعد على تقليل العيّنة.

نقاط التوسعة

نقطة التوسعة	استخدمها لـ	القيد
`ChromeRendererConfig::fromArray()`	تعيين إعدادات إطار العمل.	تعود القيم الاختيارية غير المعروفة أو ذات النوع الخاطئ إلى القيم الافتراضية.
`HtmlSecurityPolicyInterface`	سياسة ⁨HTML⁩ على طبقة التحليل.	لا يحلّ محل ضوابط النقل أو العمليات أو التفويض.
`LoggerInterface`	تشخيصات التصيير والمتصفح.	لا تُسجِّل محتوى ⁨HTML⁩ افتراضيًا.
`BrowserPool`	إعادة استخدام عملية ⁨Chrome⁩ طويلة العمر.	يجب إغلاقه عند إيقاف تشغيل العملية المُعالِجة.
`PageImporter`	تضمين صفحة خارجية محلَّلة.	يجب تحليل القارئ أولاً.
فئات المُحلِّل	التشخيصات ومُخرَجات ⁨Chrome⁩ المُستورَدة.	ليست مجموعة أدوات عامة لإصلاح ⁨PDF.⁩

سير عمل التطوير

أعد إنتاج مقتطف ⁨HTML⁩ في اختبار تصيير مُصغَّر.
تحقّق من maxHtmlSize وأوراق أنماط ⁨CSS⁩ الافتراضية ومسار ملف ⁨Chrome⁩ الثنائي.
صيِّر بعرض ثابت بالنقاط.
حلِّل بايتات ⁨PDF⁩ المُعادة باستخدام PdfReader::parse().
استورِد الصفحة 0 ما لم يختر سير العمل صفحة أخرى عن قصد.
أضف اختبارات عيّنات لأصغر ⁨HTML⁩ يعيد إنتاج كل إخفاق.
أغلق المُصيِّر في خطّافات إيقاف تشغيل العملية المُعالِجة.

معالجة الإخفاقات

الإخفاق	أين ينبغي معالجته	الاستجابة المُوصى بها
ملف ⁨Chrome⁩ الثنائي مفقود	فحص النشر ومسار إنشاء المُصيِّر.	أفشِل فحص الجاهزية قبل قبول حركة التصيير.
⁨HTML⁩ مفرط الحجم	سياسة ⁨HTML.⁩	ارفضه قبل بدء تشغيل ⁨Chrome.⁩
مهلة المتصفح	حدّ المُصيِّر.	أفشِل التصيير، وسجِّل اسم القالب والحجم والعرض والمهلة.
إخفاق المُحلِّل	حدّ الاستيراد.	خزِّن عيّنة صغيرة مُطهَّرة للتنقيح عندما تسمح السياسة بذلك.
تسرّب عملية المتصفح	دورة حياة العملية المُعالِجة.	أغلق عند إيقاف التشغيل، وأعد التشغيل بعد أعداد تصيير مضبوطة.

القيم الافتراضية الآمنة

الاهتمام	الافتراضي	متى يُتجاوَز
مهلة التصيير	`30` ثانية.	زِدها للمستندات ذات القياس المعروف والمحدودة فقط.
الحد الأقصى لحجم ⁨HTML⁩	`5,000,000` بايت.	اخفِضها لنقاط النهاية العامة.
الصندوق الرملي	مُفعَّل.	عطِّله فقط عندما تتطلّب قيود الحاوية ذلك، ويكون المضيف معزولاً.
الارتفاع	تلقائي عندما `heightPt <= 0`.	استخدم ارتفاعًا ثابتًا لعقود التخطيط الصارمة.
الموارد الخارجية	محظورة بموجب سياسة المُصيِّر.	اسمح بها فقط عبر سياسة موارد خضعت للمراجعة.

قائمة تحقّق الاختبار

اختبارات التصيير تغطّي ⁨HTML⁩ و⁨CSS⁩ تمثيليين.
اختبارات الأمان تغطّي ⁨HTML⁩ مفرط الحجم ومحاولات الوصول إلى الموارد المحظورة.
اختبارات الاستيراد تؤكّد أن كائن النموذج المُعاد يحتوي على محتوى وصندوق وسائط وموارد.
اختبارات المُحلِّل تغطّي جدول المرجع التبادلي (⁨xref⁩) ودفق ⁨xref⁩ ودفق الكائنات وحالات العيّنات المُشوَّهة.
اختبارات العملية المُعالِجة تستدعي close() وتتحقّق من عدم بقاء أي عملية متصفح.
اختبارات الأداء تسجّل زمن التصيير حسب القالب وحجم المحتوى.