Premium edição

Instale e autentique o pacote premium privado do NextPDF com o Composer

Visão geral

Os pacotes premium do NextPDF — nextpdf/pro, nextpdf/enterprise e o metapacote nextpdf/premium — não são publicados no índice público do Packagist. Eles vivem em um repositório Composer privado vinculado à sua conta, então um simples composer require nextpdf/premium não consegue encontrá-los até que você informe ao Composer duas coisas: onde está o repositório e como se autenticar nele.

Esta página continua de onde Licenciamento e ativação parou. Depois de obter as credenciais, você configura o Composer uma vez, instala o pacote e o verifica. Tudo aqui é comportamento padrão do Composer; nada disso é ferramenta específica do NextPDF. Trate seu token de repositório como uma chave de API, exatamente como a página de licenciamento trata o envelope de licença assinado: mantenha-o fora do controle de versão público.

De onde vêm as suas credenciais

A URL do seu repositório privado, o usuário e o token são emitidos depois que você obtém uma licença — seja comprando por meio do nosso Merchant of Record, seja iniciando uma avaliação — a partir do portal de licenças. Para o fluxo de compra, o modelo de dois contratos (compra versus licença) e quem contatar para cobrança versus ajuda com o produto, consulte Compra e licenciamento.

1. Onde os pacotes premium ficam

Seu portal de licenças emite duas coisas para a instalação:

Uma URL de repositório Composer privado — o endpoint autenticado que serve os pacotes premium.
Um usuário e token (um par de credenciais HTTP Basic) para esse endpoint.

Sempre que esta página mostrar um host de repositório, substitua pela URL do repositório do seu portal de licenças. Sempre que mostrar um usuário ou token, substitua pelas credenciais emitidas para a sua conta. O NextPDF não publica uma URL única e compartilhada; o endpoint e as credenciais são específicos da sua assinatura.

2. Adicione o repositório privado ao composer.json

Informe ao Composer sobre o repositório com um único comando, executado na raiz do seu projeto:

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

Substitua https://repo.example.com/nextpdf pela URL do seu portal. O tipo de repositório composer aponta o Composer para um índice no formato Composer (um packages.json), que é o que um endpoint de pacote privado serve.

Esse comando grava um bloco repositories no composer.json. Você também pode adicioná-lo manualmente:

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

A definição do repositório não é um segredo — ela apenas nomeia um local, então pode ser comitada com segurança. As credenciais da próxima etapa é que você precisa proteger.

3. Autentique-se com um dos três métodos padrão

O Composer lê as credenciais HTTP Basic de um host em vários lugares. Escolha o método que combina com o local onde você está instalando.

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

Para uma máquina de desenvolvedor, armazene a credencial em um arquivo auth.json ao lado do composer.json. Use o host da URL do seu repositório como chave:

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

Isso cria (ou atualiza) um auth.json local do projeto:

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

A chave de host (repo.example.com) deve corresponder exatamente ao host na URL do repositório — o Composer associa as credenciais às requisições pelo host.

Método B — variável de ambiente COMPOSER_AUTH (CI/CD)

Em integração contínua, você normalmente não quer um arquivo em disco. O Composer lê as mesmas credenciais da variável de ambiente COMPOSER_AUTH, cujo valor é uma string JSON com o mesmo formato do auth.json:

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

Injete COMPOSER_AUTH a partir do cofre de segredos do seu provedor de CI (variável mascarada, segredo ou binding de vault) para que o token nunca apareça na definição do pipeline nem no log de build.

Método C — auth global por usuário (estação de trabalho compartilhada)

Para autenticar todos os projetos do usuário atual sem um arquivo por projeto, grave a credencial no auth.json global do Composer:

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

Isso armazena a credencial no seu diretório home do Composer (COMPOSER_HOME, por exemplo ~/.composer/auth.json ou ~/.config/composer/auth.json). Ela se aplica a todos os projetos que você compila como esse usuário, então prefira o Método A ou B quando uma credencial deve ter escopo limitado a um projeto ou pipeline.

4. Mantenha as credenciais fora do controle de versão

A URL do repositório pode ser comitada com segurança; o token, não. Duas regras mantêm os segredos fora do seu histórico:

