CodeIgniter-Entwicklerleitfaden

Auf einen Blick

Das CodeIgniter-Paket stellt Service-Factories, Hilfsfunktionen und einen schlanken Pdf-Bibliothekswrapper für ein Dokument bereit. Der Wrapper eignet sich für Controller. Queue-Aufgaben verwenden statische Builder-Callables, weil CodeIgniter-Queue-Payloads serialisierte Daten sind.

Verwenden Sie diesen Leitfaden, wenn Sie Controller-Abläufe, Services, Queue-Builder oder Tests rund um nextpdf/codeigniter entwerfen.

Architekturgrenze

Schicht	Verantwortlich	Zuständigkeit	Gehört nicht hierher
Controller	Anwendung	Autorisiert, ruft einen Builder oder Service auf und gibt eine `DownloadResponse` zurück.	Gemeinsame Layout-Logik.
Bibliothekswrapper	`nextpdf/codeigniter`	Kapselt ein `Document` und stellt response/save-Hilfsmethoden bereit.	Langlebige Dokumentenspeicherung.
Service-Factory	`nextpdf/codeigniter`	Erstellt gemeinsame Registries und frische Dokumente.	Geschäftsspezifische Speicher-Roots.
Queue-Builder	Anwendung	Baut ein Dokument aus statischer Callable-Eingabe.	Request-Objekte oder nicht serialisierbarer Zustand.
Kern-Engine	`nextpdf/nextpdf`	Erstellt und serialisiert das PDF.	CodeIgniter-Response oder Queue-Policy.

Laufzeit-Lebenszyklus

Phase	Verhalten	Entwickleraktion
Autoload-Registrierung	`Registrar::Autoload()` registriert das Laden der Helper für das Modul.	Laden Sie das Modul über die CodeIgniter-Konfiguration.
Service-Auflösung	`Services::pdf()` liefert standardmäßig einen Wrapper um ein frisches Dokument.	Lösen Sie den Service einmal pro Request auf.
Erstellung	Anwendungscode verwendet `Pdf::document()` für die Kern-Dokumentaufrufe.	Halten Sie dokumentbauenden Code in Services oder Buildern.
Response	`PdfResponse` liefert eine `DownloadResponse`.	Lassen Sie das Paket die PDF-Header setzen.
Queue-Ausführung	`GeneratePdfJob::process()` validiert Builder und Ausgabepfad und speichert anschließend.	Legen Sie Queue-Builder unter `App\PdfBuilders` ab.

Empfohlene Anwendungsstruktur

Pfad	Zweck
`app/PdfBuilders/*`	Statische, queue-sichere Builder, die `GeneratePdfJob` akzeptiert.
`app/Libraries/*`	Optionale Anwendungswrapper um wiederkehrende Dokument-Workflows.
`app/Services/*`	Abruf von Domänendaten und Speicher-Policy.
`app/Config/NextPdf.php`	Anwendungsseitige Überschreibungen für die Paketkonfiguration.
`tests/app/PdfBuilders/*`	Tests für Builder und Queue-Payloads.

Verwenden Sie die Paket-Helper für kurze Abläufe. Verwenden Sie explizite Service-Aufrufe, wenn der Dokumentaufbau zu einer Klasse gehört, die direkt getestet werden soll.

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

Queue-Builder-Muster

Queue-Builder sollten statisch und deterministisch sein und unter App\PdfBuilders liegen. Halten Sie das Context-Array so einfach, dass es sich serialisieren und prüfen lässt.

<?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;
    }
}

Der Job beschränkt die Ausgabe auf das konfigurierte PDF-Verzeichnis der Anwendung. Wenn Ihre Anwendung mandantenspezifische Speicherung benötigt, legen Sie diese Policy in einen Service und testen Sie sie vor dem Queue-Dispatch.

Erweiterungspunkte

Erweiterungspunkt	Einsatzgebiet	Einschränkung
`Services::pdfDocument()`	Anpassung der Dokumenterstellung.	Muss ein frisches Dokument zurückgeben.
`Services::fontRegistry()`	Font-Warmup und Registry-Zugriff.	Unsichere Pfade abweisen und die Registry nach dem Warmup gesperrt halten.
`Services::pdfSigner()`	Optionales digitales Signieren.	Liefert `null`, wenn das Signieren deaktiviert ist.
`NextPDF\CodeIgniter\Libraries\Pdf`	Controller-orientierter Wrapper.	Ein Wrapper bildet ein Dokument ab.
`App\PdfBuilders::*`	Queue-sichere Dokument-Builder.	Statischer Callable-String erforderlich.
`app/Config/NextPdf.php`	Anwendungsstandards und Integrationseinstellungen.	Produktionswerte explizit halten.

Entwicklungs-Workflow

Beginnen Sie mit einem Controller, der pdf() oder service('pdf') aufruft.
Verschieben Sie wiederkehrenden Dokumentaufbau nach app/PdfBuilders oder in einen Anwendungsservice.
Verwenden Sie GeneratePdfJob, wenn die Generierung für den Request-Pfad zu langsam ist.
Halten Sie den Queue-Context serialisierbar und klein.
Speichern Sie die Ausgabe unter dem freigegebenen PDF-Speicher-Root, sofern Sie die Policy nicht bewusst erweitern.
Ergänzen Sie Tests für Helper, Services, Queue-Payloads und unsichere Pfade.

Fehlerbehandlung

Fehler	Wo er behandelt werden sollte	Empfohlene Reaktion
Fehlende Extension oder unsicherer Font-Pfad	Service-Factory.	Bereits während der Service-Auflösung fehlschlagen.
Ungültiges Builder-Callable	Validierung des Queue-Jobs.	Den Job abweisen und den Builder-String ohne Secrets loggen.
Unsicherer Ausgabepfad	Speicher-Service und Queue-Job.	Vor dem Dispatch abweisen und die Job-Validierung beibehalten.
Fehler bei der Response-Serialisierung	Fehlerbehandlung im Controller oder Framework.	Keinen unvollständigen Response-Body senden.
Optionale Premium-Klasse nicht verfügbar	Rückgabewert der Service-Methode.	`null` explizit behandeln, bevor optionale E-Invoice-Funktionen genutzt werden.

Sichere Standardwerte

Aspekt	Standard	Wann überschreiben
Queue-Builder-Namespace	`App\PdfBuilders`.	Behalten Sie den Standard bei, sofern Sie nicht auch die Sicherheits-Policy aktualisieren.
Ausgabe-Root	`WRITEPATH/pdfs`.	Nur mit einer strengeren Allowlist überschreiben.
Response-Dateiname	`document.pdf`.	Verwenden Sie bereinigte fachliche Dateinamen.
Stream-Methoden	API-Parität mit anderen Frameworks.	Verlassen Sie sich in CodeIgniter nicht auf Streaming als Speichergrenze.
Dokument-Service	Standardmäßig ein frisches Dokument.	Fordern Sie im Request-Code keine geteilten Dokumente an.

Test-Checkliste

Service-Tests prüfen, dass jede Services::pdf()-Auflösung ein unabhängiges Dokument zurückgibt.
Helper-Tests prüfen, dass pdf() und pdf_document() frische Objekte zurückgeben.
Response-Tests prüfen die Header und die Normalisierung des Dateinamens.
Queue-Tests decken ungültige Builder-Strings und unsichere Ausgabepfade ab.
Builder-Tests verwenden repräsentative Context-Daten.
Config-Tests decken Font-Pfad, Cache-Pfad, deaktiviertes Signieren und deaktivierte TSA-Zustände ab.