بداية سريعة مع NextPDF Pro

لمحة سريعة

بحوزتك مظروف ترخيص ⁨NextPDF⁩ Pro. يحوّل هذا الدرس التعليمي ذلك المظروف إلى أول نتيجة مُتحقَّق منها في أربع خطوات قصيرة. تُثبِّت ⁨nextpdf/pro⁩ من المستودع الخاص، وتفعِّل ترخيصك، وتؤكِّد الاستحقاق الذي حلَّه وقت التشغيل، ثم تُصيِّر مستند ⁨PDF⁩ من قالب وتوقِّعه. تُظهر كل خطوة المُخرَج الذي ينبغي أن تراه.

تأتي هذه القدرة ضمن ⁨NextPDF⁩ Pro (⁨nextpdf/pro⁩) وتُفعَّل بمظروف ترخيص من فئة Pro. لا يُحمِّل النشر الذي يفتقر إلى ذلك الاستحقاق أصناف هذه القدرة. قارن الإصدارات واحصل على ترخيص.

المتطلبات المسبقة

• ⁨PHP 8.4⁩ وComposer 2. تتطلب الحزم المميزة ⁨PHP⁩ ⁨>=8.4 <9.0⁩.
• بيانات اعتماد المستودع الخاص. تُصدر بوابتك عنوان URL للمستودع، واسم مستخدم، ورمزًا مميزًا. يُغطَّى الإعداد في التثبيت والمصادقة.
• مظروف ترخيصك. سجِّل الدخول إلى حسابك على app.getnextpdf.com، ووقِّع اتفاقية الترخيص، ونزِّل المظروف المُوقَّع الخاص بنشرك. تعامل معه كما تتعامل مع مفتاح ⁨API⁩.
• مُحمِّل ionCube (البنيات المُرمَّزة فقط). تحتاج نسخة Pro التجريبية وبنية Pro المدفوعة المُرمَّزة بـ ionCube إلى المُحمِّل الخاص بـ ⁨PHP 8.4⁩ — انظر إعداد ionCube.

1. التثبيت والتفعيل

وجِّه Composer إلى مستودعك الخاص، وصادِق، واطلب الحزمة:

composer config repositories.nextpdf composer https://repo.example.com/nextpdf
composer config --auth http-basic.repo.example.com your-username your-token
composer require nextpdf/pro:^3

استبدل عنوان URL للمستودع وبيانات الاعتماد من بوابتك. تُوصَف طرق المصادقة الثلاث جميعها (ملف المشروع ⁨auth.json⁩، و⁨COMPOSER_AUTH⁩، والمصادقة العامة) في التثبيت والمصادقة.

بعد ذلك، ضع مظروف الترخيص المُوقَّع حيث يُحمِّله نشرك، متَّبعًا عرف التهيئة الخاص بك، وشغِّل خطوة التفعيل في تكاملك — تكشف عنها معظم أطر العمل بوصفها أمر وحدة تحكم. في الخلفية، يكون التفعيل عبر الإنترنت استدعاءً واحدًا على واجهة الترخيص:

public function activate(string $licenseJws, string $deploymentId, ?string $machineFingerprintHash = null, ?string $expectedLicenseId = null, ?string $clientNonce = null): StatusResponse

يطرح استثناءً أو يفشل بـ: ⁨NextPDF\Enterprise\Licensing\LicenseClientException⁩ عند فشل النقل، أو حالة غير 200، أو nonce مُقدَّم غير صالح، و ⁨NextPDF\Accelerator\Exception\SpectrumAuthenticationException⁩ عند أي فشل في التحقق من الحالة المُوقَّعة. على قناة ionCube يتحقق الترخيص أيضًا دوريًا عبر الإنترنت؛ أما قناة المصدر المُوقَّع فتتحقق محليًا — انظر قناتا التسليم.

2. تحقَّق من استحقاقك

اسأل مُقيِّم الاستحقاق — السلطة الوحيدة لقرارات الترخيص — إلامَ حلَّ مظروفك. ⁨$license⁩ هو ⁨NextPDF\Enterprise\Licensing\LicenseKey⁩ المُتحقَّق منه الذي يكشفه تمهيد الترخيص في تكاملك؛ وتُظهر ⁨null⁩ نتيجة انعدام الترخيص المُغلقة عند الفشل.

use NextPDF\Enterprise\Licensing\EntitlementEvaluator;

$result = (new EntitlementEvaluator())->evaluate($license);