Ignore o arquivo de auth local. Adicione auth.json ao .gitignore para que uma credencial local do projeto nunca seja comitada:
```
/auth.json
```
Injete o token no CI/CD. Forneça COMPOSER_AUTH (Método B) a partir do cofre de segredos do seu pipeline, em vez de comitar um auth.json no repositório ou embuti-lo em uma camada de imagem de contêiner.

Se um token chegar a ser comitado ou impresso, rotacione-o pelo seu portal de licenças — trate-o como comprometido, exatamente como você faria com uma chave de API vazada.

5. Instale e verifique

Com o repositório e as credenciais no lugar, faça o require da edição a que sua licença dá direito:

# 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

Fixe uma versão major se o seu projeto prefere restrições explícitas — por exemplo composer require nextpdf/pro:^3, que combina com a restrição usada pelas páginas do módulo Pro.

Verifique se o Composer resolveu o pacote privado e se o autoloader dele funciona. Primeiro, confirme que o pacote está instalado executando composer show <installed-package> para a edição que você fez require — por exemplo 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

Se o composer show reportar o pacote e sua versão, o pacote privado foi resolvido. Reexecutar o composer dump-autoload então regenera o autoloader de forma limpa, de modo que as classes do pacote sejam descobríveis:

composer dump-autoload

Como verificação opcional no nível de código, você pode confirmar que uma classe da sua edição instalada é carregada pelo autoload. Não adivinhe um nome de classe: abra a referência de API da edição que você instalou e escolha qualquer classe pública documentada, depois teste se ela é resolvida. A classe a procurar depende da sua edição — uma classe que vem em uma edição pode não estar presente em outra, e uma única classe sendo carregada pelo autoload prova apenas que aquela edição está presente, não que todas as edições estão 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 o pacote não é o mesmo que ativá-lo. O pacote sozinho não concede os recursos do Pro ou do Enterprise — a licença assinada que você ativa é o que seleciona a edição ativa. Após uma instalação bem-sucedida, siga Licenciamento e ativação para posicionar e ativar o envelope de licença e, para builds codificadas com ionCube, configure o ionCube Loader.

Solução de problemas

401 Unauthorized ou 403 Forbidden

O Composer alcançou o repositório, mas as credenciais foram rejeitadas ou eram insuficientes. Confirme que a chave de host no auth.json / COMPOSER_AUTH corresponde exatamente ao host do repositório (sem esquema, sem caminho, sem barra final), que o usuário e o token estão atuais e que o token não expirou nem foi rotacionado no seu portal. Um 401 indica uma credencial errada ou ausente; um 403 indica uma credencial válida cujo escopo não inclui o pacote ou a edição que você solicitou — verifique se a sua assinatura dá direito ao nome de pacote que você está fazendo require.

Pacote não encontrado / “could not find a matching version”

Isso geralmente significa que o Composer não usou nem alcançou o índice privado (então ele só procurou no Packagist público), ou que ele alcançou o índice mas não encontrou um pacote ou versão instalável que corresponda. Confirme que o bloco repositories.nextpdf existe no composer.json deste projeto, com "type": "composer" e a URL correta, e que você está fazendo require do nome de pacote exato (nextpdf/pro, nextpdf/enterprise ou nextpdf/premium). Execute composer config repositories para imprimir o que o Composer enxerga. Um erro de digitação na URL ou um bloco de repositório ausente é uma causa comum, mas verifique também se a sua restrição de versão corresponde a uma versão publicada, se o requisito de plataforma PHP do seu projeto (e minimum-stability) permite o pacote, e se o direito de uso do seu token realmente cobre o pacote que você está fazendo require.

O token funciona localmente mas falha no CI

O auth.json local não está presente no runner. Defina COMPOSER_AUTH a partir do cofre de segredos do seu CI (Método B) em vez de depender de um arquivo, e garanta que a variável seja exportada antes de o composer install rodar. Em builds em contêiner, passe o segredo no momento do build sem persisti-lo em uma camada de imagem.

Chave de host errada

As credenciais são associadas pelo host. Se a URL do repositório for https://repo.example.com/nextpdf, a chave deve ser repo.example.com — não a URL completa e não um subcaminho. Uma chave incompatível faz o Composer enviar a requisição sem autenticação, o que aparece como um 401.