Premium الإصدار

ثبّت حزمة ⁨NextPDF⁩ المدفوعة الخاصة وصادق عليها باستخدام ⁨Composer⁩

لمحة سريعة

إن حزم ⁨NextPDF⁩ المدفوعة — ‏nextpdf/pro وnextpdf/enterprise والحزمة الفوقية nextpdf/premium — ليست منشورة على فهرس ⁨Packagist⁩ العام. فهي تقيم في مستودع ⁨Composer⁩ خاص مرتبط بحسابك، ولهذا فإن أمر composer require nextpdf/premium البسيط لا يستطيع العثور عليها حتى تخبر ⁨Composer⁩ بأمرين: أين يقع المستودع، وكيف تُجري المصادقة عليه.

تكمل هذه الصفحة من حيث تنتهي الترخيص والتفعيل. فبمجرد حصولك على بيانات الاعتماد، تهيّئ ⁨Composer⁩ مرة واحدة، وتثبّت الحزمة، وتتحقق منها. كل ما هنا سلوك قياسي من ⁨Composer⁩؛ لا شيء منه أدوات خاصة بـ⁨NextPDF.⁩ عامِل رمز مستودعك مثل مفتاح ⁨API⁩ تمامًا، كما تعامل صفحة الترخيص ظرف الترخيص الموقّع: أبقِه خارج إدارة الإصدارات العامة.

من أين تأتي بيانات اعتمادك

يُصدَر عنوان ⁨URL⁩ لمستودعك الخاص، واسم المستخدم، والرمز بعد حصولك على ترخيص — إمّا عبر الشراء من خلال التاجر المسجَّل لدينا أو ببدء تقييم — من بوابة الترخيص. للاطلاع على مسار الشراء، ونموذج العقدين (الشراء مقابل الترخيص)، ومن تتواصل معه لشؤون الفوترة مقابل دعم المنتج، راجِع الشراء والترخيص.

1. أين تقيم الحزم المدفوعة

يُصدر بوابة الترخيص لديك أمرين للتثبيت:

عنوان ⁨URL⁩ لمستودع ⁨Composer⁩ خاص — وهو نقطة النهاية المصادَق عليها التي تخدم الحزم المدفوعة.
اسم مستخدم ورمز (زوج بيانات اعتماد ⁨HTTP Basic⁩) لتلك النقطة.

أينما أظهرت هذه الصفحة مضيف مستودع، استبدله بعنوان ⁨URL⁩ للمستودع من بوابة الترخيص لديك. وأينما أظهرت اسم مستخدم أو رمزًا، استبدله ببيانات الاعتماد الصادرة لحسابك. لا ينشر ⁨NextPDF⁩ عنوان ⁨URL⁩ واحدًا مشتركًا؛ فنقطة النهاية وبيانات الاعتماد خاصة باشتراكك.

2. أضف المستودع الخاص إلى ملف ⁨composer.json⁩

أخبر ⁨Composer⁩ بالمستودع عبر أمر واحد، تُشغّله في جذر مشروعك:

composer config repositories.nextpdf composer https://repo.example.com/nextpdf

استبدل https://repo.example.com/nextpdf بالعنوان من بوابتك. يوجّه نوع المستودع composer‏ ⁨Composer⁩ نحو فهرس بصيغة ⁨Composer⁩ (ملف packages.json)، وهو ما تخدمه نقطة نهاية حزمة خاصة.

يكتب ذلك الأمر كتلة repositories داخل ملف composer.json. ويمكنك أيضًا إضافتها يدويًا:

{
    "repositories": {
        "nextpdf": {
            "type": "composer",
            "url": "https://repo.example.com/nextpdf"
        }
    }
}

إن تعريف المستودع ليس سرًّا — فهو يسمّي موقعًا فحسب، ولذا فمن الآمن إيداعه في إدارة الإصدارات. أما بيانات الاعتماد في الخطوة التالية فهي ما يجب أن تحميه.

3. صادِق بإحدى الطرق القياسية الثلاث

يقرأ ⁨Composer⁩ بيانات اعتماد ⁨HTTP Basic⁩ لمضيف ما من عدة أماكن. اختر الطريقة التي تطابق المكان الذي تثبّت فيه.

الطريقة أ — ملف ⁨auth.json⁩ (التطوير المحلي)