printf("status:   %s\n", $result->status->value);
printf("edition:  %s\n", $result->edition?->value ?? '(none)');
printf("channel:  %s\n", $result->channel->value);
printf("branding: %s\n", $result->brandingMode->value);
printf("runtime:  %s\n", $result->runtimeAllowed ? 'allowed' : 'disabled');

الطريقة التي وراءه (لا تطرح استثناءً):

public function evaluate(?LicenseKey $license, ?DateTimeImmutable $now = null): EntitlementResult

مع ترخيص Pro مدفوع ونشِط، توقَّع:

status:   active
edition:  pro
channel:  paid
branding: none
runtime:  allowed

على منحة تجريبية أو تقييمية، توقَّع ⁨channel: evaluation⁩ و ⁨branding: evaluation⁩ بدلًا من ذلك. تظل كل قدرة من قدرات Pro تعمل، ويحمل المُخرَج المُصيَّر علامة مائية تقييمية مرئية عن قصد. ويزيلها الترخيص المدفوع دون أي تغيير في الكود — انظر علامة التجربة والتقييم.

3. أول نتيجة

الآن الجزء الممتع: حلِّل قالب ⁨JSON⁩، واربط بياناتك بتنسيق واعٍ بالنوع، وصيِّر القيم المربوطة، ووقِّع المستند. احفظ هذا باسم ⁨quickstart.php⁩ بجوار دليل ⁨vendor/⁩ الخاص بك وشغِّل ⁨php quickstart.php⁩. تحتاج إلى شهادة توقيع بصيغة ملف PKCS#12 (⁨signing-cert.p12⁩)؛ وتكفي شهادة موقَّعة ذاتيًا لهذا الدرس التعليمي. يحتاج التوقيع في الإنتاج إلى مفتاح خاص محمي كما ينبغي، وسلسلة شهادات حقيقية، وسياسة ثقة يقبلها مستلموك — التوقيعات الموقَّعة ذاتيًا غير مناسبة لسير عمل المستلمين الموثوقين.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

// Parse a JSON template: one A4 page, three positioned placeholders.
$template = (new TemplateParser())->parse(<<<'JSON'
{
    "name": "welcome-letter",
    "pageSize": "A4",
    "orientation": "P",
    "placeholders": [
        {"name": "customer", "type": "text",     "x": 25, "y": 60, "width": 160, "height": 10},
        {"name": "issued",   "type": "date",     "x": 25, "y": 72, "width": 80,  "height": 10},
        {"name": "total",    "type": "currency", "x": 25, "y": 84, "width": 80,  "height": 10, "format": "EUR "}
    ]
}
JSON);

// Bind data. Keys match placeholder names case-insensitively.
$binding = (new TemplateDataBinder())->bind($template, [
    'customer' => 'Aurora Paper Co.',
    'issued'   => '2026-07-03',
    'total'    => 1249.5,
]);

printf(
    "Bound %d of %d placeholders (%d missing, %d warnings)\n",
    $binding->count(),
    count($template->placeholders),
    count($binding->missingFields),
    count($binding->warnings),
);

// Render the bound values with the Core document API.
$doc = Document::createStandalone();
$doc->setTitle('Welcome letter');
$doc->addPage();
$doc->setFont('helvetica', '', 12);

foreach ($binding->bindings as $bound) {
    $doc->text($bound->placeholder->x, $bound->placeholder->y, $bound->formattedValue);
}

// Apply a PAdES B-B baseline signature, then save once.
$doc->setSignature(
    CertificateInfo::fromPkcs12(__DIR__ . '/signing-cert.p12', (string) getenv('NEXTPDF_P12_PASSWORD')),
    SignatureLevel::PAdES_B_B,
);

$doc->save(__DIR__ . '/welcome-letter-signed.pdf');

echo "Created: welcome-letter-signed.pdf\n";

المُخرَج المتوقَّع:

Bound 3 of 3 placeholders (0 missing, 0 warnings)
Created: welcome-letter-signed.pdf

افتح ⁨welcome-letter-signed.pdf⁩ في قارئ ⁨PDF⁩: تظهر القيم المربوطة الثلاث في مواضعها من القالب (⁨issued⁩ بتنسيق ⁨Y-m-d⁩، و⁨total⁩ بصيغة ⁨EUR 1,249.50⁩)، وتُظهر لوحة توقيع القارئ توقيعًا واحدًا. تتبع البنية المُنبعثة ملمح خط الأساس ⁨PAdES⁩ B-B؛ وتوثِّق ⁨NextPDF⁩ ذلك بوصفه قدرة، لا شهادة اعتماد — النطاق وموقف المطابقة مذكوران في صفحة مستويات ⁨PAdES⁩. إذا كان قالب ⁨JSON⁩ مُشوَّهًا، يطرح ⁨TemplateParser::parse()⁩ استثناء ⁨InvalidArgumentException⁩ برسالة مسبوقة بـ ⁨Template validation failed:⁩.

