Integracja NextPDF z CodeIgniter

W skrócie

Zainstaluj pakiet, a CodeIgniter 4 podłączy go automatycznie. Ta strona pomaga potwierdzić poprawność połączenia: wykrywanie, model powiązań, publikowanie konfiguracji oraz test dymny z jedną metodą, który sprawdza działanie integracji.

Instalacja

composer require nextpdf/codeigniter

Nie musisz edytować dostawcy usług ani zmieniać pliku startowego. Zweryfikowane ograniczenia wersji opisuje strona /integrations/codeigniter/install/.

Rozruch / automatyczne wykrywanie

CodeIgniter 4 znajduje pakiet dzięki wykrywaniu pakietów Composera, gdy Config\Modules::$discoverInComposer ma wartość true, czyli domyślną wartość frameworka. Prefiks PHP Standard Recommendation 4 (PSR-4) NextPDF\CodeIgniter\ jest mapowany na src/CodeIgniter/, dzięki czemu framework może rozwiązać klasę NextPDF\CodeIgniter\Config\Services do odpowiadającego jej pliku (PSR-4 §x1.x3). Strona /integrations/codeigniter/boot-and-discovery/ dokumentuje pełną sekwencję oraz właściwości nadrzędne Config\Modules.

Powiązania kontenera

CodeIgniter 4 nie udostępnia kontenera PSR-11. PSR-11 §1.3 odradza wzorzec lokalizatora usług (modalne SHOULD NOT). Pakiet stosuje konwencję lokalizatora frameworka i ogranicza jej użycie do minimum. Każde powiązanie ma postać nazwanej statycznej fabryki z parametrem bool $getShared.

Nazwa usługi	Zwraca	Domyślny czas życia
fontRegistry	FontRegistryInterface	współdzielony
imageRegistry	ImageRegistry	współdzielony
documentFactory	DocumentFactoryInterface	współdzielony
pdfDocument	Document	nowy
pdf	Pdf	nowy
tsaClient	?TsaClient	współdzielony
pdfSigner	?SignerInterface	nowy

Możesz użyć dowolnego punktu wejścia; są równoważne:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

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

Globalne funkcje pomocnicze pdf() i pdf_document() są opakowaniami dla Services::pdf(false) oraz Services::pdfDocument(false).

Publikowanie konfiguracji

Konfiguracja pakietu znajduje się w klasie NextPDF\CodeIgniter\Config\NextPdf, czyli niefinalnej klasie opartej na BaseConfig. Możesz nadpisać ją na jeden z dwóch obsługiwanych sposobów:

1. Rozszerz klasę (z typowaniem i pod kontrolą wersji). Utwórz 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 ładuje Twoją klasę aplikacji zamiast domyślnej klasy pakietu.

2. Nadpisz przez .env (dla danego środowiska). Jako prefiksu użyj krótkiej nazwy klasy zapisanej małymi literami: nextpdf:

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

Na stronie /integrations/codeigniter/configuration/ opisano każdy klucz oraz regułę nadpisywania tablic.

Test dymny dostawcy usług / pakietu

CodeIgniter nie ma dostawcy usług ani klasy pakietu, które można by przetestować. Użyj równoważnego testu dymnego, aby sprawdzić dwie rzeczy: czy wykrywanie rozwiązało usługi oraz czy czasy życia zachowują się zgodnie ze specyfikacją. Poniższą akcję kontrolera można uruchomić i odpowiada ona asercjom funkcjonalnym samego pakietu.

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

Przypisz trasę do tej akcji, a następnie ją wywołaj. Odpowiedź 200 ze wszystkimi flagami ustawionymi na true potwierdza integrację. Każda asercja odpowiada tu zachowaniu zweryfikowanemu w zestawie testów funkcjonalnych pakietu.

Przypadki brzegowe i pułapki

• Jeśli aplikacja hosta wyłączy wykrywanie Composera, dodaj nextpdf/codeigniter do Config\Modules::$composerPackages['only'].
• Services::pdfDocument(true) zwraca współdzielony dokument. Służy wyłącznie do resetowania w testach. Nigdy nie pobieraj współdzielonego dokumentu w kodzie obsługującym żądanie ani w zadaniu.
• Services::pdfSigner() i Services::tsaClient() zwracają null, dopóki nie skonfigurujesz podpisywania lub punktu końcowego urzędu znakowania czasem (TSA). To celowa łagodna degradacja, a nie awaria.

Zgodność

• Mapowanie klasy na ścieżkę na potrzeby wykrywania modułów (PSR-4 Autoloader §x1.x3).
• Wytyczne dotyczące lokalizatora usług w modelu powiązań (PSR-11 Container §1.3).

Kontekst komercyjny

Rdzeń NextPDF jest objęty licencją Apache-2.0. Po zainstalowaniu Pro lub Enterprise jego usługi pojawiają się w tej samej warstwie Services. Pakiet CodeIgniter udostępnia odpowiadające im metody usług. Każda metoda zwraca null, dopóki nie zainstalujesz odpowiadającego jej pakietu Premium. Zobacz </get-license/?intent=codeigniter>.

Zobacz też

• /integrations/codeigniter/boot-and-discovery/ — wewnętrzne szczegóły wykrywania.
• /integrations/codeigniter/install/ — ograniczenia wersji i weryfikacja.
• /integrations/codeigniter/quickstart/ — pierwszy plik PDF.
• /integrations/codeigniter/production-usage/ — kontrolery podłączone przez wstrzykiwanie zależności i zadanie kolejki.
• /integrations/codeigniter/configuration/ — każdy klucz konfiguracji.