Referência da API do CodeIgniter

Visão geral

O pacote do CodeIgniter expõe uma pequena API voltada para controllers. Ele inclui um wrapper de biblioteca Pdf em torno de um documento (Services::pdf() e o helper global pdf()), helpers de resposta que transformam um documento construído em um DownloadResponse (PdfResponse), as factories Services por trás deles (registros de fontes e imagens, a factory de documentos e o cliente opcional de assinatura e de autoridade de carimbo do tempo (TSA)), a classe de configuração NextPdf e GeneratePdfJob para geração assíncrona a partir de callables construtores estáticos.

Comece pelo caminho principal do controller: chame Services::pdf() (ou o helper pdf()), adicione conteúdo a $pdf->document() e retorne $pdf->download('file.pdf'). Esse caminho cobre o caso comum. As tabelas de referência são organizadas por superfície; a seção Tarefas comuns mostra primeiro os formatos executáveis.

Tarefas comuns

Estes são os fluxos de produção mais comuns. Cada exemplo é verificado com base no código-fonte de nextpdf/codeigniter.

Use o caminho canônico de renderização para retornar de um controller um arquivo Portable Document Format (PDF) para download:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

O que ele faz: resolve um Pdf novo em torno de um Document novo, escreve uma célula e retorna um DownloadResponse com disposição attachment e os cabeçalhos de segurança do pacote.

Visualize um PDF inline no navegador com o mesmo wrapper e inline() em vez de download():

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

O que ele faz: usa o helper global pdf() (equivalente a Services::pdf()) e retorna um DownloadResponse com disposição inline para que o navegador exiba o PDF em vez de baixá-lo.

Gere um PDF de forma assíncrona na fila com GeneratePdfJob e um construtor estático:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

O que ele faz: enfileira a geração. O worker valida o construtor (deve ser um callable estático App\PdfBuilders\...::method) e o caminho de saída (deve resolver para dentro de WRITEPATH/pdfs/ e terminar em .pdf), constrói um documento novo e o salva.

Wrapper de biblioteca

Use esta tabela quando você tiver um wrapper Pdf e precisar dos métodos de resposta ou de salvamento dele.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: novo documento do núcleo.	Encapsula o documento fornecido para uma operação de resposta ou salvamento.	`Pdf`	Nenhum esperado.	Não reutilize o wrapper após a saída.
`Pdf::document()`	nenhum.	Retorna o documento encapsulado.	`NextPDF\Core\Document`	Nenhum esperado.	Use isto para chamar as APIs de criação do núcleo.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: nome do arquivo da resposta.	Usa a disposição inline do navegador.	`CodeIgniter\HTTP\DownloadResponse`	Erros de serialização do núcleo.	Delega para `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: nome do arquivo da resposta.	Usa a disposição de anexo do navegador.	`DownloadResponse`	Erros de serialização do núcleo.	Delega para `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: nome do arquivo da resposta.	Fornece paridade de API com outros pacotes de framework.	`DownloadResponse`	Erros de serialização do núcleo.	O CodeIgniter trata a saída binária nativamente.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: nome do arquivo da resposta.	Fornece paridade de API com outros pacotes de framework.	`DownloadResponse`	Erros de serialização do núcleo.	Use os mesmos controles de tamanho das respostas não transmitidas por fluxo.
`Pdf::save(string $path)`	`path`: destino no sistema de arquivos.	Escreve o documento encapsulado.	`void`	Erros de escrita do sistema de arquivos ou do núcleo.	Valide as raízes de armazenamento antes de salvar.

Serviços e helpers

Use esta tabela quando você precisar de uma factory de serviço específica ou de uma função helper global, incluindo o comportamento de compartilhamento e o tipo de retorno.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`Services::fontRegistry(bool $getShared = true)`	`getShared`: flag de serviço compartilhado do CodeIgniter.	Retorna um registro compartilhado, pré-carrega as fontes configuradas e, em seguida, bloqueia o registro.	`FontRegistryInterface`	`RuntimeException` para extensões ausentes ou caminho de fonte inseguro.	Rejeita stream wrappers e bytes nulos em `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: flag de serviço compartilhado.	Retorna um registro de imagens compartilhado e limitado por menos recentemente usado (LRU).	`ImageRegistry`	Nenhum esperado.	O tamanho do cache é controlado por `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: flag de serviço compartilhado.	Retorna uma factory compartilhada que usa registros compartilhados.	`DocumentFactoryInterface`	Erros de configuração do registro.	A factory e reutilizável; os documentos nao.
`Services::tsaClient(bool $getShared = true)`	`getShared`: flag de serviço compartilhado.	Retorna `null` quando `tsa.url` está vazio.	`TsaClient	null`	Erros do cliente de Hypertext Transfer Protocol (HTTP) ou de configuração do TSA.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: flag de serviço compartilhado.	Retorna `null` quando a assinatura está desabilitada.	`SignerInterface	null`	Erros de certificado ou de nível de assinatura.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: flag de serviço compartilhado.	Cria um documento novo, aplica os padrões e, opcionalmente, configura PDF/A ou Artisan.	`Document`	Erros opcionais de extensão ou de configuração do documento.	Mantenha o padrão `false` para a segurança da requisição.
`Services::pdf(bool $getShared = false)`	`getShared`: flag de serviço compartilhado.	Cria um wrapper `Pdf` novo em torno de um documento novo.	`NextPDF\CodeIgniter\Libraries\Pdf`	Erros de configuração do documento.	Principal serviço voltado para controllers.
`Services::eInvoiceEmbedder()`	nenhum.	Retorna `null`, a menos que exista a classe de embedder de e-invoice do Premium Pro.	`EmbedderInterface	null`	Erros opcionais de construção do pacote.
`Services::eInvoiceValidator()`	nenhum.	Retorna `null`, a menos que exista a classe de validador do Premium Enterprise.	`ValidatorInterface	null`	Erros opcionais de construção do pacote.
`Services::eInvoiceProfile()`	nenhum.	Retorna o perfil EN16931 quando o Premium Pro está instalado.	`ProfileInterface	null`	Erros opcionais do pacote.
`Services::schematronRunner()`	nenhum.	Retorna `null`, a menos que exista o validador Schematron do Premium Enterprise.	`SchematronRunnerInterface	null`	Erros opcionais de construção do pacote.
`Registrar::Autoload()`	nenhum.	Adiciona o helper do pacote à configuração de autoload do CodeIgniter.	`array`	Nenhum esperado.	Habilita `pdf()` e `pdf_document()` quando o módulo é carregado.
`pdf()`	nenhum.	Chama `Services::pdf(false)`.	`Pdf`	Erros de configuração do documento.	Helper de conveniência para controllers.
`pdf_document()`	nenhum.	Chama `Services::pdfDocument(false)`.	`Document`	Erros de configuração do documento.	Helper de conveniência quando se prefere a API de documento do núcleo.

