مرجع API في Laravel

لمحة سريعة

تربط حزمة nextpdf/laravel نواة ⁨NextPDF⁩ المستقلّة عن إطار العمل بتطبيق ⁨Laravel.⁩ ستتعامل مباشرةً مع أربع نقاط دخول: الواجهة الساكنة Pdf لتدفّقات إنشاء المستندات القصيرة، وارتباط الحاوية PdfDocumentInterface لإنشاء مستند قابل للحقن، والمساعد PdfResponse لاستجابات ⁨HTTP⁩ من المستندات المكتملة، ومهمّة قائمة الانتظار GeneratePdfJob للتوليد خارج الطلب. يسجّل NextPdfServiceProvider كل ارتباط ويُكتشف تلقائيًّا، لذا لن تحتاج إلى إعداد يدوي. يتحكّم الإعداد في config/nextpdf.php في الإعدادات الافتراضية والخطوط وقوائم الانتظار وميزات التوقيع الاختيارية وسلطة الطابع الزمني (⁨TSA⁩).

ابدأ من هنا: لإرسال ملف بصيغة المستندات المحمولة (⁨PDF⁩) مباشرةً من وحدة تحكّم، أنشئ مستندًا ثم أعد PdfResponse::download($document, 'file.pdf'). يوضّح المثال الأول أدناه هذا التدفّق.

المهام الشائعة

تغطّي المقتطفات أدناه التدفّقات الثلاثة التي ستستخدمها غالبًا في البداية. كل مقتطف مُتحقَّق منه مقابل مصدر الحزمة؛ وتليه جداول كاملة لكل رمز.

أعد ملف ⁨PDF⁩ قابلًا للتنزيل من وحدة تحكّم. هذه هي المهمّة الأكثر شيوعًا:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

ما الذي يفعله هذا: يحقن مستندًا جديدًا، ويكتب سطرًا واحدًا، ويعيد استجابة attachment مع Content-Type: application/pdf وترويسات الأمان الخاصة بمشروع أمان تطبيقات الويب المفتوح عالميًّا (⁨OWASP⁩). استخدم inline() بدلًا من download() للمعاينة في المتصفّح.

ألّف واحفظ باستخدام الواجهة الساكنة Pdf. هذا أقصر مسار للنصوص البرمجية والتدفّقات القصيرة:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

ما الذي يفعله هذا: تحلّ الواجهة الساكنة مستندًا جديدًا من الحاوية، وتكتب خليّة واحدة، وتحفظ ملف ⁨PDF⁩ المكتمل على القرص.

ولّد ملف ⁨PDF⁩ خارج خيط الطلب باستخدام GeneratePdfJob:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

ما الذي يفعله هذا: يضع التوليد في قائمة انتظار على عامل. تتلقّى مغلّفة المُنشئ مستندًا محلولًا من الحاوية وتعيده. تتحقّق المهمّة من مسار الإخراج .pdf قبل الحفظ. يأتي اسم قائمة الانتظار والمهلة والاتصال من config('nextpdf.queue.*').

الواجهة الساكنة

تفوّض الواجهة الساكنة Pdf الاستدعاءات الساكنة إلى نواة Document جديدة. استخدمها في تدفّقات وحدة التحكّم القصيرة عندما يكون الأسلوب الساكن واضحًا. يسرد كل صفّ طريقة مستند واحدة مفوَّضة.