توقيعات الطرق الأساسية التي استخدمتَها للتو، حرفيًا:

public function parse(string $json): TemplateDefinition
public function bind(TemplateDefinition $template, array $data): BindingResult
public static function fromPkcs12(string $p12Path, #[SensitiveParameter] string $password = ''): self
public function setSignature(CertificateInfo $certInfo, SignatureLevel $level = SignatureLevel::PAdES_B_B, ?TsaClient $tsaClient = null, ?ClientInterface $httpClient = null): static
public function save(string $path): void

يطرح استثناءً أو يفشل بـ: ⁨parse()⁩ — ⁨InvalidArgumentException⁩ عندما يكون ⁨JSON⁩ غير صالح أو لا يطابق البنية المتوقَّعة؛ ⁨fromPkcs12()⁩ — ⁨NextPDF\Exception\SignatureException⁩ عندما يتعذَّر قراءة الملف أو تحليله؛ ⁨setSignature()⁩ — ⁨NextPDF\Exception\InvalidConfigException⁩ عندما تكون الخطية مُفعَّلة بالفعل (⁨PAdES⁩ وعرض الويب السريع متعارضان)؛ ⁨save()⁩ — ⁨NextPDF\Exception\InvalidConfigException⁩، أو ⁨NextPDF\Exception\PageLayoutException⁩، أو ⁨NextPDF\Exception\CompressionException⁩ عندما يتعذَّر كتابة الملف. لا تطرح ⁨bind()⁩ استثناءً؛ بل تبلِّغ عن ⁨missingFields⁩ و⁨warnings⁩ بدلًا من ذلك.

4. عند فشل شيء ما

يتعذَّر على ⁨Composer⁩ العثور على ⁨nextpdf/pro⁩ أو جلبها

خطأ ⁨401⁩/⁨403⁩ أثناء ⁨composer require⁩، أو “could not be found”، يعني أن المستودع الخاص أو بيانات اعتماده غير مهيَّأة لهذا المشروع. يجب أن يطابق مفتاح المضيف في ⁨auth.json⁩ مضيف عنوان URL للمستودع تمامًا. اعمل خطوة بخطوة عبر التثبيت والمصادقة.

يبلِّغ وقت التشغيل عن انعدام الترخيص

تطبع الخطوة 2 ⁨status: no_license⁩، و⁨runtime: disabled⁩، وتحذير المُقيِّم — رسالة وقت التشغيل المميز الأولية (المشتركة بين الإصدارين) هي: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. تفشل الميزات المميزة مُغلقةً دون مظروف مُتحقَّق منه. لا يُعامَل ملف مظروف موجود لكنه معطوب على أنه غائب أبدًا — بل يرفع ⁨NextPDF\Enterprise\Licensing\Storage\LicenseStorageException⁩ برسائل مثل License file is present but unreadable: ... أو License file is present but empty: .... ضع المظروف في المسار المُهيَّأ واجعله قابلًا للقراءة من قِبل مستخدم عملية ⁨PHP⁩.

شهادة التوقيع لا تُحمَّل

تطرح ⁨CertificateInfo::fromPkcs12()⁩ استثناء ⁨NextPDF\Exception\SignatureException⁩ عندما يتعذَّر قراءة ملف ⁨.p12⁩ أو تحليله. الأسباب المعتادة هي مسار خاطئ، أو كلمة مرور خاطئة (تحقَّق من ⁨NEXTPDF_P12_PASSWORD⁩)، أو ملف ليس PKCS#12 فعليًا. تحقَّق بـ ⁨openssl pkcs12 -info -in signing-cert.p12 -noout⁩.

إلى أين تذهب بعد ذلك

• القالب — المرجع الكامل لتعريف القالب والربط.
• وقِّع مستند ⁨PDF⁩ بـ ⁨PAdES⁩ B-B، ثم وسِّع إلى ⁨PAdES⁩ B-T — أضف طابعًا زمنيًا وفق ⁨RFC 3161⁩ إلى توقيعك.
• قدرات ⁨NextPDF⁩ Pro — كل ما يتضمنه ترخيص Pro الخاص بك.
• قناتا التسليم — استئجار ionCube عبر الإنترنت مقابل المصدر المُوقَّع دون اتصال تمامًا.
• علامة التجربة والتقييم — كيف تبدو العلامة المائية التقييمية وكيف يزيلها الترخيص المدفوع.