بداية سريعة لاستخدام NextPDF Laravel

لمحة سريعة

في هذا الدرس، ستنشئ ملف ⁨Portable Document Format⁩ ‏(⁨PDF⁩) قابلًا للتنزيل من متحكم. ثم ستنقل العمل نفسه إلى مهمة في قائمة انتظار. يطابق كل مقتطف سلوكًا تتحقق منه مجموعة اختبارات الحزمة.

التثبيت

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

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

تغطي ثلاث نقاط دخول معظم حالات استخدام ⁨Laravel⁩. توفّر الواجهة (⁨facade⁩) أسرع طريقة للبدء. يحوّل PdfResponse المستند إلى استجابة ⁨Hypertext Transfer Protocol⁩ ‏(⁨HTTP⁩). وتنقل المهمة الموضوعة في قائمة الانتظار عمليات التوليد الثقيلة بعيدًا عن خيط الطلب، حتى لا ينتظرها الطلب. يستعرض هذا الدرس كل نقطة دخول على حدة. تضيف الإصدارات الجاهزة للإنتاج معالجة الأخطاء، وهي موجودة في /⁨integrations/laravel/production-usage/.⁩

مثال برمجي — بداية سريعة

1. الواجهة (⁨facade⁩)

تستجلب الواجهة (⁨facade⁩) مستندًا جديدًا من الحاوية عند كل استدعاء. والحاوية هي سجل الخدمات في ⁨Laravel.⁩ يطابق هذا المقتطف السلوك الذي يتحقق منه tests/Unit/Laravel/Facades/PdfTest.php.

<?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'));

2. استجابة التنزيل من متحكم

يُرجع PdfResponse::download() كائن Illuminate\Http\Response مع Content-Type: application/pdf، وتوزيع من نوع attachment، وترويسات أمان ⁨Open Worldwide Application Security Project⁩ ‏(⁨OWASP⁩). يتحقق tests/Unit/Laravel/Http/PdfResponseTest.php من رمز الحالة، ونوع المحتوى، وبادئة التوزيع، والترويسات.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

لعرض معاينة داخلية في المتصفح، استبدل download() بـ inline(). وللمستندات الكبيرة، استخدم streamInline() أو streamDownload(). فهي ترسل ملف ⁨PDF⁩ في أجزاء حتمية بحجم 64 ⁨KB.⁩

3. التوليد عبر قائمة الانتظار

يبني GeneratePdfJob ملف ⁨PDF⁩ ويحفظه على عامل قائمة الانتظار. يستقبل إغلاق الباني (⁨closure⁩) المستندَ المستجلب من الحاوية ويُرجع المستند المهيأ. يؤكد tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php أن المهمة تنشئ الملف في مسار الإخراج المحدد بالضبط.

<?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. تتحقق المهمة من صحة المسار على العامل قبل الكتابة.

مثال برمجي — الإنتاج

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

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

تُرجع الواجهة (⁨facade⁩) نسخة مستند مختلفة عند كل استجلاب. لا تخزّن Pdf::getFacadeRoot() مؤقتًا لاستخدامه عبر مستندات منطقية متعددة.
إذا مرّرت اسم ملف فارغًا إلى أي مصنع PdfResponse، فسيعود افتراضيًا إلى document.pdf. تتحقق مجموعة اختبارات الاستجابة من هذا السلوك الافتراضي.
تتلقى أسماء الملفات غير ⁨ASCII⁩ تلقائيًا معامل filename*= وفق ⁨RFC 5987.⁩ أما أسماء ⁨ASCII⁩ فلا تتلقاه.
يرفض GeneratePdfJob التنقل في المسارات (⁨path traversal⁩)، ومغلِّفات الدفق (⁨stream wrappers⁩)، والبايتات الصفرية (⁨null bytes⁩)، وأي امتداد غير .pdf. ويطلق InvalidArgumentException على العامل.

الأداء

يُولَّد مستند من صفحة واحدة بسهولة ضمن ميزانية زمن الجدار لكل صفحة المدرجة في المقدمة (⁨front matter⁩). يؤدي نقل التوليد إلى GeneratePdfJob إلى إزالة زمن بناء ⁨PDF⁩ من طلب ⁨HTTP⁩ كليًا. يعود الطلب فور إرسال المهمة.

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

تطبّق مصانع PdfResponse مجموعة ثابتة من ترويسات ⁨OWASP⁩. كما تنقّي اسم ملف التنزيل. تتحقق المهمة الموضوعة في قائمة الانتظار من صحة مسار إخراجها. تتوفر تغطية مفصّلة للتهديدات في /⁨integrations/laravel/security-and-operations/.⁩

المطابقة

لا يخضع هذا الدرس لأي معيار إلزامي. يُتحقق من كل مقتطف مقابل مصدر الحزمة والاختبار المقابل تحت tests/.

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

يتوفر الإخراج الموقّع وإخراج ⁨PDF/A⁩ مع ⁨nextpdf/premium⁩ بوصفه قدرة ⁨Enterprise⁩ اختيارية. لا تتطلب حزمة ⁨Core⁩ الموثّقة هنا أي تغيير في الكود لاعتماده. انظر https://nextpdf.dev/get-license/?intent=laravel-signing.

انظر أيضًا

/⁨integrations/laravel/install/⁩ — التثبيت ونشر الإعدادات
/⁨integrations/laravel/production-usage/⁩ — متحكم ومهمة موصولان بحقن التبعيات ومعالجة الأخطاء
/⁨integrations/laravel/configuration/⁩ — مفاتيح الإعدادات المستخدمة هنا
/⁨integrations/laravel/overview/⁩ — المعمارية وأعمار الربط