Guia do desenvolvedor do CodeIgniter

Visão geral

O pacote CodeIgniter fornece fábricas de serviço, funções auxiliares e um pequeno wrapper de biblioteca Pdf para um único documento Portable Document Format (PDF). Use o wrapper em controllers. O processamento em fila usa callables de construtores estáticos porque os payloads de fila do CodeIgniter precisam ser dados serializados.

Use este guia para projetar fluxos de controller, serviços, construtores de fila e testes em torno de nextpdf/codeigniter.

Limites da arquitetura

Camada	Pertence a	Responsabilidade	Não coloque aqui
Controller	Aplicação	Autorize, chame um construtor ou serviço e retorne um `DownloadResponse`.	Lógica de layout compartilhada.
Wrapper de biblioteca	`nextpdf/codeigniter`	Encapsule um `Document` e forneça auxiliares de resposta e salvamento.	Armazenamento de documentos de longa duração.
Fábrica de serviço	`nextpdf/codeigniter`	Crie registros compartilhados e documentos novos.	Raízes de armazenamento específicas do negócio.
Construtor de fila	Aplicação	Construa um documento a partir da entrada de um callable estático.	Objetos de requisição ou estado que não possam ser serializados.
Motor principal	`nextpdf/nextpdf`	Construa e serialize o PDF.	Política de resposta ou de fila do CodeIgniter.

Ciclo de vida em tempo de execução

Estágio	Comportamento	Ação do desenvolvedor
Registro de autoload	`Registrar::Autoload()` registra o carregamento de helpers do módulo.	Carregue o módulo por meio da configuração do CodeIgniter.
Resolução de serviço	`Services::pdf()` retorna, por padrão, um wrapper em torno de um documento novo.	Resolva uma vez por requisição.
Criação	O código da aplicação usa `Pdf::document()` para chamadas principais de documento.	Mantenha o código de construção de documentos em serviços ou construtores.
Resposta	`PdfResponse` retorna um `DownloadResponse`.	Deixe o pacote definir os cabeçalhos do PDF.
Execução em fila	`GeneratePdfJob::process()` valida o construtor e o caminho de saída e, em seguida, salva.	Coloque os construtores de fila em `App\PdfBuilders`.

Estrutura de aplicação recomendada

Caminho	Finalidade
`app/PdfBuilders/*`	Construtores estáticos seguros para fila aceitos por `GeneratePdfJob`.
`app/Libraries/*`	Wrappers de aplicação opcionais em torno de fluxos de trabalho de documentos recorrentes.
`app/Services/*`	Política de recuperação e armazenamento de dados de domínio.
`app/Config/NextPdf.php`	Sobrescritas da aplicação para a configuração do pacote.
`tests/app/PdfBuilders/*`	Testes de construtor e de payload de fila.

Use os helpers do pacote para fluxos curtos. Use chamadas de serviço explícitas quando a construção do documento pertencer a uma classe que você possa testar diretamente.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

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

Padrão de construtor de fila

Os construtores de fila devem ser estáticos, determinísticos e localizados em App\PdfBuilders. Mantenha o array de contexto simples o suficiente para ser serializado e auditado.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

O job restringe a saída ao diretório de PDF configurado da aplicação. Se a aplicação precisar de armazenamento específico por tenant, coloque essa política em um único serviço e teste-a antes de despachar o job.

Pontos de extensão

Ponto de extensão	Use para	Restrição
`Services::pdfDocument()`	Personalize a criação do documento.	Deve retornar um documento novo.
`Services::fontRegistry()`	Pré-aqueça as fontes e acesse o registro.	Rejeite caminhos inseguros e mantenha o registro bloqueado após o pré-aquecimento.
`Services::pdfSigner()`	Habilite a assinatura digital opcional.	Retorne `null` quando a assinatura estiver desabilitada.
`NextPDF\CodeIgniter\Libraries\Pdf`	Encapsule o trabalho de documento voltado ao controller.	Um wrapper corresponde a um documento.
`App\PdfBuilders::*`	Construtores de documento seguros para fila.	String de callable estatico obrigatoria.
`app/Config/NextPdf.php`	Padrões da aplicação e configurações de integração.	Mantenha os valores de produção explícitos.

Fluxo de trabalho de desenvolvimento

Comece com um controller que chame pdf() ou service('pdf').
Mova a construção recorrente de documentos para app/PdfBuilders ou para um serviço da aplicação.
Use GeneratePdfJob quando a geração for lenta demais para o caminho da requisição.
Mantenha o contexto da fila serializável e pequeno.
Armazene a saída sob a raiz de armazenamento de PDF aprovada, a menos que você estenda deliberadamente a política.
Adicione testes para helpers, serviços, payloads de fila e caminhos inseguros.

Tratamento de falhas

Falha	Onde deve ser tratada	Resposta recomendada
Extensão ausente ou caminho de fonte inseguro	Fábrica de serviço.	Falhe rápido durante a resolução do serviço.
Callable construtor inválido	Validação do job de fila.	Rejeite o job e registre a string do construtor sem segredos.
Caminho de saída inseguro	Serviço de armazenamento e job de fila.	Rejeite antes do despacho e mantenha a validação do job.
Erro de serialização da resposta	Tratamento de erros do controller ou do framework.	Não envie um corpo de resposta parcial.
Classe Premium opcional indisponível	Valor de retorno do método de serviço.	Trate `null` explicitamente antes de usar os recursos opcionais de e-invoice.

Padrões seguros

Aspecto	Padrão	Quando sobrescrever
Namespace do construtor de fila	`App\PdfBuilders`.	Mantenha o padrão, a menos que você também atualize a política de segurança.
Raiz de saída	`WRITEPATH/pdfs`.	Sobrescreva apenas com uma allowlist mais rigorosa.
Nome do arquivo de resposta	`document.pdf`.	Use nomes de arquivo de negócio higienizados.
Métodos de stream	Paridade de application programming interface (API) com outros frameworks.	Não dependa do streaming como limite de memória no CodeIgniter.
Serviço de documento	Novo por padrão.	Não solicite documentos compartilhados a partir do código de requisição.

Checklist de testes

Os testes de serviço verificam se cada resolução de Services::pdf() retorna um documento independente.
Os testes de helper verificam se pdf() e pdf_document() retornam objetos novos.
Os testes de resposta verificam os cabeçalhos e a normalização do nome do arquivo.
Os testes de fila cobrem strings de construtor inválidas e caminhos de saída inseguros.
Os testes de construtor usam dados de contexto representativos.
Os testes de configuração cobrem o caminho de fonte, o caminho de cache, a assinatura desabilitada e os estados de Time-Stamp Authority (TSA) desabilitada.