تخطَّ إلى المحتوى
NextPDF

نظرة عامة على NextPDF Artisan

لمحة سريعة

قسم بعنوان «لمحة سريعة»

⁨NextPDF Artisan⁩ هو جسر ⁨Chrome⁩ في ⁨NextPDF.⁩ يرسل جزءًا من لغة ترميز النص التشعبي (⁨HTML⁩) إلى عملية ⁨Chrome⁩ بلا واجهة عبر ⁨Chrome DevTools Protocol⁩ (⁨CDP⁩)، ويلتقط مخرجات printToPDF، ثم يضمّن النتيجة في مستند تنسيق المستندات المحمولة (⁨PDF⁩) الهدف على شكل ⁨Form XObject.⁩ ويظل النص المُضمَّن قابلًا للتحديد والبحث.

نظرة عامة مفاهيمية

قسم بعنوان «نظرة عامة مفاهيمية»

تُوسِّع حزمة ⁨Artisan⁩ (nextpdf/artisan) محرك ⁨NextPDF⁩ مفتوح المصدر بمُصيِّر يُفوِّض التخطيط إلى ⁨Chrome.⁩ يغطي مسار ⁨HTML⁩ الأصلي في ⁨NextPDF⁩ بالفعل مجموعة فرعية واسعة من صفحات الأنماط المتتالية (⁨CSS⁩). استخدم جسر ⁨Artisan⁩ للمستندات التي تحتاج إلى تخطيط بمستوى ⁨Chrome⁩، بما في ذلك ⁨CSS flexbox⁩ و⁨grid⁩، وخطوط الويب المخصصة المُحمَّلة من مصادر معرّف الموارد الموحّد (⁨URI⁩) بصيغة ⁨data⁩، والمحدِّدات المعقّدة، مع الاستمرار في إنتاج نص متجهي بدلًا من لقطة شاشة منقّطة.

يعمل الجسر كمسار يضم مكوّنات صغيرة ذات غرض واحد. يُنسِّق ChromeHtmlRenderer عملية العرض. يتحقق ChromeSecurityPolicy من المُدخَل ويغلّفه في مستند ⁨HTML⁩ مُحكَم القيود. يدير BrowserPool دورة حياة عملية ⁨Chrome.⁩ يُحوِّل ViewportCalculator نقاط ⁨PDF⁩ إلى بكسلات ⁨CSS.⁩ يحلل قارئ NextPDF\Parser مخرجات ⁨Chrome⁩، ويُحوِّلها PageImporter إلى ⁨Form XObject.⁩ كل مكوّن final، ويُحقَن عبر الباني، ومُحدَّد الأنواع عند ⁨PHPStan⁩ المستوى 10.

الجسر مُقيَّد باعتماديات خارجية. يحتاج إلى مكتبة chrome-php/chrome (^1.15) وإلى ملف ⁨Chrome⁩ أو ⁨Chromium⁩ ثنائي يمكن لعملية ⁨PHP⁩ الوصول إليه. ولا يأتي أيٌّ منهما مُرفقًا ضمن الحزمة. عند غياب المكتبة، يُطلِق الجسر ChromeNotAvailableException بدلًا من الإخفاق الصامت؛ انظر /⁨integrations/artisan/failure-modes/⁩ في صفحة /⁨integrations/artisan/troubleshooting/.⁩

لا يرسل المُصيِّر أي محتوى إلى ⁨Chrome⁩ إطلاقًا حتى يجتاز المُدخَل ChromeSecurityPolicy::validate(). يُغلَّف المستند الذي يستقبله ⁨Chrome⁩ دائمًا بسياسة أمان محتوى (⁨CSP⁩) صارمة عبر ترويسة ⁨Content-Security-Policy⁩ وحظر شبكي على مستوى ⁨CDP⁩ وفق مبدأ الدفاع المتعمّق. ولأن الجسر يعالج ⁨HTML⁩ قد يكون غير موثوق، توثّق صفحة /⁨integrations/artisan/security-and-operations/⁩ نموذج النقل والعزل الخاص به بدلًا من تلخيصه هنا.

تصف هذه الصفحة سلوك الحزمة كما تُشحَن، وقد جرى التحقق منه مقابل src/Artisan/ ومجموعة اختبارات tests/Unit/Artisan/. ولا تقدّم ادعاءً بالمطابقة بكسلًا ببكسل مع متصفح ⁨Chrome⁩ التفاعلي: تُلتقط الحركات عند إطارها الأخير، ولا يعتمد التخطيط على ⁨JavaScript⁩، ولا تُستورد إلا صفحة ⁨Chrome⁩ الأولى فقط.

البنية المعمارية

قسم بعنوان «البنية المعمارية»

HTML fragment

ChromeSecurityPolicy::validate()

ChromeSecurityPolicy::wrapHtml()

CSP + reset CSS

BrowserPool

headless Chrome

CDP: Network.setBlockedURLs '*'

Page.setDocumentContent

Chrome printToPDF

NextPDF\\Parser\\PdfReader

PageImporter → Form XObject

Embedded in target PDF

(text selectable)

Diagram

مسؤوليات المكوّنات

