تثبيت NextPDF Artisan

لمحة سريعة

ثبّت nextpdf/artisan باستخدام ⁨Composer.⁩ يثبّت ⁨Composer⁩ أيضًا اعتمادية وقت التشغيل chrome-php/chrome. ثم وفّر ملف ⁨Chrome⁩ أو ⁨Chromium⁩ التنفيذي لعملية ⁨PHP.⁩

التثبيت

composer require nextpdf/artisan

تُعلن الحزمة القيود الآتية في composer.json:

المتطلب	القيد	ملاحظات
`php`	`>=8.4 <9.0`	⁨PHP 8.4⁩ فقط
`nextpdf/core`	`^3.0 \|\| ^5.2`	محرّك ⁨NextPDF⁩ مفتوح المصدر
`chrome-php/chrome`	`^1.15`	مكتبة عميل ⁨Chrome DevTools Protocol⁩ (⁨CDP⁩)؛ تُجلب بصورة متعدّية
`psr/log`	`^3.0`	نقطة حقن اختيارية لمسجّل السجلات

يحلّ ⁨Composer⁩ chrome-php/chrome تلقائيًا. لا يُثبّت ⁨Composer⁩ أبدًا الملف التنفيذي لـ ⁨Chrome⁩؛ إذ يبقى هذا الملف التنفيذي اعتمادية على مستوى النظام.

توفير ملف ⁨Chrome⁩ التنفيذي

يتطلّب الجسر ملفًا تنفيذيًا قابلًا للتشغيل من ⁨Chrome⁩ أو ⁨Chromium.⁩ افتراضيًا، يبحث chrome-php/chrome عن ملف تنفيذي في المسارات الشائعة. لتحديد مسار صريح، مرّره عبر الإعدادات. راجع /⁨integrations/artisan/configuration/⁩ والصفحة المخصّصة /⁨integrations/artisan/chrome-renderer-setup/.⁩

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

قبل ربط الملف التنفيذي بالتطبيق، تحقّق من أنه يعمل في وضع بلا واجهة (⁨headless⁩):

chromium --headless --dump-dom about:blank

يطبع التشغيل الناجح مستند ⁨Document Object Model⁩ (⁨DOM⁩) فارغًا وينهي العملية بالرمز 0. يعني الإنهاء برمز غير صفري أن الملف التنفيذي أو مكتباته المشتركة مفقودة. عالج ذلك قبل المتابعة، لأن الجسر يُظهر الفشل نفسه على هيئة ChromeRenderException في وقت العرض.

التحقّق من أن الحزمة مربوطة

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

ينشئ هذا أداة العرض ويقرأ سياسة أمان ⁨Hypertext Markup Language⁩ (⁨HTML⁩) الافتراضية دون تشغيل ⁨Chrome.⁩ كما يؤكّد أن التحميل التلقائي وارتباطات عقود nextpdf/core تُحلّ بنجاح. (السلوك مؤكّد عبر tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

التثبيت داخل الحاويات

في ⁨Docker⁩، لا يستطيع صندوق حماية ⁨Chrome⁩ عادةً أن يبدأ بوصفه ⁨process ID⁩ (⁨PID⁩) 1 / ⁨root⁩ دون قدرات نواة إضافية. تتيح الحزمة مفتاح noSandbox لهذه الحالة. لتعطيل صندوق حماية ⁨Chrome⁩ كلفة أمنية حقيقية. توثّق صفحة /⁨integrations/artisan/security-and-operations/⁩ وصفحة /⁨integrations/artisan/chrome-renderer-setup/⁩ هذه الكلفة وتذكران حدودها صراحةً. لا تضبط المفتاح دون قراءة ذلك القسم.

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

chrome-php/chrome موجود لكن دون ملف تنفيذي. ينجح ⁨Composer⁩؛ ثم يطرح أول عرض ChromeRenderException ويلفّ فشل التشغيل. فحص المكتبة منفصل عن فحص الملف التنفيذي.
chrome-php/chrome غائب. إذا أُزيلت المكتبة من المُحمّل التلقائي، يطرح BrowserPool::getBrowser() الاستثناء ChromeNotAvailableException مع أمر المعالجة الدقيق. (مؤكّد عبر tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
قيد الإصدار. nextpdf/core: ^3.0 || ^5.2 — يدعم ⁨Artisan⁩ خطّي الإصدار الرئيسيين لـ ⁨core⁩ كليهما. ثبّت إصدار ⁨core⁩ الذي يستهدفه تطبيقك.

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

يُدخل تثبيت الجسر عملية خارجية (⁨Chrome⁩) إلى حدود الثقة. راجع /⁨integrations/artisan/security-and-operations/⁩ قبل أن تعرّض أي مسار عرض لـ ⁨HTML⁩ المقدَّم من المستخدم.

انظر أيضًا

/integrations/artisan/overview/
/integrations/artisan/configuration/
/integrations/artisan/quickstart/
/integrations/artisan/chrome-renderer-setup/
/integrations/artisan/security-and-operations/