CodeIgniter-API-Referenz

Auf einen Blick

Das CodeIgniter-Paket stellt eine schlanke, auf Controller ausgerichtete Oberfläche bereit: einen Pdf-Library-Wrapper für ein Dokument (Services::pdf() und der globale pdf()-Helper), Response-Helper, die ein erstelltes Dokument in eine DownloadResponse umwandeln (PdfResponse), die zugrunde liegenden Services-Factories (Schriftart-/Bild-Registries, Dokument-Factory, optionaler Signierer und TSA-Client), die NextPdf-Konfigurationsklasse und einen GeneratePdfJob für die asynchrone Generierung aus statischen Builder-Callables.

Beginnen Sie hier: Rufen Sie in einem Controller Services::pdf() (oder den pdf()-Helper) auf, fügen Sie Inhalt zu $pdf->document() hinzu und geben Sie $pdf->download('file.pdf') zurück. Dieser eine Weg deckt die häufigste Aufgabe ab. Die Referenztabellen weiter unten sind nach Oberfläche gegliedert; der Abschnitt „Häufige Aufgaben“ zeigt zuerst die lauffähigen Formen.

Häufige Aufgaben

Dies sind die häufigsten Abläufe in der Praxis. Jedes Beispiel wurde anhand der Quellen von nextpdf/codeigniter geprüft.

Geben Sie aus einem Controller ein herunterladbares PDF zurück — der kanonische Render-Weg:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

Wirkung: Es löst einen frischen Pdf auf, der ein frisches Document umschließt, schreibt eine Zelle und gibt eine DownloadResponse mit attachment-Disposition und den Sicherheits-Headern des Pakets zurück.

Zeigen Sie ein PDF inline im Browser an — derselbe Wrapper, inline() statt download():

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

Wirkung: Es nutzt den globalen pdf()-Helper (äquivalent zu Services::pdf()) und gibt eine DownloadResponse mit inline-Disposition zurück, sodass der Browser das PDF anzeigt, statt es herunterzuladen.

Generieren Sie ein PDF asynchron in der Queue — schieben Sie GeneratePdfJob mit einem statischen Builder ein:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

Wirkung: Die Generierung wird eingereiht. Der Worker validiert den Builder (muss ein statisches Callable der Form App\PdfBuilders\...::method sein) und den Ausgabepfad (muss sich unter WRITEPATH/pdfs/ auflösen und auf .pdf enden), erstellt ein frisches Dokument und speichert es anschließend.

Library-Wrapper

Nutzen Sie diese Tabelle, wenn Sie einen Pdf-Wrapper verwenden und seine Response- oder Speichermethoden benötigen.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: frisches Core-Dokument.	Umschließt das übergebene Dokument für eine einzelne Response- oder Speicheroperation.	`Pdf`	Keine erwartet.	Verwenden Sie den Wrapper nach der Ausgabe nicht erneut.
`Pdf::document()`	keine.	Gibt das umschlossene Dokument zurück.	`NextPDF\Core\Document`	Keine erwartet.	Nutzen Sie dies, um Core-Authoring-APIs aufzurufen.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: Dateiname der Response.	Inline-Disposition im Browser.	`CodeIgniter\HTTP\DownloadResponse`	Core-Serialisierungsfehler.	Delegiert an `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: Dateiname der Response.	Attachment-Disposition im Browser.	`DownloadResponse`	Core-Serialisierungsfehler.	Delegiert an `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: Dateiname der Response.	API-Parität mit anderen Framework-Paketen.	`DownloadResponse`	Core-Serialisierungsfehler.	CodeIgniter verarbeitet Binärausgabe nativ.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: Dateiname der Response.	API-Parität mit anderen Framework-Paketen.	`DownloadResponse`	Core-Serialisierungsfehler.	Verwende dieselben Größensteuerungen wie bei nicht gestreamten Responses.
`Pdf::save(string $path)`	`path`: Ziel im Dateisystem.	Schreibt das umschlossene Dokument.	`void`	Dateisystem- oder Core-Schreibfehler.	Validieren Sie die Storage-Roots vor dem Speichern.

Services und Helper

