Integración de NextPDF con CodeIgniter

De un vistazo

Al instalar el paquete, CodeIgniter 4 lo conecta automáticamente. Esta página sirve como referencia de conexión: cubre el descubrimiento, el modelo de vinculaciones, la publicación de la configuración y una prueba de humo de un solo método que demuestra que la integración funciona.

Instalación

composer require nextpdf/codeigniter

No es necesario editar un proveedor de servicios ni cambiar un archivo de arranque. Consultar /integrations/codeigniter/install/ para conocer las restricciones de versión verificadas.

Arranque / descubrimiento automático

CodeIgniter 4 encuentra el paquete mediante el descubrimiento de paquetes de Composer. Esto ocurre cuando Config\Modules::$discoverInComposer es true, que es el valor predeterminado del framework. El prefijo PSR-4 NextPDF\CodeIgniter\ se asigna a src/CodeIgniter/. Mediante esa asignación, el framework resuelve NextPDF\CodeIgniter\Config\Services en su archivo (PSR-4 §x1.x3). /integrations/codeigniter/boot-and-discovery/ documenta la secuencia completa y las propiedades de Config\Modules que la rigen.

Vinculaciones del contenedor

CodeIgniter 4 no incluye ningún contenedor PSR-11. PSR-11 §1.3 desaconseja el patrón de localizador de servicios (modal SHOULD NOT). El paquete sigue la convención de localizador de servicios del framework, pero la restringe al mínimo. Cada vinculación es una fábrica estática con nombre y acepta un parámetro bool $getShared.

Nombre del servicio	Devuelve	Tiempo de vida predeterminado
`fontRegistry`	`FontRegistryInterface`	compartido
`imageRegistry`	`ImageRegistry`	compartido
`documentFactory`	`DocumentFactoryInterface`	compartido
`pdfDocument`	`Document`	nuevo
`pdf`	`Pdf`	nuevo
`tsaClient`	`?TsaClient`	compartido
`pdfSigner`	`?SignerInterface`	nuevo

Se puede resolver mediante cualquiera de estos dos puntos de entrada; son equivalentes:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

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

Los ayudantes globales pdf() y pdf_document() son envoltorios ligeros que delegan en Services::pdf(false) y Services::pdfDocument(false).

Publicar la configuración

La configuración del paquete reside en NextPDF\CodeIgniter\Config\NextPdf, un BaseConfig no final. Hay dos formas admitidas de sobrescribirla:

1. Extender la clase (tipada, controlada por versiones). Crear 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;
}

CodeIgniter carga la clase de aplicación en lugar del valor predeterminado del paquete.

2. Sobrescribir con .env (por entorno). El prefijo es el nombre corto de la clase en minúsculas, nextpdf:

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

/integrations/codeigniter/configuration/ documenta cada clave y la regla de sobrescritura de arreglos.

Prueba de humo del proveedor de servicios / paquete

CodeIgniter no tiene una clase de proveedor de servicios ni una clase de paquete que probar. En su lugar, la prueba de humo equivalente comprueba dos aspectos: que el descubrimiento resuelve los servicios y que los tiempos de vida se comportan según lo especificado. La siguiente prueba es una acción de controlador ejecutable que refleja las aserciones funcionales del propio paquete.

<?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,
            ]);
    }
}

Asignar una ruta a esta acción y solicitarla. Una respuesta 200 con todas las banderas establecidas en true demuestra que la integración funciona. Cada aserción de esta prueba corresponde a un comportamiento verificado en el conjunto de pruebas funcionales del paquete.

Casos límite y trampas

Si la aplicación anfitriona desactiva el descubrimiento de Composer, hay que agregar nextpdf/codeigniter a Config\Modules::$composerPackages['only'].
Services::pdfDocument(true) devuelve un documento compartido. Existe únicamente para reiniciar pruebas. Nunca solicitar el documento compartido en código de solicitud o de trabajo.
Services::pdfSigner() y Services::tsaClient() devuelven null hasta que se configure la firma o una URL TSA. Es una degradación elegante intencionada, no un fallo.

Conformidad

Asignación de clase a ruta para el descubrimiento de módulos (autocargador PSR-4 §x1.x3).
Orientación sobre el localizador de servicios para el modelo de vinculaciones (contenedor PSR-11 §1.3).

Contexto comercial

El núcleo de NextPDF es Apache-2.0. Los servicios Pro y Enterprise aparecen en la misma superficie de Services una vez instalados. El paquete de CodeIgniter expone los métodos de servicio correspondientes. Cada uno devuelve null hasta que se instala el paquete Premium correspondiente. Consultar </get-license/?intent=codeigniter>.

Consulta también

/integrations/codeigniter/boot-and-discovery/ — detalles internos del descubrimiento.
/integrations/codeigniter/install/ — restricciones de versión y verificación.
/integrations/codeigniter/quickstart/ — primer PDF.
/integrations/codeigniter/production-usage/ — controladores conectados con DI y trabajos en cola.
/integrations/codeigniter/configuration/ — cada clave de configuración.