Przewodnik dewelopera CodeIgniter

W skrócie

Pakiet CodeIgniter udostępnia fabryki usług, funkcje pomocnicze oraz niewielki komponent biblioteki Pdf, który opakowuje pojedynczy dokument w formacie Portable Document Format (PDF). Używaj komponentu opakowującego w kontrolerach. Przetwarzanie w kolejce korzysta ze statycznych konstruktorów typu callable, ponieważ ładunki kolejki CodeIgniter muszą być zserializowanymi danymi.

Skorzystaj z tego przewodnika przy projektowaniu przepływów kontrolerów, usług, konstruktorów kolejki oraz testów wokół pakietu nextpdf/codeigniter.

Granica architektury

Warstwa	Właściciel	Odpowiedzialność	Czego tu nie umieszczać
Kontroler	Aplikacja	Autoryzuje, wywołuje konstruktor lub usługę i zwraca obiekt DownloadResponse.	Współdzielonej logiki układu.
Komponent opakowujący bibliotekę	nextpdf/codeigniter	Opakowuje pojedynczy obiekt Document i udostępnia funkcje pomocnicze odpowiedzi oraz zapisu.	Długotrwałego przechowywania dokumentów.
Fabryka usług	nextpdf/codeigniter	Tworzy współdzielone rejestry i nowe dokumenty.	Katalogów głównych przechowywania specyficznych dla biznesu.
Konstruktor kolejki	Aplikacja	Buduje dokument na podstawie statycznego wejścia typu callable.	Obiektów żądania ani stanu, których nie można zserializować.
Główny silnik	nextpdf/nextpdf	Buduje i serializuje plik PDF.	Zasad dotyczących odpowiedzi lub kolejki CodeIgniter.

Cykl życia w czasie wykonywania

Etap	Zachowanie	Działanie dewelopera
Rejestracja automatycznego ładowania	Registrar::Autoload() rejestruje ładowanie funkcji pomocniczych dla modułu.	Załaduj moduł w konfiguracji CodeIgniter.
Rozwiązywanie usług	Services::pdf() domyślnie zwraca komponent opakowujący wokół nowego dokumentu.	Rozwiązuj usługę raz na żądanie.
Tworzenie	Kod aplikacji używa Pdf::document() do podstawowych wywołań dokumentu.	Umieszczaj kod budowania dokumentów w usługach lub konstruktorach.
Odpowiedź	PdfResponse zwraca obiekt DownloadResponse.	Pozwól pakietowi ustawić nagłówki PDF.
Wykonywanie kolejki	GeneratePdfJob::process() weryfikuje konstruktor i ścieżkę wyjściową, a następnie zapisuje plik.	Umieszczaj konstruktory kolejki w App\PdfBuilders.

Zalecana struktura aplikacji

