Installazione di NextPDF Connect

In sintesi

Installare nextpdf/server con Composer, quindi eseguire uno dei tre entry point di transport. L’installazione core richiede solo PHP 8.4 e il motore NextPDF. Redis e Premium sono facoltativi.

Installazione

composer require nextpdf/server

Questo comando include nextpdf/core: ^3.0. Il pacchetto dichiara php: >=8.4 <9.0; di conseguenza, Composer ne rifiuta l’installazione su PHP 8.3 o versioni precedenti, oppure su PHP 9.

Panoramica concettuale

Il pacchetto è un pacchetto Composer di tipo library. L’installazione aggiunge quattro entry point da console in vendor/bin/:

• vendor/bin/nextpdf-mcp — il server MCP stdio.
• vendor/bin/nextpdf-server — il server REST (worker HTTP RoadRunner).
• vendor/bin/nextpdf-grpc — il server gRPC (worker gRPC RoadRunner).
• vendor/bin/generate-skills — esporta il catalogo degli strumenti come skill per gli agenti.

Un quinto script, bin/nextpdf-prune, è fornito nel repository per le attività di manutenzione. Va eseguito direttamente, invece che tramite vendor/bin/.

Non è prevista alcuna registrazione di service provider, bundle o framework. Il server è un processo standalone. Non è una libreria da integrare in un’applicazione host.

Superficie API

Composer installa anche le dipendenze di runtime del pacchetto. Le dipendenze transitive includono lo stack HTTP e gRPC:

• league/route e nyholm/psr7 — routing REST e messaggi PSR-7.
• spiral/roadrunner-http e spiral/roadrunner-grpc — il runtime worker RoadRunner per i transport REST e gRPC.
• psr/http-server-middleware e psr/http-server-handler — i contract middleware PSR-15 implementati dalla pipeline REST.
• symfony/yaml — parsing del file di configurazione.
• ramsey/uuid — identificatori di richieste e risorse.

Queste dipendenze non vanno installate direttamente. Composer le risolve automaticamente a partire da nextpdf/server.

Esempio di codice — Avvio rapido

Per verificare l’installazione, elencare il catalogo degli strumenti senza avviare alcun server:

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

Questo comando avvia il registry, esegue il rilevamento del tier e stampa gli strumenti esposti da questa installazione. L’elenco rispecchia i pacchetti facoltativi presenti. Vedere /connect/tool-catalog/.

Esempio di codice — Produzione

Un’installazione di produzione blocca la dipendenza su una versione fissa e ignora gli strumenti di sviluppo:

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

Per i transport REST e gRPC, installare anche il binario RoadRunner. RoadRunner è il supervisor di processo che governa il pool di worker. Il pacchetto PHP fornisce il worker, non il supervisor:

./vendor/bin/rr get-binary

Casi limite e insidie

• Redis facoltativo. L’estensione ext-redis è un suggest, non un require. Senza di essa, il server REST utilizza store in memoria per rate-limit, idempotenza e documenti. Questi store in memoria sono corretti per un singolo worker, ma non sono condivisi all’interno di un pool multi-worker. Per i deployment multi-worker, installare ext-redis e impostare le variabili di ambiente di Redis. Vedere /connect/configuration/.

• Premium facoltativo. nextpdf/premium è un suggest. Quando è installato insieme al server, le probe di rilevamento del tier del registry individuano le sue classi provider. Le probe registrano quindi gli strumenti Pro ed Enterprise aggiuntivi. Senza di esso, viene servito solo il catalogo core. Si tratta di una decisione di packaging presa al momento di composer require, non di un’opzione di runtime.

• Il server MCP non richiede RoadRunner. nextpdf-mcp è un semplice processo PHP che comunica in JSON-RPC su stdio. RoadRunner è necessario solo per i transport REST e gRPC.

Prestazioni

La risoluzione delle dipendenze di Composer rappresenta la maggior parte del costo in fase di installazione. Nelle immagini di produzione, usare --prefer-dist e una classmap autoritativa per mantenere basso il tempo di autoload all’avvio a freddo. Il costo di avvio del server stesso deriva dalla scansione del registry e dal rilevamento del tier. Il performance_budget in questa pagina delimita tale costo di avvio.

Note sulla sicurezza

Installare esclusivamente dal pacchetto Packagist ufficiale nextpdf/server. Bloccare la versione in composer.json ed effettuare il commit di composer.lock, affinché il catalogo degli strumenti distribuito sia riproducibile. I transport di rete richiedono una chiave API prima di servire qualsiasi endpoint diverso da quelli di health; vedere /connect/security-and-operations/.

Conformità

Questa pagina descrive esclusivamente la meccanica di installazione. Le citazioni di conformità relative a protocollo e sicurezza sono fissate in /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contesto commerciale

L’installazione core è pienamente funzionale. Gestisce la creazione, l’ispezione e la diagnostica dei documenti su tutti e tre i transport. L’aggiunta di nextpdf/premium estende il catalogo senza modificare il transport né il modello di autenticazione.

Vedere anche

• /connect/overview/ — ciò che il pacchetto offre
• /connect/quickstart/ — primo scambio eseguibile
• /connect/configuration/ — le variabili di ambiente e il file di configurazione
• /connect/deployment/ — deployment di RoadRunner, Docker e transport combinati
• /connect/tool-catalog/ — quali strumenti espone questa installazione