Instalação do NextPDF Connect

Visão geral

Instale o nextpdf/server pelo Composer. Em seguida, execute um dos três pontos de entrada de transporte. A instalação do core requer apenas o PHP 8.4 e o engine do NextPDF. Redis e Premium são opcionais.

Instalação

composer require nextpdf/server

Esse comando instala o nextpdf/core: ^3.0. Como o pacote declara php: >=8.4 <9.0, o Composer se recusa a instalá-lo no PHP 8.3 ou inferior, ou no PHP 9.

Visão conceitual

Trata-se de um pacote Composer do tipo library. Instalá-lo adiciona quatro pontos de entrada de console em vendor/bin/:

• vendor/bin/nextpdf-mcp — o servidor stdio do Model Context Protocol (MCP).
• vendor/bin/nextpdf-server — o servidor Representational State Transfer (REST) (worker HTTP do RoadRunner).
• vendor/bin/nextpdf-grpc — o servidor gRPC (worker gRPC do RoadRunner).
• vendor/bin/generate-skills — exporta o catálogo de ferramentas como skills de agente.

Um quinto script, bin/nextpdf-prune, também vem no repositório para tarefas de manutenção. Execute-o diretamente, em vez de por vendor/bin/.

Você não precisa de um service provider, bundle ou registro em framework. O servidor roda como um processo autônomo. Ele não é uma biblioteca que você integra a uma aplicação hospedeira.

Superfície da API

O Composer também instala as dependências de runtime do pacote. Essas dependências transitivas incluem as pilhas de Hypertext Transfer Protocol (HTTP) e gRPC:

• league/route e nyholm/psr7 — roteamento REST e mensagens PHP Standard Recommendation (PSR)-7.
• spiral/roadrunner-http e spiral/roadrunner-grpc — o runtime de worker do RoadRunner para os transportes REST e gRPC.
• psr/http-server-middleware e psr/http-server-handler — os contratos de middleware PSR-15 que o pipeline REST implementa.
• symfony/yaml — análise do arquivo de configuração.
• ramsey/uuid — identificadores de requisição e de recurso.

Não instale esses pacotes diretamente. O Composer os resolve para você a partir do nextpdf/server.

Exemplo de código — Início rápido

Para verificar a instalação, liste o catálogo de ferramentas sem iniciar um servidor:

./vendor/bin/generate-skills --dry-run --list-tools

Esse comando inicia o registro, executa a detecção de tier e imprime as ferramentas que esta instalação expõe. A lista reflete os pacotes opcionais instalados. Consulte /connect/tool-catalog/.

Exemplo de código — Produção

Uma instalação de produção fixa a dependência e dispensa o ferramental de desenvolvimento:

composer require nextpdf/server --no-dev
composer install --no-dev --optimize-autoloader --classmap-authoritative

Para os transportes REST e gRPC, instale também o binário do RoadRunner. O RoadRunner é o supervisor de processos que controla o pool de workers. O pacote PHP fornece o worker, não o supervisor:

./vendor/bin/rr get-binary

Casos extremos e pegadinhas

• Redis opcional. A extensão ext-redis é um suggest, não um require. Sem ela, o servidor REST usa armazenamentos em memória para rate-limit, idempotência e documentos. Esses armazenamentos em memória funcionam corretamente para um único worker, mas não são compartilhados em um pool com vários workers. Para implantações com vários workers, instale a ext-redis e defina as variáveis de ambiente do Redis. Consulte /connect/configuration/.

• Premium opcional. O nextpdf/premium é um suggest. Quando você o instala junto com o servidor, as sondas de detecção de tier do registro encontram as classes de provider desse pacote e registram as ferramentas adicionais Pro e Enterprise. Sem ele, apenas o catálogo do core é servido. Essa é uma decisão de empacotamento tomada no momento do composer require, não uma chave de runtime.

• O servidor MCP não precisa do RoadRunner. O nextpdf-mcp é um processo PHP simples que fala JavaScript Object Notation Remote Procedure Call (JSON-RPC) por entrada e saída padrão (stdio). O RoadRunner é necessário apenas para os transportes REST e gRPC.

Desempenho

A resolução de dependências do Composer responde pela maior parte do tempo de instalação. Em imagens de produção, use --prefer-dist e um classmap autoritativo para manter baixo o tempo de autoload no cold-boot. O custo de boot do próprio servidor vem da varredura do registro e da detecção de tier. O performance_budget nesta página limita esse custo de boot.

Notas de segurança

Instale apenas a partir do pacote oficial do Packagist nextpdf/server. Fixe a versão no composer.json e faça commit do composer.lock para que o catálogo de ferramentas implantado seja reproduzível. Os transportes em rede exigem uma chave de API (application programming interface) antes de servir qualquer endpoint que não seja de health; consulte /connect/security-and-operations/.

Conformidade

Esta página descreve apenas a mecânica de instalação. As citações de conformidade de protocolo e segurança estão fixadas em /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contexto comercial

A instalação do core é totalmente funcional. Ela lida com criação, inspeção e diagnóstico de documentos nos três transportes. Adicionar o nextpdf/premium estende o catálogo sem alterar o modelo de transporte ou de autenticação.

Consulte também

• /connect/overview/ — o que o pacote fornece
• /connect/quickstart/ — primeira troca executável
• /connect/configuration/ — variáveis de ambiente e o arquivo de configuração
• /connect/deployment/ — RoadRunner, Docker e implantação com transporte combinado
• /connect/tool-catalog/ — quais ferramentas esta instalação expõe