Configuração do NextPDF para CodeIgniter 4

Visão geral

A configuração do NextPDF está em NextPDF\CodeIgniter\Config\NextPdf, uma subclasse de BaseConfig do CodeIgniter. Você pode substituir valores estendendo a classe em app/Config/ ou definindo chaves .env com o prefixo nextpdf.. Os padrões funcionam sem configuração adicional.

Visão conceitual

NextPdf é uma BaseConfig tipada. Ela é intencionalmente não final. No CodeIgniter, a configuração da aplicação estende a classe do pacote para que a aplicação possa substituir os padrões. Quando o CodeIgniter constrói a configuração, BaseConfig resolve as substituições de ambiente para cada propriedade pública, inclusive chaves aninhadas de arrays.

Os caminhos padrão de fonte e cache usam a constante WRITEPATH do CodeIgniter: WRITEPATH . 'fonts' e WRITEPATH . 'cache/nextpdf'.

Chaves de configuração

Cada chave abaixo é uma propriedade pública de NextPdf. Os padrões são verificados em relação ao código-fonte do pacote.

Padrões de página e documento

Chave	Tipo	Padrão	Descrição
pageFormat	string	A4	Formato da página.
orientation	string	P	P retrato ou L paisagem.
unit	string	mm	Unidade de medida.
defaults.creator	string	NextPDF	Metadados do criador do Portable Document Format (PDF).
defaults.author	string	''	Metadados do autor; ignorados quando vazio.
defaults.language	string	en	Tag de idioma do documento.
defaults.margin_top	float	10.0	Margem superior.
defaults.margin_right	float	10.0	Margem direita.
defaults.margin_bottom	float	10.0	Margem inferior.
defaults.margin_left	float	10.0	Margem esquerda.
defaults.font_family	string	dejavusans	Família de fonte padrão.
defaults.font_size	float	12.0	Tamanho de fonte padrão.
defaults.trim_box	list<float>|null	null	Trim box, quando definida.
defaults.bleed_box	list<float>|null	null	Bleed box, quando definida.

O pacote aplica defaults.creator e defaults.language em cada documento. Ele aplica defaults.author apenas quando o valor não está vazio.

Caminhos e caches

Chave	Tipo	Padrão	Descrição
fontsPath	string	WRITEPATH/fonts	Diretório de arquivos de fonte.
cachePath	string	WRITEPATH/cache/nextpdf	Diretório de cache.
preloadFonts	list<string>	[]	Caminhos absolutos para fontes pré-carregadas na inicialização.
imageCacheMb	int	50	Orçamento do cache de imagens menos usadas recentemente (LRU) em megabytes (MB).
fontCacheLocking	bool	true	Bloqueia o cache de fontes após o aquecimento.

