Premium édition

Installer et authentifier le paquet privé NextPDF premium avec Composer

En un coup d’œil

Les paquets premium NextPDF — nextpdf/pro, nextpdf/enterprise et le métapaquet nextpdf/premium — ne sont pas publiés sur l’index public Packagist. Ils vivent dans un dépôt Composer privé lié à ton compte, si bien qu’un simple composer require nextpdf/premium ne peut pas les trouver tant que tu n’as pas indiqué deux choses à Composer : où se trouve le dépôt, et comment s’y authentifier.

Cette page prend le relais là où Licence et activation s’arrête. Une fois que tu disposes des identifiants, tu configures Composer une fois, installes le paquet et le vérifies. Tout ce qui figure ici relève du comportement Composer standard ; rien n’est un outillage propre à NextPDF. Traite ton jeton de dépôt comme une clé d’API, exactement comme la page de licence traite l’enveloppe de licence signée : garde-le hors du système public de gestion de versions.

D’où viennent tes identifiants

L’URL de ton dépôt privé, ton nom d’utilisateur et ton jeton sont émis après l’obtention d’une licence — soit en achetant via notre Marchand de référence, soit en démarrant une évaluation — depuis le portail de licences. Pour le parcours d’achat, le modèle à deux contrats (achat versus licence), et à qui s’adresser pour la facturation versus l’aide produit, consulte Achat et licence.

1. Où vivent les paquets premium

Ton portail de licences émet deux éléments pour l’installation :

Une URL de dépôt Composer privé — le point d’accès authentifié qui sert les paquets premium.
Un nom d’utilisateur et un jeton (une paire d’identifiants HTTP Basic) pour ce point d’accès.

Partout où cette page affiche un hôte de dépôt, substitue l’URL de dépôt issue de ton portail de licences. Partout où elle affiche un nom d’utilisateur ou un jeton, substitue les identifiants émis pour ton compte. NextPDF ne publie pas une URL partagée unique ; le point d’accès et les identifiants sont propres à ton abonnement.

2. Ajouter le dépôt privé à composer.json

Informe Composer du dépôt avec une seule commande, exécutée à la racine de ton projet :

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

Remplace https://repo.example.com/nextpdf par l’URL de ton portail. Le type de dépôt composer pointe Composer vers un index au format Composer (un packages.json), qui est ce que sert un point d’accès de paquets privé.

Cette commande écrit un bloc repositories dans composer.json. Tu peux aussi l’ajouter à la main :

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

La définition du dépôt n’est pas un secret — elle ne nomme qu’un emplacement, donc on peut la valider sans risque. Ce sont les identifiants de l’étape suivante que tu dois protéger.

3. S’authentifier avec l’une des trois méthodes standard

Composer lit les identifiants HTTP Basic d’un hôte depuis plusieurs endroits. Choisis la méthode qui correspond à l’endroit où tu installes.

Méthode A — auth.json (développement local)

Pour une machine de développeur, stocke l’identifiant dans un fichier auth.json à côté de composer.json. Utilise l’hôte de ton URL de dépôt comme clé :

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

Cela crée (ou met à jour) un auth.json local au projet :

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

La clé d’hôte (repo.example.com) doit correspondre exactement à l’hôte de l’URL du dépôt — Composer associe les identifiants aux requêtes par hôte.

Méthode B — variable d’environnement COMPOSER_AUTH (CI/CD)

En intégration continue, tu ne veux généralement pas d’un fichier sur le disque. Composer lit les mêmes identifiants depuis la variable d’environnement COMPOSER_AUTH, dont la valeur est une chaîne JSON de la même forme que auth.json :

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

Injecte COMPOSER_AUTH depuis le magasin de secrets de ton fournisseur de CI (variable masquée, secret ou liaison de coffre) afin que le jeton n’apparaisse jamais dans la définition du pipeline ni dans le journal de build.

Méthode C — authentification globale par utilisateur (poste de travail partagé)

Pour authentifier chaque projet de l’utilisateur courant sans fichier par projet, écris l’identifiant dans l’auth.json global de Composer :

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

Cela stocke l’identifiant sous ton répertoire personnel Composer (COMPOSER_HOME, par exemple ~/.composer/auth.json ou ~/.config/composer/auth.json). Il s’applique à tous les projets que tu construis en tant que cet utilisateur ; préfère donc la Méthode A ou B lorsqu’un identifiant doit être limité à un seul projet ou pipeline.

4. Garder les identifiants hors du système de gestion de versions

L’URL du dépôt peut être validée sans risque ; le jeton, non. Deux règles gardent les secrets hors de ton historique :

