Premium edición

Instalar y autenticar el paquete privado de NextPDF Premium con Composer

En resumen

Los paquetes premium de NextPDF — nextpdf/pro, nextpdf/enterprise y el metapaquete nextpdf/premium — no se publican en el índice público de Packagist. Residen en un repositorio privado de Composer vinculado a tu cuenta, de modo que un simple composer require nextpdf/premium no puede encontrarlos hasta que se le indican dos cosas a Composer: dónde está el repositorio y cómo autenticarse en él.

Esta página retoma donde lo deja Licencias y activación. Una vez que se dispone de las credenciales, se configura Composer una vez, se instala el paquete y se verifica. Todo lo que aparece aquí es comportamiento estándar de Composer; nada de ello son herramientas específicas de NextPDF. Trata tu token de repositorio como una clave de API, exactamente como la página de licencias trata el sobre de licencia firmado: mantenlo fuera del control de versiones público.

De dónde proceden tus credenciales

La URL de tu repositorio privado, el usuario y el token se emiten después de obtener una licencia —ya sea comprando a través de nuestro comerciante de registro o iniciando una evaluación— desde el portal de licencias. Para conocer la vía de compra, el modelo de dos contratos (compra frente a licencia) y a quién dirigirte para cuestiones de facturación frente a ayuda sobre el producto, consulta Compra y licenciamiento.

1. Dónde residen los paquetes premium

Tu portal de licencias emite dos cosas para la instalación:

Una URL de repositorio privado de Composer: el extremo autenticado que sirve los paquetes premium.
Un usuario y un token (un par de credenciales HTTP Basic) para ese extremo.

Allí donde esta página muestre un host de repositorio, sustitúyelo por la URL del repositorio de tu portal de licencias. Allí donde muestre un usuario o un token, sustitúyelos por las credenciales emitidas para tu cuenta. NextPDF no publica una única URL compartida; el extremo y las credenciales son específicos de tu suscripción.

2. Añadir el repositorio privado a composer.json

Indícale a Composer el repositorio con un solo comando, ejecutado en la raíz de tu proyecto:

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

Sustituye https://repo.example.com/nextpdf por la URL de tu portal. El tipo de repositorio composer apunta Composer a un índice en formato Composer (un packages.json), que es lo que sirve un extremo de paquetes privado.

Ese comando escribe un bloque repositories en composer.json. También puedes añadirlo a mano:

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

La definición del repositorio no es un secreto: solo nombra una ubicación, por lo que es seguro confirmarla en el control de versiones. Las credenciales del paso siguiente son lo que debes proteger.

3. Autenticar con uno de los tres métodos estándar

Composer lee las credenciales HTTP Basic de un host desde varios lugares. Elige el método que corresponda al lugar donde realizas la instalación.

Método A — auth.json (desarrollo local)

Para una máquina de desarrollo, guarda la credencial en un archivo auth.json junto a composer.json. Usa el host de la URL de tu repositorio como clave:

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

Esto crea (o actualiza) un auth.json local del proyecto:

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

La clave del host (repo.example.com) debe coincidir exactamente con el host de la URL del repositorio: Composer asocia las credenciales a las solicitudes por host.

Método B — variable de entorno COMPOSER_AUTH (CI/CD)

En integración continua normalmente no se desea tener un archivo en disco. Composer lee las mismas credenciales desde la variable de entorno COMPOSER_AUTH, cuyo valor es una cadena JSON con la misma forma que auth.json:

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

Inyecta COMPOSER_AUTH desde el almacén de secretos de tu proveedor de CI (variable enmascarada, secreto o enlace de vault) para que el token nunca aparezca en la definición de la canalización ni en el registro de compilación.

Método C — autenticación global por usuario (estación de trabajo compartida)

Para autenticar todos los proyectos del usuario actual sin un archivo por proyecto, escribe la credencial en el auth.json global de Composer:

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

Esto almacena la credencial en tu directorio principal de Composer (COMPOSER_HOME, por ejemplo ~/.composer/auth.json o ~/.config/composer/auth.json). Se aplica a todos los proyectos que compilas como ese usuario, así que prefiere el Método A o B cuando una credencial deba acotarse a un solo proyecto o canalización.

4. Mantener las credenciales fuera del control de versiones

La URL del repositorio se puede confirmar sin problema; el token no. Dos reglas mantienen los secretos fuera de tu historial:

