Dokumentacja API CodeIgniter

W skrócie

Pakiet CodeIgniter udostępnia niewielkie API przeznaczone do użycia w kontrolerach. Obejmuje bibliotekę opakowującą Pdf dla pojedynczego dokumentu (Services::pdf() oraz globalny pomocnik pdf()), pomocniki odpowiedzi, które przekształcają zbudowany dokument w obiekt DownloadResponse (PdfResponse), stojące za nimi fabryki Services (rejestry czcionek i obrazów, fabrykę dokumentów oraz opcjonalny moduł podpisujący i klienta urzędu znaczników czasu (TSA)), klasę konfiguracji NextPdf oraz GeneratePdfJob, który generuje dokumenty asynchronicznie za pomocą statycznych wywołań budujących.

Zacznij od głównej ścieżki w kontrolerze: wywołaj Services::pdf() (lub pomocnik pdf()), dodaj treść do $pdf->document() i zwróć $pdf->download('file.pdf'). Ta ścieżka obejmuje najczęstszy przypadek. Tabele referencyjne są uporządkowane według obszarów API; sekcja Typowe zadania najpierw pokazuje przykłady gotowe do uruchomienia.

Typowe zadania

Poniżej znajdują się najczęstsze przepływy produkcyjne. Każdy przykład został zweryfikowany na podstawie kodu źródłowego pakietu nextpdf/codeigniter.

Użyj kanonicznej ścieżki renderowania, aby kontroler zwrócił plik w formacie Portable Document Format (PDF) do pobrania:

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

Co robi: tworzy nowy obiekt Pdf wokół nowego obiektu Document, zapisuje jedną komórkę i zwraca obiekt DownloadResponse z trybem disposition ustawionym na attachment oraz nagłówkami bezpieczeństwa pakietu.

Pokaż podgląd pliku PDF w przeglądarce za pomocą tego samego opakowania i metody inline() zamiast 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');
    }
}

Co robi: używa globalnego pomocnika pdf() (odpowiednika Services::pdf()) i zwraca obiekt DownloadResponse z trybem disposition ustawionym na inline, dzięki czemu przeglądarka wyświetla plik PDF zamiast go pobierać.

Wygeneruj plik PDF asynchronicznie w kolejce za pomocą GeneratePdfJob i statycznego budowniczego:

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

Co robi: dodaje generowanie do kolejki. Proces roboczy weryfikuje budowniczego (musi mieć postać statycznego wywołania App\PdfBuilders\...::method) oraz ścieżkę wyjściową (musi wskazywać lokalizację w WRITEPATH/pdfs/ i kończyć się rozszerzeniem .pdf), buduje nowy dokument i zapisuje go.

Biblioteka opakowująca

Użyj tej tabeli, gdy masz opakowanie Pdf i potrzebujesz jego metod odpowiedzi albo zapisu.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
NextPDF\CodeIgniter\Libraries\Pdf / new Pdf(Document $document)	document: nowy dokument rdzenia.	Opakowuje przekazany dokument na potrzeby jednej operacji odpowiedzi lub zapisu.	Pdf	Nie powinny wystąpić.	Nie używaj opakowania ponownie po wygenerowaniu wyniku.
Pdf::document()	brak.	Zwraca opakowany dokument.	NextPDF\Core\Document	Nie powinny wystąpić.	Używaj tej metody do wywoływania API rdzenia i tworzenia treści.
Pdf::inline(string $filename = 'document.pdf')	filename: nazwa pliku w odpowiedzi.	Używa trybu inline w przeglądarce.	CodeIgniter\HTTP\DownloadResponse	Błędy serializacji w rdzeniu.	Deleguje do PdfResponse::inline().
Pdf::download(string $filename = 'document.pdf')	filename: nazwa pliku w odpowiedzi.	Używa trybu attachment w przeglądarce.	DownloadResponse	Błędy serializacji w rdzeniu.	Deleguje do PdfResponse::download().
Pdf::streamInline(string $filename = 'document.pdf')	filename: nazwa pliku w odpowiedzi.	Zapewnia zgodność API z pakietami dla innych frameworków.	DownloadResponse	Błędy serializacji w rdzeniu.	CodeIgniter natywnie obsługuje wyjście binarne.
Pdf::streamDownload(string $filename = 'document.pdf')	filename: nazwa pliku w odpowiedzi.	Zapewnia zgodność API z pakietami dla innych frameworków.	DownloadResponse	Błędy serializacji w rdzeniu.	Stosuj te same mechanizmy kontroli rozmiaru co w odpowiedziach niestrumieniowanych.
Pdf::save(string $path)	path: docelowa lokalizacja w systemie plików.	Zapisuje opakowany dokument.	void	Błędy zapisu w systemie plików lub w rdzeniu.	Przed zapisem zweryfikuj katalogi bazowe magazynu.

