بداية سريعة باستخدام Artisan

لمحة سريعة

أرفِق ChromeRendererConfig بمستند ⁨NextPDF⁩، واستدعِ writeHtmlChrome()، ثم احفظ ملف ⁨Portable Document Format⁩ (⁨PDF⁩). يتولى ⁨Chrome⁩ عرض ⁨Hypertext Markup Language⁩ (⁨HTML⁩)، ويستورد الجسر الناتج في صورة ⁨Form XObject⁩، مع بقاء النص قابلًا للتحديد.

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

writeHtmlChrome() دالة في Document الأساسي في ⁨NextPDF.⁩ توفّرها السمة HasTextOutput. تتحقق الدالة من صحة المُدخَل وتحدد مُصيِّر ⁨Artisan.⁩ ثم ترسل ⁨HTML⁩ إلى ⁨Chrome⁩، وتحلل ملف ⁨PDF⁩ المُعاد، وتضمّن الصفحة 0 في صورة ⁨Form XObject⁩ عند موضع المؤشر الحالي. التوقيع العمومي هو writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — تم التحقق منه بالرجوع إلى nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

عينة شيفرة — بداية سريعة

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

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

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

هذا هو التدفق المعياري المأخوذ من README.md الخاص بالحزمة. يتولى ⁨Chrome⁩ تخطيط flex الخاص بـ ⁨Cascading Style Sheets⁩ (⁨CSS⁩). وتبقى الأرقام نصًا قابلًا للتحديد في الناتج لأن الصفحة مُضمَّنة في صورة ⁨Form XObject⁩، لا كصورة نقطية.

حجم صفحة مخصص

مرّر عرضًا وارتفاعًا صريحين بوحدة نقاط ⁨PDF⁩ لملاءمة صفحة ثابتة (يظهر ⁨A4⁩ هنا):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

عند تزويد كلتا القيمتين، يطبع ⁨Chrome⁩ بحجم الورق المحدد بالضبط. عند إغفال الارتفاع (أو تمرير null)، يضبط الجسر ارتفاعه وفق ارتفاع المحتوى المقاس، ويضيف هامش أمان صغيرًا لإعادة التدفق. راجع /⁨integrations/artisan/production-usage/⁩ لمعرفة سبب هذا الهامش ومتى ينبغي تجاوزه.

ما الذي تحصل عليه

الخاصية	السلوك
النص	قابل للتحديد والبحث (نص متجهي، وليس منقّطًا)
⁨Cascading Style Sheets⁩ (⁨CSS⁩)	تخطيط ⁨Chrome⁩: ⁨flexbox⁩ و⁨grid⁩ والمحدِّدات المركّبة والخطوط الإلكترونية عبر قيم ⁨data Uniform Resource Identifier⁩ (⁨URI⁩)
الشبكة	لا توجد عمليات جلب لموارد فرعية؛ ولا تُحمَّل عناوين ⁨Uniform Resource Locators⁩ (⁨URLs⁩) البعيدة (راجع /⁨integrations/artisan/security-and-operations/⁩)
الصفحات	تُستورَد الصفحة 0 من ناتج ⁨Chrome⁩

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

• ⁨HTML⁩ الفارغ لا يؤدي أي عملية. يعيد writeHtmlChrome('') المستند دون تغيير (تم التحقق منه في HasTextOutput::writeHtmlChrome).
• لا توجد صفحة بعد. إذا لم يكن للمستند صفحة، يضيف writeHtmlChrome() واحدة قبل العرض.
• الأصول البعيدة لا تُحمَّل. يُعرَض <img src="https://..."> فارغًا. ضمِّن الأصول مباشرة في صورة عناوين data: ⁨URI.⁩ هذا سلوك عزل الشبكة، وليس خللًا. راجع /⁨integrations/artisan/security-and-operations/.⁩
• الجسر مفقود. إذا لم يكن nextpdf/artisan مثبتًا، يطلق المحرك الأساسي استثناء تخطيط بدلًا من خطأ فادح.

الأداء

يتضمن الاستدعاء الأول زمن بدء تشغيل ⁨Chrome⁩ وزمن التخطيط. تعيد الاستدعاءات اللاحقة استخدام عملية ⁨Chrome⁩ النشطة عبر BrowserPool. للمهام الدُّفعية أو العمال طويلي التشغيل، راجع إرشادات دورة الحياة والموارد في صفحة /⁨integrations/artisan/production-usage/.⁩

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

تستخدم البداية السريعة شيفرة ⁨HTML⁩ موثوقة ومُضمَّنة مباشرة في الشيفرة. قبل تمرير أي شيفرة ⁨HTML⁩ متأثرة بالمستخدم إلى writeHtmlChrome()، اقرأ /⁨integrations/artisan/security-and-operations/.⁩ يعزل الجسر الوصول إلى الشبكة، لكن عرض ⁨HTML⁩ لا يزال يمثّل سطح تهديد.

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

ينتج هذا ملف ⁨PDF⁩ من ⁨HTML⁩ باستخدام الجسر مفتوح المصدر. لتضمين ملف ⁨Extensible Markup Language⁩ (⁨XML⁩) متوافق لفاتورة إلكترونية داخل المستند نفسه، توفّر فئة ⁨Premium Pro⁩ أداة تضمين. لا يتأثر المسار مفتوح المصدر عند غياب ⁨Premium.⁩

انظر أيضًا

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/production-usage/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/security-and-operations/