Nutzen Sie diese Tabelle, wenn Sie eine bestimmte Service-Factory oder eine der globalen Helper-Funktionen benötigen und deren Sharing-Verhalten sowie Rückgabetyp kennen möchten.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`Services::fontRegistry(bool $getShared = true)`	`getShared`: CodeIgniter-Flag für gemeinsam genutzte Services.	Gemeinsam genutzte Registry, die mit den konfigurierten Schriftarten vorgewärmt und anschließend gesperrt wird.	`FontRegistryInterface`	`RuntimeException` bei fehlenden Extensions oder unsicherem Schriftartenpfad.	Lehnt Stream-Wrapper und Null-Bytes in `fontsPath` ab.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: Flag für gemeinsam genutzte Services.	Gemeinsam genutzte LRU-Bild-Registry mit Größenbeschränkung.	`ImageRegistry`	Keine erwartet.	Die Cachegröße wird über `imageCacheMb` gesteuert.
`Services::documentFactory(bool $getShared = true)`	`getShared`: Flag für gemeinsam genutzte Services.	Gemeinsam genutzte Factory, die gemeinsam genutzte Registries verwendet.	`DocumentFactoryInterface`	Fehler bei der Registry-Einrichtung.	Die Factory ist wiederverwendbar; Dokumente sind es nicht.
`Services::tsaClient(bool $getShared = true)`	`getShared`: Flag für gemeinsam genutzte Services.	Gibt `null` zurück, wenn `tsa.url` leer ist.	`TsaClient	null`	HTTP-Client- oder TSA-Konfigurationsfehler.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: Flag für gemeinsam genutzte Services.	Gibt `null` zurück, wenn das Signieren deaktiviert ist.	`SignerInterface	null`	Zertifikats- oder Signatur-Fehler.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: Flag für gemeinsam genutzte Services.	Erstellt ein frisches Dokument, wendet Standardwerte an und konfiguriert optional PDF/A oder Artisan.	`Document`	Optionale Erweiterungs- oder Dokumentkonfigurationsfehler.	Behalten Sie für die Sicherheit pro Request den Standard `false` bei.
`Services::pdf(bool $getShared = false)`	`getShared`: Flag für gemeinsam genutzte Services.	Erstellt einen frischen `Pdf`-Wrapper um ein frisches Dokument.	`NextPDF\CodeIgniter\Libraries\Pdf`	Fehler bei der Dokument-Einrichtung.	Wichtigster an Controller gerichteter Service.
`Services::eInvoiceEmbedder()`	keine.	Gibt `null` zurück, sofern die Premium-Pro-E-Invoice-Embedder-Klasse nicht existiert.	`EmbedderInterface	null`	Fehler beim Erstellen optionaler Pakete.
`Services::eInvoiceValidator()`	keine.	Gibt `null` zurück, sofern die Premium-Enterprise-Validator-Klasse nicht existiert.	`ValidatorInterface	null`	Fehler beim Erstellen optionaler Pakete.
`Services::eInvoiceProfile()`	keine.	Gibt das EN16931-Profil zurück, wenn Premium Pro installiert ist.	`ProfileInterface	null`	Fehler bei optionalen Paketen.
`Services::schematronRunner()`	keine.	Gibt `null` zurück, sofern der Premium-Enterprise-Schematron-Validator nicht existiert.	`SchematronRunnerInterface	null`	Fehler beim Erstellen optionaler Pakete.
`Registrar::Autoload()`	keine.	Fügt den Paket-Helper zur Autoload-Konfiguration von CodeIgniter hinzu.	`array`	Keine erwartet.	Aktiviert `pdf()` und `pdf_document()`, wenn das Modul geladen ist.
`pdf()`	keine.	Ruft `Services::pdf(false)` auf.	`Pdf`	Fehler bei der Dokument-Einrichtung.	Komfort-Helper für Controller.
`pdf_document()`	keine.	Ruft `Services::pdfDocument(false)` auf.	`Document`	Fehler bei der Dokument-Einrichtung.	Komfort-Helper, wenn die Core-Dokument-API bevorzugt wird.

HTTP-Responses

