Instale o NextPDF Artisan

Visão geral

Instale o nextpdf/artisan com o Composer. O Composer também instala a dependência de runtime chrome-php/chrome. Depois, disponibilize um binário do Chrome ou do Chromium para o processo PHP.

Instalação

composer require nextpdf/artisan

O pacote declara estas restrições no composer.json:

Requisito	Restrição	Observações
`php`	`>=8.4 <9.0`	Apenas PHP 8.4
`nextpdf/core`	`^3.0 \|\| ^5.2`	O mecanismo open-source do NextPDF
`chrome-php/chrome`	`^1.15`	Biblioteca cliente do Chrome DevTools Protocol (CDP); incluída transitivamente
`psr/log`	`^3.0`	Ponto opcional para injeção de logger

O Composer resolve chrome-php/chrome automaticamente. O Composer nunca instala o binário do Chrome; esse binário é uma dependência do sistema.

Disponibilize o binário do Chrome

A ponte exige um binário executável do Chrome ou do Chromium. Por padrão, chrome-php/chrome procura esse binário em caminhos comuns. Para fixar um caminho explícito, informe-o pela configuração. Consulte /integrations/artisan/configuration/ e a página dedicada /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Antes de conectar o binário à aplicação, verifique se ele executa em modo headless:

chromium --headless --dump-dom about:blank

Uma execução bem-sucedida imprime um documento DOM vazio e encerra com código 0. Uma saída diferente de zero significa que o binário ou suas bibliotecas compartilhadas estão ausentes. Corrija isso antes de continuar, porque a ponte expõe a mesma falha como uma ChromeRenderException no momento da renderização.

Verifique se o pacote está conectado

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

Isso constrói o renderizador e lê a política de segurança Hypertext Markup Language (HTML) padrão sem iniciar o Chrome. A verificação confirma que o autoloading e as ligações de contrato do nextpdf/core são resolvidos. (Comportamento assegurado por tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Instalações em contêiner

No Docker, o sandbox do Chrome normalmente não consegue iniciar como process ID (PID) 1 / root sem capacidades extras do kernel. O pacote expõe uma chave noSandbox para esse caso. Desabilitar o sandbox do Chrome tem um custo real de segurança. As páginas /integrations/artisan/security-and-operations/ e /integrations/artisan/chrome-renderer-setup/ documentam esse custo e declaram seus limites de forma explícita. Não defina a chave sem ler essa seção.

Casos extremos e armadilhas

chrome-php/chrome presente, mas sem binário. O Composer é bem-sucedido; a primeira renderização lança ChromeRenderException e encapsula a falha de inicialização. A verificação da biblioteca é separada da verificação do binário.
chrome-php/chrome ausente. Se a biblioteca for removida do autoloader, BrowserPool::getBrowser() lança ChromeNotAvailableException com o comando de remediação exato. (Assegurado por tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
Restrição de versão. nextpdf/core: ^3.0 || ^5.2 — o Artisan oferece suporte às duas linhas principais do core. Fixe a versão do core que a aplicação tem como alvo.

Notas de segurança

Instalar a ponte introduz um processo externo (Chrome) na fronteira de confiança. Revise /integrations/artisan/security-and-operations/ antes de expor qualquer caminho de renderização a HTML fornecido pelo usuário.

Veja também

/integrations/artisan/overview/
/integrations/artisan/configuration/
/integrations/artisan/quickstart/
/integrations/artisan/chrome-renderer-setup/
/integrations/artisan/security-and-operations/