تكامل NextPDF مع Laravel

لمحة سريعة

يرشدك هذا الدليل إلى إعداد ⁨NextPDF⁩ في تطبيق ⁨Laravel 12.⁩ تمرّ بست مراحل: تثبيت الحزمة، والسماح لـ ⁨Laravel⁩ باكتشافها تلقائيًا، ونشر ملف التهيئة، وحلّ ارتباطات الحاوية، وإرجاع استجابة ⁨HTTP⁩، وتشغيل مهمة مُدرَجة في قائمة الانتظار. ويربط كل مرحلة بمرجعها التفصيلي.

التثبيت

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

الإقلاع / الاكتشاف التلقائي

يكتشف ⁨Laravel⁩ تلقائيًا موفِّر الخدمة واسم ⁨Facade⁩ المستعار من كتلة composer.jsonextra.laravel في الحزمة. لا تحتاج إلى تعديل config/app.php. وتستخدم خريطة التحميل التلقائي مُدخلًا واحدًا من ⁨PSR-4.⁩ تُحَلّ البادئة NextPDF\Laravel\ إلى src/Laravel/ وفقًا لقاعدة تعيين البادئة إلى الدليل الأساسي في ⁨PSR-4⁩ (⁨PSR-4⁩ §3). ونظرًا لأن موفِّر الخدمة مؤجَّل، فإنه لا يُقلِع إلا عند أول حلّ لأحد مُدخلات provides() الخاصة به. للاطلاع على التفاصيل الداخلية الكاملة للاكتشاف، راجع /⁨integrations/laravel/boot-and-discovery/.⁩

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

استدعِ عقد المستند من الحاوية. يُحَلّ المُعرِّف المرتبط إلى مُدخله المُسجَّل (⁨PSR-11⁩ §1.1.2). وبما أن ارتباط المستند مصنع، فإن كل حلّ يعيد مستندًا جديدًا. أما سجلّا الخطوط والصور فهما مفردان (⁨singletons⁩)، لذلك يعيد كل حلّ المثيل المشترك نفسه. للاطلاع على الجدول الكامل لمدد بقاء الارتباطات، راجع /⁨integrations/laravel/overview/⁩ و/⁨integrations/laravel/boot-and-discovery/.⁩

resource: NextPDF\Contracts\PdfDocumentInterface

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

نشر ملف التهيئة

php artisan vendor:publish --tag=nextpdf-config

ينشئ هذا الأمر config/nextpdf.php. يغطي مرجع التهيئة كل مفتاح، ومتغير البيئة الخاص به، وقيمته الافتراضية في /⁨integrations/laravel/configuration/.⁩

اختبار تحقُّق مبدئي لموفِّر الخدمة / الحزمة

تتضمن الحزمة مجموعة اختبارات قائمة على ⁨Testbench⁩ تتحقق من موفِّر الخدمة من البداية إلى النهاية. أضِف اختبار التحقُّق المبدئي المُبسَّط هذا إلى تطبيق مُستهلِك:

resource: tests/Unit/Laravel/NextPdfServiceProviderTest.php (pattern)

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

يعكس هذان التأكيدان فحوصات المطابقة أحادية الاستخدام في الحزمة ضمن EInvoiceServiceProviderIntegrationTest. ويؤكدان أن المستند مرتبط عبر مصنع وأن سجلّ الخطوط مفرد ومُقفَل.

نقاط الدخول إلى الواجهة البرمجية العامة (⁨API⁩)

نقطة الدخول	الغرض	المرجع
NextPDF\Laravel\Facades\Pdf	وكيل ثابت لمستند جديد	/⁨integrations/laravel/quickstart/⁩
app(NextPDF\Contracts\PdfDocumentInterface::class)	مستند مُحَلّ من الحاوية	/⁨integrations/laravel/production-usage/⁩
NextPDF\Laravel\Http\PdfResponse	استجابات ⁨HTTP⁩ للعرض المضمَّن والتنزيل والبث	/⁨integrations/laravel/security-and-operations/⁩
NextPDF\Laravel\Jobs\GeneratePdfJob	إنشاء عبر قائمة الانتظار	/⁨integrations/laravel/production-usage/⁩

نموذج التعليمات البرمجية — الإنتاج

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

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

• استدعِ PdfDocumentInterface، وليس الصنف الملموس Document، بحيث يبقى الارتباط قابلًا للاختبار والاستبدال.
• يُحَلّ SignerInterface وTsaClient إلى null إلى أن يُهيَّآ. تحقّق دائمًا من القيمة ⁨null.⁩
• تتطلب عقود الفاتورة الإلكترونية nextpdf/premium. تكون مرتبطة، لكنها تُصدِر خطأً عند أول حلّ من دونه.

الأداء

لا يضيف التكامل الكامل أي تكلفة إقلاع لأن موفِّر الخدمة مؤجَّل. وتغطي /⁨integrations/laravel/boot-and-discovery/⁩ تكاليف الإنشاء عند أول حلّ وتكاليف تسخين الخطوط.

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

يطبّق PdfResponse مجموعة ثابتة من ترويسات مشروع أمان تطبيقات الويب المفتوح عالميًا (⁨OWASP⁩). ويتحقق GeneratePdfJob من صحة مسار الإخراج الخاص به على العامل. راجع /⁨integrations/laravel/security-and-operations/⁩ للاطلاع على نموذج التهديد.

المطابقة

الادعاء	المصدر	البند	⁨reference_id⁩
يُحَلّ المُعرِّف المرتبط إلى مُدخله المُسجَّل	⁨PSR-11 Container⁩	§1.1.2
تعيين بادئة ⁨PSR-4⁩ إلى الدليل الأساسي	⁨PSR-4 Autoloader⁩	§3

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

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

انظر أيضًا

• /⁨integrations/laravel/overview/⁩ — البنية المعمارية وجدول الارتباطات
• /⁨integrations/laravel/install/⁩ — التثبيت والإضافات الاختيارية
• /⁨integrations/laravel/quickstart/⁩ — أول مثال قابل للتشغيل
• /⁨integrations/laravel/production-usage/⁩ — حقن التبعيات، ومعالجة الأخطاء، وقائمة الانتظار
• /⁨integrations/laravel/boot-and-discovery/⁩ — الاكتشاف ومدد البقاء