في جهاز مطوّر، خزّن بيانات الاعتماد في ملف auth.json بجوار composer.json. استخدم مضيف عنوان ⁨URL⁩ لمستودعك مفتاحًا:

composer config --auth http-basic.repo.example.com your-username your-token

ينشئ هذا (أو يحدّث) ملف auth.json محليًا في المشروع:

{
    "http-basic": {
        "repo.example.com": {
            "username": "your-username",
            "password": "your-token"
        }
    }
}

يجب أن يطابق مفتاح المضيف (repo.example.com) المضيف في عنوان ⁨URL⁩ للمستودع تمامًا — فـ⁨Composer⁩ يطابق بيانات الاعتماد بالطلبات عبر المضيف.

الطريقة ب — متغيّر البيئة ⁨COMPOSER_AUTH⁩ (⁨CI/CD⁩)

في التكامل المستمر عادةً لا تريد ملفًا على القرص. يقرأ ⁨Composer⁩ بيانات الاعتماد نفسها من متغيّر البيئة COMPOSER_AUTH، الذي تكون قيمته سلسلة ⁨JSON⁩ بالشكل نفسه الذي لملف auth.json:

export COMPOSER_AUTH='{"http-basic":{"repo.example.com":{"username":"your-username","password":"your-token"}}}'
composer install

احقن COMPOSER_AUTH من مخزن أسرار مزوّد ⁨CI⁩ لديك (متغيّر مُقنّع أو سرّ أو ربط خزنة) حتى لا يظهر الرمز أبدًا في تعريف خط الأنابيب أو في سجلّ البناء.

الطريقة ج — مصادقة شاملة لكل مستخدم (محطة عمل مشتركة)

لمصادقة كل مشروع للمستخدم الحالي دون ملف لكل مشروع، اكتب بيانات الاعتماد في ملف auth.json الشامل لـ⁨Composer:⁩

composer config --global --auth http-basic.repo.example.com your-username your-token

يخزّن هذا بيانات الاعتماد تحت دليل ⁨Composer⁩ الرئيسي (COMPOSER_HOME، مثلًا ~/.composer/auth.json أو ~/.config/composer/auth.json). وهو ينطبق على كل المشاريع التي تبنيها بصفتك هذا المستخدم، لذا فضّل الطريقة أ أو ب حين ينبغي قصر بيانات اعتماد على مشروع أو خط أنابيب واحد.

4. أبقِ بيانات الاعتماد خارج إدارة الإصدارات

عنوان ⁨URL⁩ للمستودع آمن للإيداع؛ أما الرمز فلا. هناك قاعدتان تبقيان الأسرار خارج تاريخك:

تجاهل ملف المصادقة المحلي. أضف auth.json إلى .gitignore حتى لا تُودَع بيانات اعتماد محلية في المشروع أبدًا:
```
/auth.json
```
احقن الرمز في ⁨CI/CD.⁩ وفّر COMPOSER_AUTH (الطريقة ب) من مخزن أسرار خط الأنابيب لديك بدلًا من إيداع ملف auth.json في المستودع أو طهيه في طبقة من صورة حاوية.

إذا أُودِع رمز أو طُبع يومًا ما، فدوّره عبر بوابة الترخيص لديك — عامِله بوصفه مُخترقًا، تمامًا كما تفعل مع مفتاح ⁨API⁩ مُسرَّب.

5. ثبّت وتحقّق

بوجود المستودع وبيانات الاعتماد، اطلب الإصدار الذي يخوّله ترخيصك:

# Pick the package for your entitlement:
composer require nextpdf/pro
# or
composer require nextpdf/enterprise
# or the metapackage, which the licensing page uses:
composer require nextpdf/premium

ثبّت إصدارًا رئيسيًا إذا كان مشروعك يفضّل القيود الصريحة — مثلًا composer require nextpdf/pro:^3، بما يطابق القيد الذي تستخدمه صفحات وحدة ⁨Pro.⁩

تحقق من أن ⁨Composer⁩ حلّ الحزمة الخاصة ومن أن مُحمِّلها التلقائي يعمل. أكّد أولًا أن الحزمة مثبّتة بتشغيل composer show <installed-package> لأي إصدار طلبته — مثلًا composer show nextpdf/pro أو composer show nextpdf/enterprise أو composer show nextpdf/premium:

# Use the package name you actually required:
composer show nextpdf/pro
# or
composer show nextpdf/enterprise
# or
composer show nextpdf/premium

إذا أبلغ composer show عن الحزمة وإصدارها، فقد حُلّت الحزمة الخاصة. ثم تُعيد إعادة تشغيل composer dump-autoload توليد المُحمِّل التلقائي بنظافة، فتصبح أصناف الحزمة قابلة للاكتشاف:

composer dump-autoload

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

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

// Replace the placeholder with a documented public class from YOUR edition's
// API reference. Do not hardcode a class from a different edition.
$class = 'Your\\Installed\\Edition\\DocumentedClass';
var_dump(class_exists($class));

إن تثبيت الحزمة ليس مثل تفعيلها. فالحزمة وحدها لا تمنح قدرات ⁨Pro⁩ أو ⁨Enterprise⁩ — بل الترخيص الموقّع الذي تفعّله هو الذي يختار الإصدار النشط. بعد تثبيت ناجح، اتبع الترخيص والتفعيل لوضع ظرف الترخيص وتفعيله، ولبنى ⁨ionCube⁩ المُرمَّزة، هيّئ مُحمِّل ⁨ionCube⁩.

استكشاف الأخطاء وإصلاحها

خطأ 401 غير مصرّح به أو 403 ممنوع

وصل ⁨Composer⁩ إلى المستودع لكن بيانات الاعتماد رُفِضت أو كانت غير كافية. أكّد أن مفتاح المضيف في auth.json / COMPOSER_AUTH يطابق مضيف المستودع تمامًا (بلا مخطّط، بلا مسار، بلا شَرطة مائلة لاحقة)، وأن اسم المستخدم والرمز حاليان، وأن الرمز لم ينتهِ صلاحيته أو يُدوَّر في بوابتك. يشير 401 إلى بيانات اعتماد خاطئة أو مفقودة؛ ويشير 403 إلى بيانات اعتماد صالحة لا يشمل نطاقها الحزمة أو الإصدار الذي طلبته — تحقق من أن اشتراكك يخوّل اسم الحزمة الذي تطلبه.

الحزمة غير موجودة / “⁨could not find a matching version⁩”

يعني هذا عادةً أن ⁨Composer⁩ لم يستخدم الفهرس الخاص أو لم يصل إليه (فبحث في ⁨Packagist⁩ العام فقط)، أو أنه وصل إلى الفهرس لكنه لم يجد حزمة أو إصدارًا قابلًا للتثبيت يطابق. أكّد أن كتلة repositories.nextpdf موجودة في ملف composer.json لـهذا المشروع مع "type": "composer" وعنوان ⁨URL⁩ الصحيح، وأنك تطلب اسم الحزمة بالضبط (nextpdf/pro أو nextpdf/enterprise أو nextpdf/premium). شغّل composer config repositories لطباعة ما يراه ⁨Composer.⁩ خطأ مطبعي في العنوان أو كتلة مستودع مفقودة سبب شائع، لكن تحقق أيضًا من أن قيد الإصدار لديك يطابق إصدارًا منشورًا، وأن متطلب منصة ⁨PHP⁩ لمشروعك (وminimum-stability) يسمح بالحزمة، وأن استحقاق رمزك يغطّي فعلًا الحزمة التي تطلبها.

الرمز يعمل محليًا لكنه يفشل في ⁨CI⁩

ملف auth.json المحلي غير موجود على المُشغِّل. اضبط COMPOSER_AUTH من مخزن أسرار ⁨CI⁩ لديك (الطريقة ب) بدلًا من الاعتماد على ملف، وتأكد من تصدير المتغيّر قبل تشغيل composer install. في البنى الحاوية، مرّر السرّ في وقت البناء دون ترسيخه في طبقة من الصورة.

مفتاح مضيف خاطئ

تُطابَق بيانات الاعتماد عبر المضيف. إذا كان عنوان ⁨URL⁩ للمستودع https://repo.example.com/nextpdf، فيجب أن يكون المفتاح repo.example.com — لا العنوان الكامل ولا مسارًا فرعيًا. يجعل مفتاح غير مطابق ⁨Composer⁩ يرسل الطلب دون مصادقة، وهو ما يظهر بصورة خطأ 401.