Usługi i pomocnicy

Użyj tej tabeli, gdy potrzebujesz konkretnej fabryki usług lub globalnego pomocnika wraz z informacją o współdzieleniu i typie zwracanym.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
Services::fontRegistry(bool $getShared = true)	getShared: flaga współdzielonej usługi CodeIgniter.	Zwraca współdzielony rejestr, wstępnie ładuje skonfigurowane czcionki, a następnie go blokuje.	FontRegistryInterface	RuntimeException w przypadku brakujących rozszerzeń lub niebezpiecznej ścieżki czcionek.	Odrzuca opakowania strumieni oraz bajty null w fontsPath.
Services::imageRegistry(bool $getShared = true)	getShared: flaga współdzielonej usługi.	Zwraca współdzielony, ograniczony rejestr obrazów typu least recently used (LRU).	ImageRegistry	Nie powinny wystąpić.	Rozmiar pamięci podręcznej kontroluje imageCacheMb.
Services::documentFactory(bool $getShared = true)	getShared: flaga współdzielonej usługi.	Zwraca współdzieloną fabrykę korzystającą ze współdzielonych rejestrów.	DocumentFactoryInterface	Błędy konfiguracji rejestrów.	Fabryka nadaje się do wielokrotnego użycia; dokumenty nie.
Services::tsaClient(bool $getShared = true)	getShared: flaga współdzielonej usługi.	Zwraca null, gdy tsa.url jest puste.	`TsaClient	null`	Błędy klienta Hypertext Transfer Protocol (HTTP) lub konfiguracji TSA.
Services::pdfSigner(bool $getShared = false)	getShared: flaga współdzielonej usługi.	Zwraca null, gdy podpisywanie jest wyłączone.	`SignerInterface	null`	Błędy na poziomie certyfikatu lub podpisu.
Services::pdfDocument(bool $getShared = false)	getShared: flaga współdzielonej usługi.	Tworzy nowy dokument, stosuje ustawienia domyślne i opcjonalnie konfiguruje PDF/A lub Artisan.	Document	Błędy opcjonalnego rozszerzenia lub konfiguracji dokumentu.	Ze względu na bezpieczeństwo żądań pozostaw wartość domyślną false.
Services::pdf(bool $getShared = false)	getShared: flaga współdzielonej usługi.	Tworzy nowe opakowanie Pdf wokół nowego dokumentu.	NextPDF\CodeIgniter\Libraries\Pdf	Błędy konfiguracji dokumentu.	Główna usługa przeznaczona dla kontrolerów.
Services::eInvoiceEmbedder()	brak.	Zwraca null, chyba że istnieje klasa osadzająca e-faktury z pakietu Premium Pro.	`EmbedderInterface	null`	Błędy konstrukcji opcjonalnego pakietu.
Services::eInvoiceValidator()	brak.	Zwraca null, chyba że istnieje klasa walidatora z pakietu Premium Enterprise.	`ValidatorInterface	null`	Błędy konstrukcji opcjonalnego pakietu.
Services::eInvoiceProfile()	brak.	Zwraca profil EN16931, gdy zainstalowany jest pakiet Premium Pro.	`ProfileInterface	null`	Błędy opcjonalnego pakietu.
Services::schematronRunner()	brak.	Zwraca null, chyba że istnieje walidator Schematron z pakietu Premium Enterprise.	`SchematronRunnerInterface	null`	Błędy konstrukcji opcjonalnego pakietu.
Registrar::Autoload()	brak.	Dodaje pomocnik pakietu do konfiguracji automatycznego ładowania CodeIgniter.	array	Nie powinny wystąpić.	Włącza pdf() oraz pdf_document() po załadowaniu modułu.
pdf()	brak.	Wywołuje Services::pdf(false).	Pdf	Błędy konfiguracji dokumentu.	Wygodny pomocnik dla kontrolerów.
pdf_document()	brak.	Wywołuje Services::pdfDocument(false).	Document	Błędy konfiguracji dokumentu.	Wygodny pomocnik, gdy preferowane jest API dokumentu rdzenia.

Odpowiedzi HTTP