Ignora el archivo de autenticación local. Añade auth.json a .gitignore para que una credencial local del proyecto nunca se confirme:
```
/auth.json
```
Inyecta el token en CI/CD. Proporciona COMPOSER_AUTH (Método B) desde el almacén de secretos de tu canalización en lugar de confirmar un auth.json en el repositorio o incrustarlo en una capa de imagen de contenedor.

Si alguna vez un token se confirma o se imprime, rótalo a través de tu portal de licencias: trátalo como comprometido, exactamente como harías con una clave de API filtrada.

5. Instalar y verificar

Con el repositorio y las credenciales en su sitio, requiere la edición a la que te da derecho tu licencia:

# 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

Fija una versión mayor si tu proyecto prefiere restricciones explícitas, por ejemplo composer require nextpdf/pro:^3, igual que la restricción que usan las páginas del módulo Pro.

Verifica que Composer resolvió el paquete privado y que su autocargador funciona. Primero confirma que el paquete está instalado ejecutando composer show <installed-package> para la edición que hayas requerido, por ejemplo composer show nextpdf/pro, composer show nextpdf/enterprise o 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 informa del paquete y su versión, el paquete privado se resolvió. Al volver a ejecutar composer dump-autoload se regenera entonces el autocargador de forma limpia, de modo que las clases del paquete son detectables:

composer dump-autoload

Como comprobación opcional a nivel de código, puedes confirmar que una clase de tu edición instalada se autocarga. No adivines un nombre de clase: abre la referencia de la API de la edición que instalaste y elige cualquier clase pública documentada, luego prueba que se resuelve. La clase que buscar depende de tu edición: una clase que se incluye en una edición puede no estar presente en otra, y que una sola clase se autocargue solo demuestra que su edición está presente, no que todas las ediciones estén instaladas.

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

Instalar el paquete no es lo mismo que activarlo. El paquete por sí solo no otorga las capacidades de Pro o Enterprise: la licencia firmada que activas selecciona la edición activa. Tras una instalación correcta, sigue Licencias y activación para colocar y activar el sobre de licencia y, en el caso de compilaciones codificadas con ionCube, configura el ionCube Loader.

Resolución de problemas

401 Unauthorized o 403 Forbidden

Composer alcanzó el repositorio pero las credenciales fueron rechazadas o resultaron insuficientes. Confirma que la clave del host en auth.json / COMPOSER_AUTH coincide exactamente con el host del repositorio (sin esquema, sin ruta, sin barra final), que el usuario y el token están vigentes y que el token no ha caducado ni se ha rotado en tu portal. Un 401 apunta a una credencial errónea o ausente; un 403 apunta a una credencial válida cuyo alcance no incluye el paquete o la edición que solicitaste: comprueba que tu suscripción te da derecho al nombre de paquete que estás requiriendo.

Paquete no encontrado / «could not find a matching version»

Esto suele significar que Composer no usó ni alcanzó el índice privado (de modo que solo buscó en Packagist público), o que alcanzó el índice pero no encontró ningún paquete o versión instalable que coincida. Confirma que el bloque repositories.nextpdf existe en el composer.json de este proyecto con "type": "composer" y la URL correcta, y que estás requiriendo el nombre exacto del paquete (nextpdf/pro, nextpdf/enterprise o nextpdf/premium). Ejecuta composer config repositories para imprimir lo que Composer ve. Un error tipográfico en la URL o un bloque de repositorio ausente es una causa frecuente, pero comprueba también que tu restricción de versión coincide con una versión publicada, que el requisito de plataforma PHP de tu proyecto (y minimum-stability) permite el paquete, y que el derecho de uso de tu token cubre realmente el paquete que estás requiriendo.

El token funciona en local pero falla en CI

El auth.json local no está presente en el runner. Define COMPOSER_AUTH desde el almacén de secretos de tu CI (Método B) en lugar de depender de un archivo, y asegúrate de exportar la variable antes de que se ejecute composer install. En compilaciones en contenedor, pasa el secreto en tiempo de compilación sin persistirlo en una capa de imagen.

Clave de host incorrecta

Las credenciales se asocian por host. Si la URL del repositorio es https://repo.example.com/nextpdf, la clave debe ser repo.example.com, no la URL completa ni una subruta. Una clave no coincidente hace que Composer envíe la solicitud sin autenticar, lo que se manifiesta como un 401.