NextPDF Gotenberg: início rápido

Visão geral

Este tutorial converte um arquivo .docx em Portable Document Format (PDF). Ao final, você terá três coisas: uma instância funcional do bridge, uma conexão verificada com o serviço e um PDF em disco. O programa completo está no repositório, em examples/convert-office-to-pdf.php. Os trechos abaixo foram extraídos desse programa.

Este tutorial começa pelo caminho funcional mais simples. Tópicos de produção, incluindo origem de segredos, retentativas, timeouts e observabilidade, são abordados em /integrations/gotenberg/production-usage/.

Antes de começar

Antes de continuar, confirme estas três coisas:

1. Você executou composer require nextpdf/gotenberg, e um cliente PHP Standards Recommendation (PSR)-18, junto com factories PSR-17, está instalado. Consulte /integrations/gotenberg/install/.
2. Um serviço Gotenberg está acessível via Hypertext Transfer Protocol Secure (HTTPS). O bridge rejeita http:// simples antes que qualquer requisição saia do processo.
3. Você tem um arquivo de exemplo em um destes formatos: .docx, .xlsx, .pptx, .odt, .ods ou .odp. Outras extensões falham com um ValueError.

Passo 1 — descreva o serviço

GotenbergConfig é um value object imutável. No mínimo, ele precisa da URL base HTTPS do serviço Gotenberg:

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    apiKey: $apiKey,
);

O transporte fixado em cURL aplica timeout como tempo limite de transferência, em segundos. Quando apiKey não está vazio, o bridge o envia como Authorization: Bearer <token>. Deixe apiKey vazio se a implantação do Gotenberg não exigir um token.

Passo 2 — conecte o bridge

Passe a configuração e os componentes PSR para o bridge. Injete também uma responseFactory para habilitar o transporte cURL com pinning de Domain Name System (DNS) e Transport Layer Security (TLS):

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

O bridge nunca cria um cliente Hypertext Transfer Protocol (HTTP) por você. Use o cliente PSR-18 e as factories PSR-17 que você instalou. O arquivo de exemplo mostra a conexão com Guzzle em um comentário.

Passo 3 — verifique a disponibilidade

Verifique o serviço antes de converter um arquivo. A sondagem valida a URL sem tráfego de rede e, em seguida, envia uma requisição HEAD para <apiUrl>/health:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

Para uma URL vazia, não HTTPS ou com endereço privado, ou diante de qualquer erro de rede, isAvailable() retorna false (nunca lança exceção). Um status abaixo de 500 vindo de /health significa que o serviço está disponível.

Passo 4 — converta

Chame convertFile() com um caminho em disco. O bridge canonicaliza o caminho para bloquear travessia de diretórios. Ele mapeia a extensão para um formato suportado, verifica o tamanho e o nome do arquivo e, em seguida, envia uma requisição multipart para <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

Para converter bytes que já estão em memória, use convertString(). Passe o nome original do arquivo para que o bridge consiga detectar a extensão:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

Passo 5 — use o resultado

O resultado inclui três coisas: os bytes do PDF, o formato de origem e uma verificação de validade:

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() é true quando o corpo não está vazio e começa com %PDF. size() retorna o tamanho em bytes. A partir daqui, o PDF é um stream comum que você pode passar para o NextPDF para pós-processamento.

O programa completo

O programa completo e executável está em examples/convert-office-to-pdf.php no repositório do pacote. Ele inclui análise de argumentos, configuração orientada por variáveis de ambiente, sondagem de integridade, tratamento exaustivo de erros e a etapa de escrita. Execute-o com:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

Próximos passos

• /integrations/gotenberg/configuration/ — revise todas as opções e regras de seleção de transporte.
• /integrations/gotenberg/production-usage/ — lide com segredos, retentativas, timeouts, registro de logs e concorrência.
• /integrations/gotenberg/troubleshooting/ — entenda cada exceção que este código pode lançar e o que ela significa.
• /integrations/gotenberg/integration/ — conduza um pipeline de renderização do NextPDF por meio do serviço.