Integração do NextPDF com CodeIgniter

Visão geral

Instale o pacote, e o CodeIgniter 4 faz a integração por você. Use esta página para confirmar a integração: descoberta, modelo de vínculos, publicação de configuração e um teste de fumaça de método único que comprova que a integração funciona.

Instalação

composer require nextpdf/codeigniter

Você não precisa editar um service provider nem alterar um arquivo de bootstrap. Consulte /integrations/codeigniter/install/ para conferir as restrições de versão verificadas.

Inicialização / descoberta automática

O CodeIgniter 4 encontra o pacote por meio da descoberta de pacotes do Composer quando Config\Modules::$discoverInComposer é true, que é o padrão do framework. O prefixo PHP Standard Recommendation 4 (PSR-4) NextPDF\CodeIgniter\ é mapeado para src/CodeIgniter/, permitindo que o framework resolva NextPDF\CodeIgniter\Config\Services para o arquivo correspondente (PSR-4 §x1.x3). /integrations/codeigniter/boot-and-discovery/ documenta a sequência completa e as propriedades de Config\Modules que a controlam.

Vínculos do container

O CodeIgniter 4 não inclui um container PSR-11. A PSR-11 §1.3 desencoraja o padrão service-locator (modal SHOULD NOT). O pacote segue a convenção de locator do framework e a mantém enxuta. Cada vínculo é uma factory estática nomeada que recebe um parâmetro bool $getShared.

Nome do serviço	Retorna	Tempo de vida padrão
fontRegistry	FontRegistryInterface	compartilhado
imageRegistry	ImageRegistry	compartilhado
documentFactory	DocumentFactoryInterface	compartilhado
pdfDocument	Document	novo
pdf	Pdf	novo
tsaClient	?TsaClient	compartilhado
pdfSigner	?SignerInterface	novo

Use qualquer um dos pontos de entrada; eles são equivalentes:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

$a = Services::pdf(false);   // direct
$b = \service('pdf');        // helper → Services::pdf()

Os helpers globais pdf() e pdf_document() encapsulam Services::pdf(false) e Services::pdfDocument(false).

Publicar a configuração

A configuração do pacote fica em NextPDF\CodeIgniter\Config\NextPdf, um BaseConfig não final. Você pode sobrescrevê-la de duas formas suportadas:

1. Estenda a classe (tipada, versionada). Crie app/Config/NextPdf.php:

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

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

O CodeIgniter carrega a classe da aplicação em vez da classe padrão do pacote.

2. Sobrescreva com .env (por ambiente). Use o nome curto da classe em minúsculas, nextpdf, como prefixo:

nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem

/integrations/codeigniter/configuration/ documenta cada chave e a regra de sobrescrita de arrays.

Teste de fumaça de service-provider / bundle

O CodeIgniter não tem service provider nem classe de bundle para testar. Use o teste de fumaça equivalente para verificar duas coisas: se a descoberta resolveu os serviços e se os tempos de vida se comportam conforme especificado. A ação de controller abaixo é executável e espelha as próprias asserções funcionais do pacote.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\CodeIgniter\Libraries\Pdf;
use NextPDF\Core\Document;

final class NextPdfSmokeController extends BaseController
{
    public function check(): ResponseInterface
    {
        // Discovery resolved the services.
        $document = Services::pdfDocument(false);
        $library = Services::pdf(false);

        // Documents are fresh per call (no cross-request leakage).
        $freshIsolated = Services::pdfDocument(false) !== $document;

        // Registries are shared singletons.
        $registrySingleton = Services::fontRegistry() === Services::fontRegistry();

        // Optional services degrade to null without Premium / TSA config.
        $signerOptional = Services::pdfSigner(false) === null;

        $ok = $document instanceof Document
            && $library instanceof Pdf
            && $freshIsolated
            && $registrySingleton
            && $signerOptional;

        return $this->response
            ->setStatusCode($ok ? 200 : 500)
            ->setJSON([
                'discovery' => $document instanceof Document,
                'document_fresh_per_call' => $freshIsolated,
                'registry_shared' => $registrySingleton,
                'signer_optional_null' => $signerOptional,
            ]);
    }
}

Mapeie uma rota para esta ação e, em seguida, faça uma requisição para ela. Uma resposta 200 com todas as flags definidas como true comprova a integração. Cada asserção aqui corresponde a um comportamento verificado na suíte de testes funcionais do pacote.

Casos extremos e pegadinhas

• Se a aplicação host desativar a descoberta do Composer, adicione nextpdf/codeigniter a Config\Modules::$composerPackages['only'].
• Services::pdfDocument(true) retorna um documento compartilhado. Ele existe apenas para reinicialização em testes. Nunca solicite o documento compartilhado em código de requisição nem de job.
• Services::pdfSigner() e Services::tsaClient() retornam null até que a assinatura ou um endpoint de Time-Stamping Authority (TSA) seja configurado. Isso é uma degradação controlada intencional, não uma falha.

Conformidade

• Mapeamento de classe para caminho na descoberta de módulos (PSR-4 Autoloader §x1.x3).
• Orientação sobre service-locator para o modelo de vínculos (PSR-11 Container §1.3).

Contexto comercial

O core do NextPDF é Apache-2.0. Depois que você instala o Pro ou o Enterprise, os serviços correspondentes aparecem na mesma superfície Services. O pacote do CodeIgniter expõe os métodos de serviço correspondentes. Cada método retorna null até que você instale o pacote Premium correspondente. Consulte </get-license/?intent=codeigniter>.

Veja também

• /integrations/codeigniter/boot-and-discovery/ — detalhes internos da descoberta.
• /integrations/codeigniter/install/ — restrições de versão e verificação.
• /integrations/codeigniter/quickstart/ — primeiro PDF.
• /integrations/codeigniter/production-usage/ — controllers integrados via injeção de dependência e job de fila.
• /integrations/codeigniter/configuration/ — todas as chaves de configuração.