Użyj tej tabeli, gdy masz już zbudowany obiekt Document i chcesz samodzielnie utworzyć obiekt DownloadResponse zamiast korzystać z opakowania Pdf.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: zbudowany dokument; filename: nazwa pliku w odpowiedzi.	Zapewnia rozszerzenie .pdf oraz tryb inline.	DownloadResponse	Błędy serializacji w rdzeniu.	Dodaje typ zawartości PDF oraz nagłówki ochronne.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Tak samo jak inline; tryb disposition ma wartość attachment.	Zapewnia rozszerzenie .pdf.	DownloadResponse	Tak samo jak inline.	Używaj do pobierania pliku w przeglądarce.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Tak samo jak inline.	Zachowuje się tak samo jak inline w CodeIgniter 4 (CI4).	DownloadResponse	Tak samo jak inline.	Istnieje dla zgodności API między frameworkami.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Tak samo jak download.	Zachowuje się tak samo jak download w CI4.	DownloadResponse	Tak samo jak download.	Istnieje dla zgodności API między frameworkami.

Zadanie kolejkowe

Użyj tej tabeli, gdy konfigurujesz asynchroniczne generowanie i potrzebujesz dokładnych kluczy danych zadania oraz kontraktu dla wywołania budującego.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
GeneratePdfJob::process()	Klucze danych zadania: builder, outputPath oraz opcjonalny context.	Po pominięciu kontekstu używa pustej tablicy kontekstu.	void	InvalidArgumentException w przypadku niebezpiecznego budowniczego lub ścieżki wyjściowej; błędy zapisu w rdzeniu.	Budowniczy musi mieć postać App\PdfBuilders\...\*::method.
Wywołanie budujące	Document $doc, array $context.	Brak domyślnego kontekstu poza danymi zadania.	Document	Wyjątki specyficzne dla budowniczego.	Wymaga statycznego wywołania, ponieważ ładunki kolejki w CI4 są serializowanymi danymi.

Konfiguracja

Użyj tej tabeli, gdy zmieniasz domyślne ustawienia formatu strony, ścieżek, podpisywania, TSA lub metadanych dokumentu w klasie konfiguracji NextPdf.

Właściwość	Typ	Zachowanie domyślne	Uwagi
pageFormat	string	A4.	Ustawia domyślny format strony.
orientation	string	P.	Ustawia domyślną orientację.
unit	string	mm.	Ustawia domyślną jednostkę.
pdfa	`string	null`	null.
fontsPath / cachePath	string	WRITEPATH . 'fonts' oraz WRITEPATH . 'cache/nextpdf'.	Utrzymuj ścieżki w magazynie kontrolowanym przez aplikację.
signature	array	Wyłączone z poziomem B-B.	Certyfikat, klucz, hasło, dodatkowe certyfikaty oraz poziom.
tsa	array	Wyłączone, gdy adres Uniform Resource Locator (URL) ma wartość null; limit czasu 30 sekund.	Poświadczenia, pliki wzajemnego Transport Layer Security (mTLS), przypięcia kluczy publicznych oraz polityka HTTP.
ocspCache	array	Włączone z czasem życia (TTL) wynoszącym 86400 sekund.	Używane przez przepływy weryfikacji podpisu, gdy są dostępne.
preloadFonts	list<string>	Pusta.	Wstępnie ładowane przed zablokowaniem rejestru.
imageCacheMb	int	50.	Kontroluje pamięć podręczną obrazów przez czas życia procesu.
fontCacheLocking	bool	true.	Nie dopuszcza zmian rejestru czcionek podczas obsługi żądań.
artisan	array	Mechanizm renderujący Chrome jest wyłączony, dopóki nie zostanie skonfigurowany i zainstalowany.	Mapuje na ChromeRendererConfig::fromArray().
defaults	array	Twórca NextPDF, pusty autor, język en, domyślne marginesy oraz domyślna czcionka.	Services::pdfDocument() stosuje tylko creator, language oraz (gdy niepuste) author; margin_top/right/bottom/left, font_family, font_size, trim_box oraz bleed_box są zdefiniowanymi wartościami domyślnymi, ale obecnie nie są stosowane.

Uwagi dla deweloperów

• GeneratePdfJob ogranicza wyjście do WRITEPATH . 'pdfs' i wymaga .pdf.
• Wywołania budujące spoza App\PdfBuilders są odrzucane, aby zapobiec wykonaniu dowolnego kodu ze zmodyfikowanych ładunków kolejki.
• W przepływach kontrolerów używaj service('pdf') lub pomocnika pakietu; do długotrwałego generowania używaj zadań kolejkowych.