Ignore le fichier d’authentification local. Ajoute auth.json à .gitignore afin qu’un identifiant local au projet ne soit jamais validé :
```
/auth.json
```
Injecte le jeton en CI/CD. Fournis COMPOSER_AUTH (Méthode B) depuis le magasin de secrets de ton pipeline plutôt que de valider un auth.json dans le dépôt ou de l’intégrer dans une couche d’image de conteneur.

Si un jeton est un jour validé ou imprimé, fais-le tourner via ton portail de licences — traite-le comme compromis, exactement comme tu le ferais pour une clé d’API divulguée.

5. Installer et vérifier

Le dépôt et les identifiants étant en place, requiers l’édition à laquelle ta licence donne droit :

# 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

Épingle une version majeure si ton projet préfère des contraintes explicites — par exemple composer require nextpdf/pro:^3, correspondant à la contrainte qu’utilisent les pages du module Pro.

Vérifie que Composer a bien résolu le paquet privé et que son autochargeur fonctionne. Confirme d’abord que le paquet est installé en exécutant composer show <installed-package> pour l’édition que tu as requise — par exemple composer show nextpdf/pro, composer show nextpdf/enterprise ou 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

Si composer show signale le paquet et sa version, le paquet privé a été résolu. Réexécuter composer dump-autoload régénère alors proprement l’autochargeur, de sorte que les classes du paquet soient détectables :

composer dump-autoload

En vérification facultative au niveau du code, tu peux confirmer qu’une classe de ton édition installée s’autocharge. Ne devine pas un nom de classe : ouvre la référence d’API de l’édition que tu as installée et choisis n’importe quelle classe publique documentée, puis teste qu’elle se résout. La classe à rechercher dépend de ton édition — une classe présente dans une édition peut être absente d’une autre, et l’autochargement d’une seule classe prouve seulement que son édition est présente, pas que toutes les éditions sont installées.

<?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));

Installer le paquet n’est pas la même chose que l’activer. Le paquet seul n’accorde pas les capacités Pro ou Enterprise — la licence signée que tu actives sélectionne l’édition active. Après une installation réussie, suis Licence et activation pour placer et activer l’enveloppe de licence, et, pour les builds encodés avec ionCube, mets en place le Loader ionCube.

Dépannage

401 Unauthorized ou 403 Forbidden

Composer a atteint le dépôt mais les identifiants ont été rejetés ou étaient insuffisants. Confirme que la clé d’hôte dans auth.json / COMPOSER_AUTH correspond exactement à l’hôte du dépôt (pas de schéma, pas de chemin, pas de barre oblique finale), que le nom d’utilisateur et le jeton sont à jour, et que le jeton n’a pas expiré ni été renouvelé dans ton portail. Un 401 indique un identifiant erroné ou manquant ; un 403 indique un identifiant valide dont la portée n’inclut pas le paquet ou l’édition que tu as demandé — vérifie que ton abonnement donne droit au nom de paquet que tu requiers.

Paquet introuvable / « could not find a matching version »

Cela signifie généralement que Composer n’a pas utilisé ou atteint l’index privé (il n’a donc cherché que dans le Packagist public), ou qu’il a atteint l’index mais n’y a trouvé aucun paquet ou version installable correspondant. Confirme que le bloc repositories.nextpdf existe dans le composer.json de ce projet avec "type": "composer" et la bonne URL, et que tu requiers le nom exact du paquet (nextpdf/pro, nextpdf/enterprise ou nextpdf/premium). Exécute composer config repositories pour imprimer ce que Composer voit. Une faute de frappe dans l’URL ou un bloc de dépôt manquant est une cause courante, mais vérifie aussi que ta contrainte de version correspond à une version publiée, que l’exigence de plateforme PHP de ton projet (et minimum-stability) autorise le paquet, et que le droit lié à ton jeton couvre bien le paquet que tu requiers.

Le jeton fonctionne en local mais échoue en CI

L’auth.json local n’est pas présent sur le runner. Définis COMPOSER_AUTH depuis le magasin de secrets de ta CI (Méthode B) plutôt que de compter sur un fichier, et assure-toi que la variable est exportée avant l’exécution de composer install. Dans les builds conteneurisés, passe le secret au moment du build sans le persister dans une couche d’image.

Mauvaise clé d’hôte

Les identifiants sont associés par hôte. Si l’URL du dépôt est https://repo.example.com/nextpdf, la clé doit être repo.example.com — pas l’URL complète et pas un sous-chemin. Une clé qui ne correspond pas fait envoyer la requête sans authentification par Composer, ce qui se manifeste par un 401.