قسم بعنوان «مسؤوليات المكوّنات»
المكوّنالمسؤوليةالمصدر
ChromeHtmlRendererيُنسِّق عملية عرض واحدة؛ ويُرجِع ChromeRenderResultsrc/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfigكائن قيمة تكوين غير قابل للتغييرsrc/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicyالتحقق من المُدخَل + تغليف ⁨HTML⁩ آمنsrc/Artisan/ChromeSecurityPolicy.php
BrowserPoolدورة حياة عملية ⁨Chrome⁩ وسياسة إعادة التشغيلsrc/Artisan/BrowserPool.php
ViewportCalculatorتحويل 72 ⁨pt/inch⁩ ↔ 96 ⁨px/inch⁩src/Artisan/ViewportCalculator.php
ChromeRenderResultمخرجات عرض محدَّدة الأنواع (ChromeRenderResultInterface)src/Artisan/ChromeRenderResult.php
PageImporterصفحة ⁨Chrome⁩ مُحلَّلة ← ImportedFormXObjectsrc/Artisan/PageImporter.php
EInvoiceServiceFactoryمصنع بلا حاوية لعقود الفاتورة الإلكترونية في ⁨Premium⁩src/Artisan/EInvoiceServiceFactory.php

الحالات الحدّية والمزالق

قسم بعنوان «الحالات الحدّية والمزالق»
  • سلسلة الإصدارات. يحمل أثر ⁨Composer⁩ المنشور الوسم v0.1.0. تحمل كتل التوثيق في المصدر @since 1.7.0 (جسر ⁨Chrome⁩) و@since 1.1.0 (مصنع الفاتورة الإلكترونية)، وكلاهما موروث من سلسلة إصدارات nextpdf/core قبل إعادة التسمية؛ وقد أُعيدت تسمية الحزمة إلى nextpdf/artisan في مدخلة ⁨CHANGELOG⁩ للإصدار 2.0.0. اعتبر وسم ⁨Composer⁩ إصدار التثبيت الموثوق، واعتبر علامات @since سجلًا لتاريخ إصدارات المحرك.
  • الصفحة الأولى فقط. يستخدم PageImporter::import() فهرس الصفحة 0 افتراضيًا. يُقتطع المحتوى الذي يفيض إلى صفحة ⁨Chrome⁩ ثانية ما لم تُحدِّد ارتفاعًا صريحًا، كما هو موضّح في صفحة /⁨integrations/artisan/production-usage/.⁩
  • لا حاوية حقن اعتماديات (⁨DI⁩). ⁨Artisan⁩ بلا حاوية. يمنح EInvoiceServiceFactory البيئات التي لا تملك حاوية خدمات طريقة متسقة لإنشاء نُسخ الخدمات؛ انظر /⁨integrations/artisan/boot-and-discovery/.⁩

الأداء

قسم بعنوان «الأداء»

تتحمل كل عملية عرض كلفة تحميل صفحة ⁨Chrome⁩ وتشغيل printToPDF مرة واحدة لكل استدعاء. يُبقي BrowserPool عملية ⁨Chrome⁩ حية بين عمليات العرض ويُعيد تشغيلها كل 100 عملية عرض لتقييد نمو الذاكرة. عمل التخطيط في ⁨Chrome⁩، لا الجسر نفسه، هو ما يهيمن على سلوك ⁨Big-O.⁩ للاطلاع على الميزانية المُقاسة للمسار المرجعي في هذه الصفحة، انظر performance_budget في البيانات الأمامية وصفحة /⁨integrations/artisan/production-usage/.⁩

ملاحظات أمنية

قسم بعنوان «ملاحظات أمنية»

يعرض الجسر ⁨HTML⁩ قد يكون غير موثوق داخل ⁨Chrome.⁩ يُتحقَّق من حجم المُدخَل ومحتواه قبل أن يراه ⁨Chrome.⁩ يحمل المستند المُغلَّف default-src 'none'. يوقف حظر على مستوى ⁨CDP⁩ كل طلب لمورد فرعي. يوجد نموذج النقل والعزل الكامل، بما في ذلك الحدود الصريحة لراية وضع ⁨Chrome⁩ الرملي، في صفحة /⁨integrations/artisan/security-and-operations/.⁩ لا تعتبر هذا القسم وصفًا كاملًا للوضع الأمني.

السياق التجاري

قسم بعنوان «السياق التجاري»

يعرض الجسر مفتوح المصدر ⁨HTML⁩ إلى ⁨PDF.⁩ تضيف فئات ⁨Premium⁩ تضمين فاتورة إلكترونية متوافقًا (⁨Pro⁩) والتحقق منها (⁨Enterprise⁩) فوق المستند المعروض. عندما لا تكون تلك الفئات مثبتة، يُرجِع EInvoiceServiceFactory القيمة null، ويبقى مسار المصدر المفتوح فعّالًا بالكامل دونها.

انظر أيضًا

قسم بعنوان «انظر أيضًا»
  • /integrations/artisan/install/
  • /integrations/artisan/configuration/
  • /integrations/artisan/quickstart/
  • /integrations/artisan/chrome-renderer-setup/
  • /integrations/artisan/security-and-operations/
  • /integrations/artisan/production-usage/