Respostas HTTP

Use esta tabela quando você já tiver um Document construído e quiser montar o DownloadResponse por conta própria em vez de usar o wrapper Pdf.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: documento construído; `filename`: nome do arquivo da resposta.	Garante a extensão `.pdf` e a disposição inline.	`DownloadResponse`	Erros de serialização do núcleo.	Adiciona o tipo de conteúdo PDF e cabeçalhos defensivos.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Igual a `inline`; a disposição é anexo.	Garante a extensão `.pdf`.	`DownloadResponse`	Igual a `inline`.	Use para downloads pelo navegador.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Igual a `inline`.	Mesmo comportamento de `inline` no CodeIgniter 4 (CI4).	`DownloadResponse`	Igual a `inline`.	Existe para paridade de API entre frameworks.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Igual a `download`.	Mesmo comportamento de `download` no CI4.	`DownloadResponse`	Igual a `download`.	Existe para paridade de API entre frameworks.

Job de fila

Use esta tabela quando você conectar a geração assíncrona e precisar das chaves exatas de dados do job e do contrato do callable construtor.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`GeneratePdfJob::process()`	Chaves de dados do job: `builder`, `outputPath` e `context` opcional.	Usa um array de contexto vazio quando omitido.	`void`	`InvalidArgumentException` para construtor ou caminho de saída inseguro; erros de escrita do núcleo.	O construtor deve ser `App\PdfBuilders\...\*::method`.
Callable construtor	`Document $doc`, `array $context`.	Sem contexto padrão além dos dados do job.	`Document`	Exceções específicas do construtor.	Requer um callable estático porque os payloads de fila do CI4 são dados serializados.

Configuração

Use esta tabela quando você alterar os padrões de formato de página, caminhos, assinatura, TSA ou metadados do documento na classe de configuração NextPdf.

Propriedade	Tipo	Comportamento padrão	Observações
`pageFormat`	`string`	`A4`.	Define o formato de página padrão.
`orientation`	`string`	`P`.	Define a orientação padrão.
`unit`	`string`	`mm`.	Define a unidade padrão.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` e `WRITEPATH . 'cache/nextpdf'`.	Mantenha os caminhos dentro do armazenamento controlado pela aplicação.
`signature`	`array`	Desabilitado com o nível `B-B`.	Certificado, chave, senha, certificados extras e nível.
`tsa`	`array`	Desabilitado quando o Uniform Resource Locator (URL) é `null`; tempo limite de 30 segundos.	Credenciais, arquivos de Transport Layer Security mútuo (mTLS), pins de chave pública e política de HTTP.
`ocspCache`	`array`	Habilitado com um tempo de vida (TTL) de 86400 segundos.	Usado pelos fluxos de validação de assinatura quando disponível.
`preloadFonts`	`list<string>`	Vazio.	Pré-carregado antes de o registro ser bloqueado.
`imageCacheMb`	`int`	`50`.	Controla o cache de imagens com tempo de vida do processo.
`fontCacheLocking`	`bool`	`true`.	Mantém as mutações do registro de fontes fora do tratamento de requisições.
`artisan`	`array`	Renderizador do Chrome desabilitado, a menos que seja configurado e instalado.	Mapeia para `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Criador `NextPDF`, autor vazio, idioma `en`, margens padrão e fonte padrão.	`Services::pdfDocument()` aplica apenas `creator`, `language` e (quando não vazio) `author`; `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` e `bleed_box` são padrões definidos, mas atualmente ele não os aplica.

Notas de desenvolvimento

GeneratePdfJob confina a saída em WRITEPATH . 'pdfs' e exige .pdf.
Callables construtores fora de App\PdfBuilders são rejeitados para evitar execução arbitrária de código a partir de payloads de fila modificados.
Use service('pdf') ou o helper do pacote para fluxos de controller; use jobs de fila para geração de longa duração.