Download the PHP package ivanilsonsousa/agnostic-pdf without Composer

Agnostic PDF (Laravel)

Manipulação de PDFs para projetos Laravel, com drivers intercambiáveis (mPDF e Dompdf). Fornece uma API simples para renderizar de views ou HTML, streamar, baixar, salvar e — quando suportado pelo driver — clonar páginas de PDFs existentes. Inclui ainda um serviço de compressão de PDFs.

Foco: DX simples no Laravel, mantendo o código da aplicação desacoplado do driver.

Sumário

• Instalação
• Configuração
• Uso rápido
• API do Serviço de PDF
• Clonagem de PDFs (MPDF)
• Compressão de PDFs
• Facade e Manager
• Contratos e Drivers
• Requisitos
• Licença

Instalação

O Service Provider é descoberto automaticamente pelo Laravel (auto-discovery).

Configuração

Publique o arquivo de configuração:

Isso criará config/pdf.php. Nele você define o driver principal e as opções específicas de cada driver.

Exemplo (conceitual):

Nota: A clonagem de PDFs é um recurso do MPDF.

Uso rápido

1) Renderizando uma view para resposta HTTP (controller)

2) Renderizando HTML arbitrário e salvando em disco

3) Download direto

Dica: para pipelines HTTP no Laravel, prefira streamResponse() (retorna Illuminate\Http\Response).

API do Serviço de PDF

A interface comum aos drivers é AgnosticPDF\Contracts\PDFServiceInterface. Os métodos expostos pelo serviço principal (AgnosticPDF\Services\PDFService) espelham essa interface:

• loadHtml(string $html): self Carrega HTML (da página em memória) para ser renderizado pelo driver.

• loadView(string $view, array $data = []): self Renderiza uma view do Laravel e carrega o HTML resultante.

• output(): string Retorna o binário do PDF renderizado como string.

• download(string $filename): void Força o download no navegador.

• save(string $path): void Salva o PDF no caminho indicado.

• stream(string $filename): void Envia o PDF e finaliza a resposta.

  Para integração limpa com Laravel, prefira streamResponse().

• streamResponse(string $filename): \Illuminate\Http\Response Retorna uma Response com o PDF em inline.

Clonagem de PDFs (MPDF)

A clonagem (importar páginas de um PDF existente para o documento atual) é implementada pelo contrato AgnosticPDF\Contracts\PDFClonerDriverInterface e está disponível com o driver MPDF.

Serviço de clonagem

Assinatura (resumo) do método principal:

• $callback (opcional): será chamado a cada página clonada como fn(PDFClonerService $svc, int $pageNo, int $pageCount).
• $force (opcional): comportamento de fluxo conforme sua aplicação.

Importante: Para orquestrar clonagem + renderização no mesmo documento, utilize o Manager (abaixo), que garante que clonagem e emissão compartilham a mesma instância de driver MPDF.

Compressão de PDFs

Há um serviço de compressão baseado em processo externo (executado via Symfony\Component\Process\Process):

Erros de compressão lançam AgnosticPDF\Exceptions\PDFCompressException, que expõe getContext(): array com detalhes úteis de depuração (comando, saída, caminho de entrada, etc.).

Facade e Manager

A facade AgnosticPDF\Facades\PDF resolve o Manager (AgnosticPDF\Services\PDFManagerService), que agrega:

• o serviço de PDF (renderização),
• o serviço de clonagem (quando disponível),
• o compressor.

O Manager oferece um builder para cenários em que você quer encadear operações (ex.: clonar páginas e em seguida renderizar/salvar) compartilhando a mesma instância de driver:

O builder é útil principalmente para clonagem com MPDF seguida de emissão do PDF, assegurando que tudo ocorra no mesmo documento interno.

Contratos e Drivers

Contratos

• AgnosticPDF\Contracts\PDFServiceInterface Operações de renderização/saída: loadHtml, loadView, output, download, save, stream, streamResponse.

• AgnosticPDF\Contracts\PDFClonerDriverInterface (MPDF) Clonagem de páginas:
  • prepareClone(string $pathFile): int → retorna o número de páginas do PDF origem;
  • clonePage(int $pageNo): void → importa a página para o documento atual.

Drivers disponíveis

• AgnosticPDF\Drivers\MPDFDriver Implementa PDFServiceInterface e PDFClonerDriverInterface. Fornece getMpdf(): \Mpdf\Mpdf para configurações avançadas do mPDF.

• AgnosticPDF\Drivers\DompdfDriver Implementa PDFServiceInterface. Por padrão, habilita recursos remotos e usa A4 portrait.

Você seleciona o driver ativo via config('pdf.driver').

Requisitos

• Laravel ^12.0 (auto-discovery de provider já configurado)

• Drivers:

  • mpdf/mpdf:^8.2
  • dompdf/dompdf:^3.1
• PHP: utilize a versão suportada pelo seu Laravel/driver.

Namespace & Provider

As classes públicas estão sob AgnosticPDF\... e o Service Provider é AgnosticPDF\PDFServiceProvider (auto-discovery via composer.json).

Exemplos rápidos (copie-e-cole)

Controller – stream inline

Salvar em disco

Compressão

Clonagem (MPDF) + emissão via Builder