الرمز	المعاملات	السلوك الافتراضي	القيمة المعادة	يطرح أو يفشل بـ	ملاحظات
`NextPDF\Laravel\Facades\Pdf`	لا شيء؛ تحلّ أداة الوصول إلى الواجهة الساكنة `NextPDF\Contracts\PdfDocumentInterface`	يحلّ ⁨Laravel⁩ ارتباط الحاوية الحالي لواجهة المستند.	API الانسيابية للمستند الأساسي.	فشل ارتباط حاوية ⁨Laravel⁩ إذا لم يكن المزوّد مسجّلًا.	استخدمها لتدفّقات وحدة التحكّم القصيرة. فضّل الحقن عبر الباني في الخدمات والمهام.
`Pdf::setTitle(string $title)`	`title`: عنوان المستند.	يستبدل أي عنوان موجود.	`static`	أخطاء التحقّق الأساسية أو أخطاء وقت الكتابة.	يوكّل إلى نواة `Document`.
`Pdf::setAuthor(string $author)`	`author`: بيانات تعريف مؤلّف المستند.	يستبدل أي مؤلّف سابق.	`static`	أخطاء التحقّق من بيانات التعريف الأساسية.	فضّل الإعدادات الافتراضية المُهيَّأة لبيانات التعريف على مستوى التطبيق.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: حجم صفحة اختياري؛ `orientation`: `Portrait` افتراضيًّا.	يستخدم حجم الصفحة المُهيَّأ أو الافتراضي عند حذف `size`.	`static`	أخطاء التحقّق من الصفحة الأساسية.	استخدم `PageSize` صريحًا عندما يكون حجم الإخراج مهمًّا.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	عائلة الخط ونمطه وحجمه بالنقاط.	يستخدم نمطًا فارغًا وحجم 12 نقطة.	`static`	أخطاء سجلّ الخطوط أو الترميز.	حمّل خطوط الإنتاج مسبقًا عبر `nextpdf.preload_fonts` عندما يهمّ زمن الاستجابة.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	صندوق الخليّة والنص وعلامة الحدّ وعلامة فاصل السطر والمحاذاة.	يستخدم نصًّا فارغًا، ومن دون حدّ، ومن دون فاصل سطر، ومحاذاة إلى اليسار.	`static`	أخطاء التخطيط أو ترميز النص.	استخدمها لإخراج بسيط بتخطيط ثابت.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	عرض الخليّة وارتفاع السطر والنص وعلامة الحدّ والمحاذاة.	من دون حدّ، وبمحاذاة إلى اليسار.	`static`	أخطاء التخطيط أو ترميز النص.	استخدمها عندما ينبغي أن يلتفّ النص ضمن عرض ثابت.
`Pdf::writeHtml(string $html)`	`html`: مقطع ⁨HTML.⁩	يعرضه على الصفحة الحالية، وينشئ صفحة عند الحاجة.	`static`	أخطاء عرض ⁨HTML⁩ الأساسية.	طبّق سياسات حجم الإدخال والموارد قبل قبول ⁨HTML⁩ غير موثوق.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	مسار الملف ومستطيل التموضع الاختياري.	يترك للمستند الأساسي اختيار الموضع الحالي والحجم الجوهري عند حذف الإحداثيات.	`static`	أخطاء فكّ ترميز الصورة أو المسار أو التخطيط.	تحقّق من سياسة مصدر الصورة قبل قبول المسارات التي يوفّرها المستخدم.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: اسم اختياري؛ `dest`: وجهة الإخراج.	يُخرج مضمَّنًا عند حذف الوجهة.	`string`	أخطاء التسلسل الأساسية.	فضّل `PdfResponse` لاستجابات ⁨HTTP⁩ في ⁨Laravel.⁩
`Pdf::save(string $path)`	`path`: هدف نظام الملفات.	يكتب ملف ⁨PDF⁩ المكتمل على القرص.	`void`	أخطاء نظام الملفات أو أخطاء الكتابة الأساسية.	تحقّق من أدلّة الإخراج في شيفرة التطبيق.
`Pdf::getPdfData()`	لا شيء.	يجسّد بايتات ⁨PDF⁩ في الذاكرة.	`string`	أخطاء التسلسل الأساسية.	استخدمها عندما يجب أن يمتلك كائن إطار عمل آخر جسم الاستجابة.

مزوّد الخدمة والارتباطات

استخدم هذا الجدول عندما تحتاج إلى حلّ مدخل حاوية أو تجاوزه مباشرةً، مثل حقن DocumentFactoryInterface في خدمة أو التحقّق مما يؤجّله provides().

