Premium редакция

Установка и аутентификация приватного премиум-пакета NextPDF через Composer

Кратко

Премиум-пакеты NextPDF — nextpdf/pro, nextpdf/enterprise и метапакет nextpdf/premium — не публикуются в публичном индексе Packagist. Они находятся в приватном репозитории Composer, привязанном к вашей учётной записи, поэтому обычная команда composer require nextpdf/premium не сможет их найти, пока вы не сообщите Composer две вещи: где находится репозиторий и как к нему аутентифицироваться.

Эта страница продолжает там, где заканчивается Лицензирование и активация. Получив учётные данные, вы один раз настраиваете Composer, устанавливаете пакет и проверяете его. Всё здесь — стандартное поведение Composer; ничего из этого не является инструментарием, специфичным для NextPDF. Относитесь к токену репозитория как к ключу API, ровно так же, как страница лицензирования относится к подписанному конверту лицензии: держите его вне публичной системы контроля версий.

Откуда берутся ваши учётные данные

URL вашего приватного репозитория, имя пользователя и токен выдаются после получения лицензии — либо при покупке через нашего Merchant of Record (продавца, официально оформляющего ваш заказ), либо при запуске оценки — на портале лицензий. Путь покупки, модель из двух договоров (покупка и лицензия), а также к кому обращаться по вопросам выставления счетов и по вопросам продукта см. в разделе Покупка и лицензирование.

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 на URL из вашего портала. Тип репозитория composer указывает Composer на индекс формата Composer (packages.json) — именно его раздаёт приватная конечная точка пакета.

Эта команда записывает блок repositories в composer.json. Его также можно добавить вручную:

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

Определение репозитория не является секретом — оно лишь называет местоположение, поэтому его безопасно фиксировать в системе контроля версий. Защищать нужно учётные данные из следующего шага.

3. Аутентификация одним из трёх стандартных методов

Composer считывает учётные данные HTTP Basic для хоста из нескольких мест. Выберите метод, соответствующий тому, куда вы устанавливаете.

Метод A — 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 сопоставляет учётные данные с запросами по хосту.

Метод B — переменная окружения 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-провайдера (маскированная переменная, секрет или привязка к хранилищу), чтобы токен никогда не появлялся в определении конвейера или в журнале сборки.

Метод C — глобальная аутентификация на уровне пользователя (общая рабочая станция)

Чтобы аутентифицировать каждый проект текущего пользователя без файла на каждый проект, запишите учётные данные в глобальный 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). Они применяются ко всем проектам, которые вы собираете под этим пользователем, поэтому предпочитайте Метод A или B, когда учётные данные должны быть ограничены одним проектом или конвейером.

4. Держите учётные данные вне системы контроля версий

URL репозитория безопасно фиксировать; токен — нет. Два правила удерживают секреты вне вашей истории:

Игнорируйте локальный файл аутентификации. Добавьте auth.json в .gitignore, чтобы локальные для проекта учётные данные никогда не фиксировались:
```
/auth.json
```
Внедряйте токен в CI/CD. Предоставляйте COMPOSER_AUTH (Метод B) из хранилища секретов конвейера, а не фиксируйте 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 Unauthorized или 403 Forbidden

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. Опечатка в URL или отсутствующий блок репозитория — частая причина, но также проверьте, что ваше ограничение версии совпадает с опубликованной версией, что требование PHP-платформы вашего проекта (и minimum-stability) допускает пакет и что право вашего токена действительно покрывает пакет, который вы затребовали.

Токен работает локально, но не работает в CI

Локальный auth.json отсутствует на исполнителе. Задайте COMPOSER_AUTH из хранилища секретов CI (Метод B), вместо того чтобы полагаться на файл, и убедитесь, что переменная экспортируется до запуска composer install. В контейнеризированных сборках передавайте секрет во время сборки, не сохраняя его в слой образа.

Неправильный ключ хоста

Учётные данные сопоставляются по хосту. Если URL репозитория — https://repo.example.com/nextpdf, ключ должен быть repo.example.com — не полный URL и не подпуть. Несовпадающий ключ заставляет Composer отправить запрос без аутентификации, что проявляется как 401.