O registro de fontes rejeita qualquer fontsPath que contenha um stream wrapper (://) ou um byte nulo, e gera um erro em tempo de execução. Consulte /integrations/codeigniter/security-and-operations/.

Arquivamento e cor (NextPDF Pro)

Chave	Tipo	Padrão	Descrição
pdfa	string|null	null	Versão PDF/A: 4, 4e, 4f.
iccProfile.rgb	string|null	null	Caminho do perfil International Color Consortium (ICC) para vermelho, verde e azul (RGB).
iccProfile.cmyk	string|null	null	Caminho do perfil ICC de ciano, magenta, amarelo e preto (CMYK).

pdfa só tem efeito quando o NextPDF Pro está instalado e a capacidade de arquivamento está disponível. Somente no core, a chave é ignorada.

Assinatura digital (NextPDF Pro / Enterprise)

Chave	Tipo	Padrão	Descrição
signature.enabled	bool	false	Habilita o serviço de assinatura.
signature.certificate	string|null	null	Caminho do arquivo de certificado.
signature.private_key	string|null	null	Caminho do arquivo da chave privada.
signature.password	string	''	Senha da chave privada.
signature.extra_certs	list<string>	[]	Caminhos de certificados de cadeia adicionais.
signature.level	string	B-B	Identificador do nível de assinatura.

Services::pdfSigner() retorna null a menos que signature.enabled seja true e signature.certificate não esteja vazio. O nível padrão é B-B. O NextPDF Pro fornece a assinatura baseline B-B. Os níveis de validação de longo prazo são um recurso separado do Enterprise e estão documentados na referência Premium, não aqui.

As PDF Advanced Electronic Signatures (PAdES) B-T são produzidas pelo mecanismo Core. A integração com o CodeIgniter não adiciona B-T por conta própria, e o Pro fornece apenas a baseline B-B. Esta documentação será atualizada se e quando o B-T do Pro for lançado.

Time Stamp Authority

Chave	Tipo	Padrão	Descrição
tsa.url	string|null	null	URL do endpoint da Time Stamp Authority (TSA).
tsa.username	string	''	Nome de usuário da autenticação básica da TSA.
tsa.password	string	''	Senha da autenticação básica da TSA.
tsa.cert	string|null	null	Caminho do certificado do cliente.
tsa.key	string|null	null	Caminho da chave do cliente.
tsa.timeout	int	30	Tempo limite da requisição em segundos.
tsa.pinned_public_keys	list<string>	[]	Chaves públicas fixadas da TSA.
tsa.warn_on_key_rotation	bool	true	Emite aviso sobre a rotação de chave da TSA.
tsa.allow_insecure_http	bool	false	Permite HTTP em texto puro para a TSA.

Services::tsaClient() retorna null quando tsa.url é null ou uma string vazia. Quando você seleciona um nível de assinatura que exige um carimbo de data e hora, o assinante anexa automaticamente o cliente da TSA.

Cache de OCSP

Chave	Tipo	Padrão	Descrição
ocspCache.enabled	bool	true	Habilita o cache de respostas do Online Certificate Status Protocol (OCSP).
ocspCache.ttl	int	86400	Tempo de vida (TTL) do cache em segundos.
ocspCache.directory	string|null	null	Diretório de cache; usa o padrão do mecanismo quando null.

Renderizador HTML do Chrome (NextPDF Artisan)

Chave	Tipo	Padrão	Descrição
artisan.chrome_binary	string|null	null	Caminho do binário do Chrome/Chromium.
artisan.render_timeout	int	30	Tempo limite de renderização em segundos.
artisan.default_css	string	''	Folha de estilos padrão.
artisan.no_sandbox	bool	false	Passa --no-sandbox ao Chrome.
artisan.max_html_size	int	5000000	Tamanho máximo do HTML de entrada em bytes.

O renderizador do Chrome só é configurado para o documento quando artisan.chrome_binary está definido e nextpdf/artisan está instalado.

Substituir com .env

BaseConfig resolve as substituições de ambiente para cada propriedade. A chave de busca é o nome curto da classe em minúsculas, nextpdf, seguido pelo caminho da propriedade. Use pontos para endereçar chaves aninhadas de arrays. Tanto a forma com ponto quanto a forma com sublinhado são aceitas.

.env

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

O prefixo é o nome curto da classe em minúsculas. Ele permanece nextpdf mesmo que a classe seja escrita como NextPdf. Você também pode usar a forma totalmente qualificada (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Substituir estendendo a classe

Para uma configuração tipada e versionada, estenda a classe do pacote em app/Config/. O CodeIgniter carrega a classe da aplicação no lugar da classe padrão do pacote. Esse arquivo declara uma classe e não causa efeitos colaterais. Isso o mantém alinhado com a expectativa da PSR-1 de que um arquivo declare símbolos ou execute lógica com efeitos colaterais, mas não ambos (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Casos de borda e pegadinhas

• Substituir uma única chave aninhada com .env altera apenas essa chave; o restante do array mantém o padrão.
• .env fornece valores em formato de string. O CodeIgniter converte true/false e strings numéricas. Coloque entre aspas os valores que devem permanecer como strings literais.
• Estender a classe com um array defaults parcial substitui o array inteiro. Inclua todas as chaves, como mostrado acima.

Notas de segurança

Mantenha os caminhos de certificado e chave fora do controle de versão. Informe-os por meio do .env ou de um gerenciador de segredos. tsa.allow_insecure_http deve permanecer false em produção. Consulte /integrations/codeigniter/security-and-operations/.

Conformidade

• O arquivo de extensão de configuração da aplicação declara uma classe e não causa efeitos colaterais (PSR-1 §x1.x1.p3).

Contexto comercial

O core do NextPDF é Apache-2.0. As chaves signature.* e pdfa só têm efeito quando o NextPDF Pro ou Enterprise está instalado. O pacote do CodeIgniter expõe os métodos de serviço correspondentes. Esses métodos retornam null até você instalar o pacote Premium relevante. Consulte </get-license/?intent=codeigniter-signing>.

Veja também

• /integrations/codeigniter/install/ — instalar o pacote.
• /integrations/codeigniter/quickstart/ — primeiro PDF.
• /integrations/codeigniter/production-usage/ — controllers conectados via DI e jobs de fila.
• /integrations/codeigniter/security-and-operations/ — proteção da configuração de assinatura e de caminhos.