Nutzen Sie diese Tabelle, wenn Ihnen bereits ein erstelltes Document vorliegt und Sie die DownloadResponse selbst konstruieren möchten, statt über den Pdf-Wrapper zu gehen.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: erstelltes Dokument; `filename`: Dateiname der Response.	Stellt die `.pdf`-Erweiterung und Inline-Disposition sicher.	`DownloadResponse`	Core-Serialisierungsfehler.	Fügt PDF-Content-Type und defensive Header hinzu.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Wie `inline`; die Disposition lautet attachment.	Stellt die `.pdf`-Erweiterung sicher.	`DownloadResponse`	Wie `inline`.	Verwenden Sie dies für Browser-Downloads.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Wie `inline`.	Gleiches Verhalten wie `inline` in CI4.	`DownloadResponse`	Wie `inline`.	Dient der Framework-übergreifenden API-Parität.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Wie `download`.	Gleiches Verhalten wie `download` in CI4.	`DownloadResponse`	Wie `download`.	Dient der Framework-übergreifenden API-Parität.

Queue-Job

Nutzen Sie diese Tabelle, wenn Sie die asynchrone Generierung einrichten und die genauen Job-Daten-Schlüssel sowie den Vertrag für Builder-Callables benötigen.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`GeneratePdfJob::process()`	Job-Daten-Schlüssel: `builder`, `outputPath`, optional `context`.	Verwendet ein leeres Context-Array, wenn es weggelassen wird.	`void`	`InvalidArgumentException` bei unsicherem Builder oder Ausgabepfad; Core-Schreibfehler.	Der Builder muss `App\PdfBuilders\...\*::method` sein.
Builder-Callable	`Document $doc`, `array $context`.	Kein Standard-Context über die Job-Daten hinaus.	`Document`	Builder-spezifische Exceptions.	Ein statisches Callable ist erforderlich, weil CI4-Queue-Payloads serialisierte Daten sind.

Konfiguration

Nutzen Sie diese Tabelle, wenn Sie Standardwerte auf der NextPdf-Konfigurationsklasse ändern: Seitenformat, Pfade, Signieren, TSA oder Dokument-Metadaten.

Eigenschaft	Typ	Standardverhalten	Hinweise
`pageFormat`	`string`	`A4`.	Standardseitenformat.
`orientation`	`string`	`P`.	Standardausrichtung.
`unit`	`string`	`mm`.	Standardeinheit.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` und `WRITEPATH . 'cache/nextpdf'`.	Belassen Sie die Pfade innerhalb des von der Anwendung kontrollierten Storage.
`signature`	`array`	Deaktiviert mit Level `B-B`.	Zertifikat, Schlüssel, Passwort, zusätzliche Zertifikate und Level.
`tsa`	`array`	Deaktiviert, wenn die URL `null` ist; Timeout 30 Sekunden.	Anmeldedaten, mTLS-Dateien, Public-Key-Pins und HTTP-Policy.
`ocspCache`	`array`	Aktiviert mit einer TTL von 86400 Sekunden.	Wird bei Signaturvalidierungs-Abläufen verwendet, sofern verfügbar.
`preloadFonts`	`list<string>`	Leer.	Vorgewärmt, bevor die Registry gesperrt wird.
`imageCacheMb`	`int`	`50`.	Steuert den Bild-Cache während der Prozesslaufzeit.
`fontCacheLocking`	`bool`	`true`.	Hält Mutationen der Schriftart-Registry aus dem Request-Handling heraus.
`artisan`	`array`	Chrome-Renderer ist deaktiviert, sofern er nicht konfiguriert und installiert ist.	Wird auf `ChromeRendererConfig::fromArray()` abgebildet.
`defaults`	`array`	Creator `NextPDF`, Author leer, Sprache `en`, Standardränder und Standardschriftart.	`Services::pdfDocument()` wendet nur `creator`, `language` und (wenn nicht leer) `author` an; die Schlüssel `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` und `bleed_box` sind definierte Standardwerte, werden derzeit aber nicht angewendet.

Entwicklungshinweise

GeneratePdfJob beschränkt die Ausgabe auf WRITEPATH . 'pdfs' und erfordert .pdf.
Builder-Callables außerhalb von App\PdfBuilders werden abgelehnt, um beliebige Codeausführung aus manipulierten Queue-Payloads zu verhindern.
Verwenden Sie service('pdf') oder den Paket-Helper für Controller-Abläufe; verwenden Sie Queue-Jobs für lang laufende Generierung.