الرمز	المعاملات	السلوك الافتراضي	القيمة المعادة	يطرح أو يفشل بـ	ملاحظات
`NextPdfServiceProvider::register()`	لا شيء.	يدمج `config/nextpdf.php`؛ ويسجّل السجلّات، ومصنع المستندات، وارتباط المستند، وعميل ⁨HTTP⁩، وعميل ⁨TSA⁩، والموقّع، وعقود الفاتورة الإلكترونية الاختيارية.	`void`	أخطاء حلّ الحاوية أو الأصناف الاختيارية عند استخدام ميزة.	`FontRegistryInterface` و`ImageRegistry` مشتركان؛ أما المستندات فهي جديدة دائمًا.
`NextPdfServiceProvider::boot()`	لا شيء.	يتحقّق من امتدادات ⁨PHP⁩ المطلوبة وينشر `nextpdf-config` في وضع الطرفية.	`void`	`RuntimeException` إذا كان امتداد مطلوب غير متوفّر.	الامتدادات المطلوبة هي `mbstring` و`zlib`.
`NextPdfServiceProvider::provides()`	لا شيء.	يبلّغ عن معرّفات الخدمات المؤجَّلة.	`array<string>`	لا شيء متوقّع.	يشمل `PdfDocumentInterface`، و`DocumentFactoryInterface`، و`FontRegistryInterface`، و`SignerInterface`، و`TsaClient`، و`ClientInterface`، و`nextpdf`.
`PdfDocumentInterface` / `nextpdf`	محلول من حاوية ⁨Laravel.⁩	ينشئ `Document` قابلًا للتخلّص عبر `DocumentFactoryInterface`، ثم يطبّق الإعدادات الافتراضية المُهيَّأة وإعدادات ⁨PDF/A⁩ أو ⁨Artisan⁩ الاختيارية.	`NextPDF\Core\Document`	أخطاء الامتدادات الاختيارية عند تهيئتها وعدم توفّرها.	احلل مستندًا جديدًا لكل طلب أو مهمّة.
`DocumentFactoryInterface`	محلول من حاوية ⁨Laravel.⁩	مصنع وحيد يشارك سجلّي الخطوط والصور طوال عمر العمليّة.	`DocumentFactoryInterface`	أخطاء إعداد السجلّ.	استخدمه للحقن الصريح للتبعيّات.
`SignerInterface`	محلول من حاوية ⁨Laravel.⁩	يعيد `null` ما لم يُضبط `nextpdf.signature.enabled` وتُهيَّأ مسارات الشهادات.	`SignerInterface	null`	أخطاء تحميل الشهادة أو التحقّق على مستوى التوقيع.

الإعداد

استخدم هذا الجدول للعثور على مفاتيح nextpdf.* المتعلّقة بوقت التشغيل التي تقرؤها الارتباطات. المرجع الكامل لكل مفتاح، بما في ذلك متغيّرات البيئة والإعدادات الافتراضية، موجود في /⁨integrations/laravel/configuration/.⁩

