إقلاع NextPDF Artisan وآلية اكتشافه

لمحة سريعة

‏⁨Artisan⁩ مكتبة عادية تتبع توصية ⁨PHP⁩ المعيارية 4 ‏(⁨PSR-4⁩). لا تتضمن مزوّد خدمة، أو حزمة، أو بيان اكتشاف تلقائي لإطار العمل. تُقلِع بمجرد أن تصبح أصنافها قابلة للتحميل التلقائي. الاكتشاف هنا هو خريطة ⁨PSR-4⁩ الخاصة بـ ⁨Composer⁩، لا أكثر.

كيف يعمل الاكتشاف

تُعلِن الحزمة composer.json عن جذرين من جذور ⁨PSR-4⁩: NextPDF\Artisan\ → src/Artisan/ وNextPDF\Parser\ → src/Parser/. ولا تتضمّن extra.laravel، أو صنف حزمة ⁨Symfony⁩، أو مُسجِّل ⁨CodeIgniter.⁩ لا يوجد ما يفحص أو يسجّل أو يربط خطافات أثناء الإقلاع.

تقع نقطة التكامل في nextpdf/core. يوفّر Document (عبر الاختصاص HasTextOutput) الدالة writeHtmlChrome()، التي تتحقق من class_exists() في وقت التشغيل لكلٍّ من NextPDF\Parser\PdfReader وNextPDF\Artisan\PageImporter. عندما يستطيع المُحمِّل التلقائي حلّ كلا الصنفين، يصبح مسار ⁨Chrome⁩ متاحًا. وعندما يتعذّر ذلك، يُطلِق ⁨core⁩ استثناء تخطيط بدلًا من أن يخفق بخطأ فادح. لذلك يطرح الاكتشاف سؤالًا واحدًا: هل أصناف ⁨Artisan⁩ موجودة في المُحمِّل التلقائي؟ ‏⁨Composer⁩ هو من يجيب عن ذلك؛ ولا تتدخّل أي آلية من آليات إطار العمل.

هذا مقصود. الجسر قدرة يصل إليها المحرك الأساسي عبر حدود الحزمة، وليس خدمة يديرها إطار العمل. يمكنك استخدام ⁨Artisan⁩ بالطريقة نفسها في ⁨Laravel⁩ أو ⁨Symfony⁩ أو ⁨CodeIgniter⁩ أو سكربت واجهة سطر الأوامر ‏(⁨CLI⁩) أو عامل طابور، لأن أيًّا من تلك المضيفات غير مطلوب.

تسلسل الإقلاع

Diagram

لا يحتوي ⁨Artisan⁩ على نواة إقلاع، أو تسجيل أوامر، أو مرحلة مزوّد مؤجَّل. أول استدعاء لـ writeHtmlChrome() هو مدخل دورة الحياة بأكملها.

روابط الحاوية

لا يملك ⁨Artisan⁩ حاوية حقن تبعيات ‏(⁨DI⁩)، ولا يسجّل أي روابط. مكوّناته كائنات عادية تُحقَن عبر الباني: أنشئ ChromeRendererConfig، ومرّره إلى ChromeHtmlRenderer، واحقن اختياريًّا مُسجِّل أحداث ⁨PSR-3⁩ وHtmlSecurityPolicyInterface مخصَّصًا. داخل حاوية مضيفة، سجّل ChromeHtmlRenderer بنفسك ككائن وحيد؛ راجع المثال في /⁨integrations/artisan/production-usage/.⁩

حلّ الخدمات بلا حاوية

تُحلّ بعض قدرات ⁨NextPDF⁩، بما في ذلك عقود الفواتير الإلكترونية في ⁨Premium⁩، عادةً عبر حاوية إطار العمل. يعمل ⁨Artisan⁩ أيضًا في بيئات بلا حاوية، مثل أدوات ⁨CLI⁩ والسكربتات المستقلة والمُشغِّلات المخصَّصة، لذلك يأتي مزوَّدًا بـ EInvoiceServiceFactory:

الدالة	القيمة المُرجَعة	متى تكون `null`
`makeEmbedder()`	`EmbedderInterface` (إصدار ⁨Pro⁩)	إصدار ⁨Pro⁩ غير مُثبَّت
`makeValidator()`	`ValidatorInterface` (إصدار ⁨Enterprise⁩)	إصدار ⁨Enterprise⁩ غير مُثبَّت
`makeDefaultProfile()`	`ProfileInterface` (⁨EN16931⁩، إصدار ⁨Pro⁩)	إصدار ⁨Pro⁩ غير مُثبَّت
`makeSchematronRunner()`	`SchematronRunnerInterface` (إصدار ⁨Enterprise⁩)	إصدار ⁨Enterprise⁩ غير مُثبَّت

يُرجِع كل استدعاء نسخة جديدة. وسلوك الاستخدام لمرة واحدة هذا مهم لأن استدعاءات التضمين والتحقق تمتلك سياق تحليل قابلًا للتغيير للغة الترميز القابلة للتوسعة ‏(⁨XML⁩)، ويجب ألا تتشارك الحالة. المصنع تيسير للحالة النادرة التي لا توجد فيها حاوية، وليس محدِّد خدمات. يظل النمط المفضَّل هو تركيب الكائنات عند الإنشاء وتمريرها كوسائط للباني. يحاكي إرجاع ⁨null⁩ عند غياب أحد الإصدارات حِزم تغليف أُطر العمل، فتعمل شيفرة الاستدعاء نفسها مع ⁨Premium⁩ أو بدونه. المصدر: src/Artisan/EInvoiceServiceFactory.php؛ ومُختبَر تكامليًّا في tests/Integration/Artisan/EInvoiceServiceFactoryIntegrationTest.php.

ترتيب حلّ الإعدادات

لا يوجد تسلسل لملفات الإعدادات. فالإعدادات هي بالضبط ما تمرّره إلى ChromeRendererConfig:

وسائط الباني التي تمرّرها صراحةً، أو
ChromeRendererConfig::fromArray() من مصفوفة يوفّرها المضيف (مفاتيح بنمط ⁨snake-case⁩؛ المفاتيح غير المضبوطة تعود إلى افتراضيات الباني؛ ولا يُطبَّق chrome_binary إلا عندما يكون سلسلة نصية غير فارغة).

تبقى الإعدادات المحلولة غير قابلة للتغيير طوال عمر العارض. راجع /⁨integrations/artisan/configuration/⁩ للاطلاع على كل مفتاح.

التشخيص

“هل الجسر قابل للاكتشاف؟” — إذا كانت class_exists(\NextPDF\Artisan\PageImporter::class) تساوي true، فيستطيع مُحمِّل ⁨Composer⁩ التلقائي العثور عليه، وسيستخدم ⁨core⁩ مسار ⁨Chrome.⁩
“هل أقلَع؟” — لا توجد مرحلة إقلاع يمكن أن تخفق؛ إذ تظهر أي تبعية مفقودة عند أول استدعاء لـ writeHtmlChrome() على هيئة استثناء مُصنَّف، مُوثَّق في /⁨integrations/artisan/troubleshooting/.⁩
فحص ⁨Premium⁩ بلا حاوية — EInvoiceServiceFactory::makeEmbedder() === null يعني أن إصدار ⁨Pro⁩ غير مُثبَّت؛ ولا يؤثّر ذلك في مسار العرض مفتوح المصدر.

انظر أيضًا

/integrations/artisan/integration/
/integrations/artisan/overview/
/integrations/artisan/configuration/
/integrations/artisan/production-usage/
/integrations/artisan/troubleshooting/