تثبيت حزمة NextPDF لـ Laravel

لمحة سريعة

ثبّت nextpdf/laravel باستخدام ⁨Composer.⁩ يسجّل الاكتشاف التلقائي في ⁨Laravel⁩ مزوّد الخدمة نيابةً عنك. انشر ملف الإعداد عندما تحتاج إلى تعديله. وتكتشف الحزمة امتدادات ⁨NextPDF⁩ الاختيارية تلقائيًا.

التثبيت

composer require nextpdf/laravel

تصرّح الحزمة بالقيود التالية في composer.json الخاص بها:

المتطلب	القيد
⁨PHP⁩	>=8.4 <9.0
laravel/framework	^12.0
nextpdf/core	^3.0 || ^5.2
psr/http-client	^1.0

تُحمَّل الحزمة تلقائيًا عبر خريطة ⁨PHP Standard Recommendation 4⁩‏ (⁨PSR-4⁩) واحدة. تُطابَق البادئة NextPDF\Laravel\ مع src/Laravel/. ويتبع ذلك قاعدة ⁨PSR-4⁩ التي تربط البادئة بالدليل الأساسي (⁨PSR-4⁩ §3).

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

بعد تشغيل composer require، يقرأ الاكتشاف التلقائي لحزم ⁨Laravel⁩ كتلة extra.laravel في composer.json الخاص بهذه الحزمة. ثم يسجّل مزوّد الخدمة والاسم المستعار للواجهة (⁨facade⁩) نيابةً عنك، فلا تحتاج إلى تحرير config/app.php يدويًا. وتظهر الكتلة على هذا النحو:

resource: composer.json (extra.laravel)

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

يوضّح توثيق حزم ⁨Laravel⁩ هذا السلوك. تسجّل مصفوفة extra.laravel.providers مزوّدي الخدمة تلقائيًا، وتسجّل مصفوفة extra.laravel.aliases الأسماء المستعارة للواجهات (⁨facade⁩) تلقائيًا (دليل تطوير حزم ⁨Laravel 12⁩، https://laravel.com/docs/12.x/packages، تاريخ الاطّلاع 2026-05-18).

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

استخدم الوسم nextpdf-config لنشر ملف الإعداد. يُعرَّف اسم هذا الوسم في NextPdfServiceProvider::boot().

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

ينشئ ذلك config/nextpdf.php في تطبيقك. ويدمج المزوّد أيضًا الإعداد الافتراضي للحزمة تحت المفتاح nextpdf أثناء register()، لذلك تعمل الحزمة قبل نشر الملف. يجعل النشر الملف قابلاً للتحرير داخل تطبيقك.

تأكّد من أن ⁨Laravel⁩ اكتشف المزوّد:

php artisan package:discover --ansi

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

ثبّت قيد الإصدار لعمليات نشر قابلة لإعادة الإنتاج. عطّل الاكتشاف صراحةً فقط إذا كنت تسجّل المزوّد بنفسك:

resource: opt-out pattern (Laravel 12 packages guide)

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "nextpdf/laravel"
      ]
    }
  }
}

عند تعطيل الاكتشاف، سجّل المزوّد بنفسك في bootstrap/providers.php:

resource: bootstrap/providers.php (manual registration)

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

الامتدادات الاختيارية

تسرد الحزمة الحزم المرافقة الاختيارية تحت suggest في composer.json الخاص بها، وتكتشف الحزم المرافقة المثبَّتة في وقت التشغيل:

الحزمة	الأثر عند التثبيت	نقطة الاكتشاف
nextpdf/artisan	يطبّق إعداد مُصيِّر ⁨HTML⁩‏ (⁨Hypertext Markup Language⁩) عبر بروتوكول ⁨Chrome DevTools Protocol⁩‏ (⁨CDP⁩) على ربط المستند عند توفّر صنف مصنع ⁨Chrome⁩	يتحقق NextPdfServiceProvider::register() من وجود صنف مصنع متصفّح ⁨Chrome⁩
nextpdf/premium	تجعل مفاتيح الحاوية القائمة تُحلّ إلى تنفيذات عقود توقيع ⁨PDF Advanced Electronic Signatures⁩‏ (⁨PAdES B-B⁩)، وأرشفة ⁨PDF/A⁩، والفاتورة الإلكترونية	تُحلّ كسولًا عند أول عملية حلّ للحاوية

ثبّت امتدادًا بالطريقة نفسها:

composer require nextpdf/artisan

لا حاجة إلى أي ربط إضافي. يكتشف المزوّد الامتداد في دورة التسجيل التالية.

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

• النشر عملية متكافئة العمل (⁨idempotent⁩)، فلا يستبدل ملف config/nextpdf.php إذا كان موجودًا مسبقًا. أضف --force عندما تريد استبداله عمدًا.
• المزوّد مؤجَّل، لذا يكفي نجاح php artisan package:discover لتأكيد الحزمة. أما الروابط نفسها فلا تظهر إلا عند أول عملية حلّ.
• تدعم الحزمة nextpdf/core على كل من الخطّين الرئيسيين ^3.0 و^5.2. طابِق قيد الـ ⁨core⁩ مع الخطّ الذي يثبّته تطبيقك. وتبقى واجهة محوّل ⁨Laravel⁩ نفسها في كليهما.
• تتفق شارة ⁨README⁩ وcomposer.json على ترخيص ⁨Apache-2.0.⁩ أُعيد ترخيص الحزمة من ⁨LGPL-3.0-or-later.⁩ وتبقى الإصدارات الموسومة قبل الانتقال خاضعة للترخيص السابق (انظر CHANGELOG.md).

الأداء

يهيمن حلّ nextpdf/core على كلفة composer require. ولا يضيف تسجيل المزوّد أي كلفة إقلاع قابلة للقياس، لأن جميع الروابط عبارة عن مغلِّفات (⁨closures⁩) مؤجَّلة. انظر /⁨integrations/laravel/boot-and-discovery/⁩ للاطّلاع على كلفة الإنشاء عند أول عملية حلّ.

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

ثبّت من حزمة ⁨Packagist⁩ الرسمية nextpdf/laravel. تتضمّن الحزمة ترويسات ⁨REUSE⁩ وفق ⁨Software Package Data Exchange⁩‏ (⁨SPDX⁩) وملف ترخيص ⁨Apache-2.0⁩ باسم NOTICE. ثبّت القيد في composer.json وأودِع composer.lock حتى يحلّ العمّال المنشورون شجرة الاعتماديات المتحقَّق منها.

المطابقة

الادعاء	المصدر	البند	⁨reference_id⁩
بادئة ⁨PSR-4⁩ تُربط بالدليل الأساسي	⁨PSR-4 Autoloader⁩	§3

جرى التحقق من أسماء مفاتيح الاكتشاف التلقائي في ⁨Laravel⁩ استنادًا إلى التوثيق الرسمي لتطوير حزم ⁨Laravel 12⁩ ‏(https://laravel.com/docs/12.x/packages، تاريخ الاطّلاع 2026-05-18).

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

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

انظر أيضًا

• /⁨integrations/laravel/overview/⁩ — معمارية الحزمة وجدول الروابط
• /⁨integrations/laravel/quickstart/⁩ — أول متحكّم قابل للتشغيل
• /⁨integrations/laravel/configuration/⁩ — شرح كل مفتاح إعداد
• /⁨integrations/laravel/boot-and-discovery/⁩ — تفاصيل الاكتشاف الداخلية وأعمار الروابط