المفتاح	النوع	السلوك الافتراضي	ملاحظات
`nextpdf.fonts_path`	`string`	يستخدم خطوط مورد ⁨Laravel⁩ عند حذفه.	دليل للخطوط المخصّصة والإحماء.
`nextpdf.cache_path`	`string`	مسار ذاكرة التخزين المؤقّت للتطبيق.	أبقه قابلًا للكتابة بواسطة عامل ⁨PHP.⁩
`nextpdf.preload_fonts`	`list<string>`	قائمة فارغة.	يُحمّى أثناء إنشاء السجلّ، ثم يُقفل السجلّ.
`nextpdf.image_cache_mb`	`int`	حجم محدود لذاكرة التخزين المؤقّت للصور.	يحدّ ذاكرة التخزين المؤقّت للصور طوال عمر العمليّة.
`nextpdf.defaults.*`	`array`	المُنشئ `NextPDF`، واللغة `en`، ومؤلّف اختياري وإعدادات تخطيط افتراضية.	يُطبَّق على كل مستند جديد.
`nextpdf.artisan.*`	`array`	مُصيِّر ⁨Chrome⁩ مُعطَّل ما لم يُثبَّت ويُهيَّأ.	يُطابق `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	التوقيع مُعطَّل افتراضيًّا.	الشهادة والمفتاح الخاص وكلمة المرور والشهادات الإضافية ومستوى التوقيع.
`nextpdf.tsa.*`	`array`	⁨TSA⁩ مُعطَّلة عندما يكون محدّد موقع المورد الموحّد (⁨URL⁩) فارغًا.	يدعم بيانات الاعتماد، وملفّات أمان طبقة النقل المتبادل (⁨mTLS⁩)، والمهلة، وتثبيتات المفتاح العام، وسياسة ⁨HTTP.⁩
`nextpdf.ocsp_cache.*`	`array`	ذاكرة التخزين المؤقّت لبروتوكول حالة الشهادة عبر الإنترنت (⁨OCSP⁩) مُفعَّلة مع مدّة بقاء (⁨TTL⁩) مُهيَّأة.	تستخدمها تدفّقات التحقّق من التوقيع عند توفّرها.

استجابات ⁨HTTP⁩

استخدم هذا الجدول عندما تعيد مستندًا مكتملًا عبر ⁨HTTP⁩ وتحتاج إلى الاختيار بين العرض المضمَّن أو تنزيل المرفق أو الإخراج المتدفّق.

الرمز	المعاملات	السلوك الافتراضي	القيمة المعادة	يطرح أو يفشل بـ	ملاحظات
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: المستند المُنشأ؛ `filename`: اسم ملف ⁨Content-Disposition.⁩	يطبّع أسماء الملفّات الفارغة إلى `document.pdf`.	`Illuminate\Http\Response`	أخطاء التسلسل الأساسية أو إنشاء الاستجابة.	يضبط نوع محتوى ⁨PDF⁩ والترويسات الدفاعية.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	مثل `inline`؛ والتصرّف مرفق.	يعيد استجابة تنزيل عبر المتصفّح.	`Illuminate\Http\Response`	مثل `inline`.	استخدمها لتنزيلات الملفّات الصريحة.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	مثل `inline`.	يجسّد بايتات ⁨PDF⁩، ثم يبثّ كتلًا بحجم 64 ⁨KB.⁩	`Symfony\Component\HttpFoundation\StreamedResponse`	مثل `inline`.	هذا إخراج ⁨HTTP⁩ متدفّق، وليس تصييرًا بلا نسخ.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	مثل `streamInline`؛ والتصرّف مرفق.	استجابة تدفّق التنزيل.	`StreamedResponse`	مثل `streamInline`.	افرض حدود حجم الإدخال والإخراج قبل التصيير.

مهمّة قائمة الانتظار

استخدم هذا الجدول عندما تنقل التوليد خارج خيط الطلب. يغطّي الإنشاء والإرسال وردود نداء النجاح أو الفشل لـGeneratePdfJob.

الرمز	المعاملات	السلوك الافتراضي	القيمة المعادة	يطرح أو يفشل بـ	ملاحظات
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: الهدف `.pdf`؛ `builder`: يتلقّى `PdfDocumentInterface`؛ وردود النداء اختيارية.	يُقرأ اسم قائمة الانتظار والمهلة والاتصال من `config('nextpdf.queue.*')`.	نسخة المهمّة.	أخطاء تسلسل إذا تعذّر تسلسل المُنشئ أو ردود النداء.	يجب أن يعيد المُنشئ المستند المُهيَّأ.
`GeneratePdfJob::handle()`	لا شيء.	يحلّ `PdfDocumentInterface`، ويطبّق المُنشئ، ويتحقّق من مسار الإخراج، ثم يحفظ.	`void`	`InvalidArgumentException` لمسارات الإخراج غير الآمنة؛ وأخطاء الكتابة الأساسية.	يرفض مغلّفات التدفّق، والبايتات الصفرية، ومقاطع `..`، والمسارات غير المنتهية بـ`.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: سبب الفشل.	يستدعي ردّ نداء الفشل المُهيَّأ عند وجوده.	`void`	إخفاقات ردّ النداء.	أبقِ ردود النداء عديمة التأثير الجانبي عند التكرار.
`GeneratePdfJob::then(callable $callback)`	`callback`: يتلقّى مسار الإخراج.	يستبدل ردّ نداء النجاح.	`self`	أخطاء المغلّفة القابلة للتسلسل.	مساعد انسيابي لإعداد الإرسال.
`GeneratePdfJob::catch(callable $callback)`	`callback`: يتلقّى `Throwable` المطروح.	يستبدل ردّ نداء الفشل.	`self`	أخطاء المغلّفة القابلة للتسلسل.	استخدمها للتنبيه أو التنظيف التعويضي.

ملاحظات التطوير

يستدعي PdfResponse دائمًا getPdfData() قبل إنشاء الاستجابة. إنه ليس بانيًا كسولًا للمستندات.
يمكن العبث بحمولات قائمة الانتظار في وسائط النقل المشتركة؛ احصر مسارات الإخراج في دليل يملكه التطبيق.
استخدم مستندًا جديدًا لكل طلب أو مهمّة. لا تعد استخدام مستند عبر طلبات متعدّدة.