Ścieżka	Przeznaczenie
app/PdfBuilders/*	Statyczne, bezpieczne dla kolejki konstruktory akceptowane przez GeneratePdfJob.
app/Libraries/*	Opcjonalne komponenty opakowujące aplikacji dla powtarzalnych przepływów pracy z dokumentami.
app/Services/*	Pobieranie danych domenowych i zasady przechowywania.
app/Config/NextPdf.php	Nadpisania konfiguracji pakietu na poziomie aplikacji.
tests/app/PdfBuilders/*	Testy konstruktorów i ładunków kolejki.

Korzystaj z funkcji pomocniczych pakietu w krótkich przepływach. Stosuj jawne wywołania usług, gdy budowanie dokumentu należy do klasy, którą można testować bezpośrednio.

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

Wzorzec konstruktora kolejki

Konstruktory kolejki powinny być statyczne, deterministyczne oraz umieszczone w App\PdfBuilders. Utrzymuj tablicę kontekstu na tyle prostą, aby można ją było zserializować i poddać audytowi.

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

Zadanie ogranicza dane wyjściowe do skonfigurowanego katalogu PDF aplikacji. Jeśli aplikacja wymaga przechowywania specyficznego dla najemcy, umieść tę zasadę w jednej usłudze i przetestuj ją przed wysłaniem zadania.

Punkty rozszerzeń

Punkt rozszerzenia	Zastosowanie	Ograniczenie
Services::pdfDocument()	Dostosowywanie tworzenia dokumentów.	Musi zwrócić nowy dokument.
Services::fontRegistry()	Wstępne ładowanie czcionek i dostęp do rejestru.	Odrzucaj niebezpieczne ścieżki i utrzymuj rejestr zablokowany po wstępnym załadowaniu.
Services::pdfSigner()	Włączanie opcjonalnego podpisu cyfrowego.	Zwracaj null, gdy podpisywanie jest wyłączone.
NextPDF\CodeIgniter\Libraries\Pdf	Opakowywanie pracy z dokumentami po stronie kontrolera.	Jeden komponent opakowujący odpowiada jednemu dokumentowi.
App\PdfBuilders::*	Bezpieczne dla kolejki konstruktory dokumentów.	Wymagany statyczny ciąg znaków typu callable.
app/Config/NextPdf.php	Domyślne wartości aplikacji i ustawienia integracji.	Wartości produkcyjne podawaj jawnie.

Przepływ pracy programistycznej

1. Zacznij od kontrolera, który wywołuje pdf() lub service('pdf').
2. Przenieś powtarzalne budowanie dokumentów do app/PdfBuilders lub do usługi aplikacji.
3. Używaj GeneratePdfJob, gdy generowanie jest zbyt wolne dla ścieżki żądania.
4. Dbaj, aby kontekst kolejki był niewielki i możliwy do zserializowania.
5. Przechowuj dane wyjściowe w zatwierdzonym głównym katalogu przechowywania PDF, chyba że celowo rozszerzysz tę zasadę.
6. Dodaj testy dla funkcji pomocniczych, usług, ładunków kolejki oraz niebezpiecznych ścieżek.

Obsługa awarii

Awaria	Gdzie należy to obsłużyć	Zalecana reakcja
Brakujące rozszerzenie lub niebezpieczna ścieżka czcionki	Fabryka usług.	Zgłoś awarię od razu podczas rozwiązywania usług.
Nieprawidłowy konstruktor typu callable	Walidacja zadania kolejki.	Odrzuć zadanie i zapisz ciąg konstruktora w logu, bez sekretów.
Niebezpieczna ścieżka wyjściowa	Usługa przechowywania i zadanie kolejki.	Odrzuć przed wysłaniem i utrzymaj walidację w zadaniu.
Błąd serializacji odpowiedzi	Obsługa błędów kontrolera lub frameworka.	Nie wysyłaj częściowego ciała odpowiedzi.
Niedostępna opcjonalna klasa Premium	Wartość zwracana przez metodę usługi.	Obsłuż null jawnie przed użyciem opcjonalnych funkcji e-faktury.

Bezpieczne wartości domyślne

Zagadnienie	Wartość domyślna	Kiedy nadpisać
Przestrzeń nazw konstruktorów kolejki	App\PdfBuilders.	Zachowaj wartość domyślną, chyba że zaktualizujesz również zasady bezpieczeństwa.
Główny katalog danych wyjściowych	WRITEPATH/pdfs.	Nadpisuj wyłącznie przy użyciu silniejszej listy dozwolonych lokalizacji.
Nazwa pliku odpowiedzi	document.pdf.	Używaj oczyszczonych biznesowych nazw plików.
Metody strumieniowe	Zgodność interfejsu programowania aplikacji (API) z innymi frameworkami.	Nie traktuj strumieniowania jako granicy pamięci w CodeIgniter.
Usługa dokumentów	Domyślnie nowy dokument.	Nie żądaj współdzielonych dokumentów z kodu obsługującego żądanie.

Lista kontrolna testów

• Testy usług weryfikują, że każde rozwiązanie usługi Services::pdf() zwraca niezależny dokument.
• Testy funkcji pomocniczych weryfikują, że pdf() oraz pdf_document() zwracają nowe obiekty.
• Testy odpowiedzi weryfikują nagłówki i normalizację nazwy pliku.
• Testy kolejki obejmują nieprawidłowe ciągi konstruktorów i niebezpieczne ścieżki wyjściowe.
• Testy konstruktorów wykorzystują reprezentatywne dane kontekstowe.
• Testy konfiguracji obejmują ścieżkę czcionek, ścieżkę pamięci podręcznej, przypadek wyłączonego podpisywania oraz przypadek wyłączonego urzędu znaczników czasu (Time-Stamp Authority, TSA).