NextPDF untuk CodeIgniter 4

Sekilas

nextpdf/codeigniter menghubungkan mesin Portable Document Format (PDF) NextPDF ke aplikasi CodeIgniter 4 melalui lapisan Services dari framework tersebut. Anda membuat dokumen PDF di controller, job, atau command, lalu mengembalikannya sebagai respons Hypertext Transfer Protocol (HTTP) native CodeIgniter.

Pemasangan

composer require nextpdf/codeigniter

Berkas composer.json paket ini memerlukan php >=8.4 <9.0, nextpdf/core ^3.0 || ^5.2, dan codeigniter4/framework ^4.6. Paket ini juga menyarankan nextpdf/artisan, nextpdf/premium, dan codeigniter4/queue. Untuk tabel lengkap persyaratan, paket opsional, dan langkah verifikasi, lihat /integrations/codeigniter/install/.

Gambaran konseptual

NextPDF adalah mesin PDF 2.0 untuk PHP 8.4. Mesin inti (nextpdf/core) bersifat agnostik terhadap framework. Mesin ini tidak mengetahui apa pun tentang HTTP, routing, atau wiring dependensi. nextpdf/codeigniter adalah adapter yang menghubungkan mesin tersebut ke aplikasi CodeIgniter 4. Dengan adapter ini terpasang, Anda tidak perlu merangkai sendiri registry, factory, atau penanganan respons.

Paket ini menambahkan empat hal ke aplikasi CodeIgniter 4:

• Sebuah kelas Services (NextPDF\CodeIgniter\Config\Services) yang ditemukan CodeIgniter secara otomatis. Kelas ini mengekspos layanan bernama: fontRegistry, imageRegistry, documentFactory, pdfDocument, pdf, tsaClient, dan pdfSigner.
• Sebuah pustaka Pdf (NextPDF\CodeIgniter\Libraries\Pdf) — sebuah application programming interface (API) tingkat controller. Pustaka ini membungkus satu dokumen sekali pakai dan mengubahnya menjadi respons dalam satu panggilan.
• Sebuah helper PdfResponse (NextPDF\CodeIgniter\Http\PdfResponse) yang membuat DownloadResponse CodeIgniter untuk pratinjau inline atau unduhan. Helper ini melampirkan sekumpulan header tetap untuk hardening respons.
• Dua fungsi helper global, pdf() dan pdf_document(). Keduanya didaftarkan melalui entri autoload files Composer dan Registrar paket.

Paket ini juga mendeteksi ekstensi NextPDF opsional saat membangun dokumen. Ketika nextpdf/artisan terpasang dan biner Chrome dikonfigurasi, dokumen tersebut mendapatkan renderer Chrome. Ketika NextPDF Pro terpasang, keluaran PDF/A dan penandatanganan digital tersedia melalui permukaan Services yang sama. Deteksi ini bersifat kondisional dan senyap. Paket ini tidak pernah mewajibkan ekstensi yang tidak tersedia.

Mengapa kelas Services dan bukan binding container

CodeIgniter 4 tidak menyertakan dependency-injection container PSR-11. Sebagai gantinya, framework ini menggunakan locator Services. Locator Services adalah kelas yang ditemukan oleh framework dengan metode factory statis. Setiap metode mengembalikan instance bersama atau instance baru. PSR-11 tidak menganjurkan pola service-locator — mengoper container ke dalam sebuah objek agar objek itu dapat mengambil dependensinya sendiri — dalam PSR-11 §1.3 dengan kata kerja modal SHOULD NOT. Paket ini mengikuti konvensi locator CodeIgniter. Paket ini juga menjaga permukaan locator tetap minimal dan eksplisit: setiap layanan adalah metode factory bernama dengan parameter bool $getShared, dan pemanggil menerima objek konkret alih-alih handle container.

Desain ini menjaga integrasi CodeIgniter tetap konsisten dengan integrasi Laravel dan Symfony. Setiap integrasi mengekspos layanan logis yang sama melalui idiom framework-nya masing-masing.

Permukaan API

Titik masuk	Tipe	Mengembalikan	Masa hidup
Services::fontRegistry()	layanan	FontRegistryInterface	bersama (dihangatkan, lalu dikunci)
Services::imageRegistry()	layanan	ImageRegistry	bersama (cache least recently used (LRU) terbatas)
Services::documentFactory()	layanan	DocumentFactoryInterface	bersama (tanpa keadaan)
Services::pdfDocument(false)	layanan	NextPDF\Core\Document	baru setiap panggilan
Services::pdf(false)	layanan	NextPDF\CodeIgniter\Libraries\Pdf	baru setiap panggilan
Services::tsaClient()	layanan	?TsaClient	bersama; null ketika tidak ada URL timestamp authority (TSA)
Services::pdfSigner(false)	layanan	?SignerInterface	baru; null ketika penandatanganan dinonaktifkan
pdf()	helper	Pdf	baru setiap panggilan
pdf_document()	helper	Document	baru setiap panggilan
PdfResponse::inline() / download()	statis	DownloadResponse	per panggilan
GeneratePdfJob	job antrean	—	satu per dispatch

Contoh kode — Quick start

Sebuah controller mengembalikan PDF dalam tiga baris. Services::pdf() mengembalikan pustaka Pdf baru yang membungkus dokumen baru. download() lalu membuat DownloadResponse CodeIgniter.

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

Panduan lengkap yang dapat dijalankan tersedia di /integrations/codeigniter/quickstart/. Panduan tersebut mencakup routing, pratinjau inline, dan variasi helper pdf() dan pdf_document().

Contoh kode — Production

Di production, minta instance non-bersama dengan Services::pdf(false). Tangkap satu eksepsi dasar, NextPDF\Exception\NextPdfException; setiap kegagalan inti dan ekstensi mewarisinya. Catat kegagalan beserta konteksnya, alih-alih menelan error tersebut.

try {
    $pdf = Services::pdf(false);
    $pdf->document()->addPage();
    $pdf->document()->cell(0, 10, "Invoice #{$id}");

    return $pdf->download("invoice-{$id}.pdf");
} catch (NextPdfException $e) {
    $logger->error('pdf.invoice.failed', [
        'invoice_id' => $id,
        'exception' => $e::class,
        'message' => $e->getMessage(),
    ]);

    return $this->response
        ->setStatusCode(ResponseInterface::HTTP_INTERNAL_SERVER_ERROR)
        ->setJSON(['error' => 'pdf_generation_failed', 'invoice_id' => $id]);
}

Controller production lengkap tersedia di /integrations/codeigniter/production-usage/. Controller tersebut menambahkan pengukuran waktu untuk observability, masa hidup yang aman bagi worker, dan pembuatan asinkron.

Kasus tepi & jebakan

• Registry fon dan gambar adalah singleton dengan masa hidup proses. Dokumen tidak pernah dibagikan. pdfDocument dan pdf mengembalikan instance baru pada setiap panggilan, sehingga satu permintaan tidak dapat membocorkan konten ke permintaan lain. Services::pdf(false) dan pdf() keduanya mengembalikan pustaka baru yang membungkus dokumen baru.
• Paket ini memerlukan ekstensi PHP mbstring dan zlib. Registry fon memvalidasinya sekali per proses. Jika salah satu ekstensi tidak ada, registry fon memunculkan error runtime yang menyebutkan ekstensi yang hilang.
• Perilaku ekstensi opsional bergantung pada apa yang terpasang di aplikasi yang sama. Jika hanya nextpdf/core yang ada, jalur penandatanganan dan PDF/A mengembalikan null atau dilewati. Jalur-jalur itu tidak pernah gagal secara bising.

Performa

Integrasi ini tidak menambahkan overhead terukur di luar mesin itu sendiri. Registry fon di-parse sekali lalu dikunci. Registry gambar adalah cache LRU yang dibatasi oleh setelan imageCacheMb (50 MB secara default). Mesin inti dan konten dokumen menentukan biaya pembangunan PDF, bukan adapter. Anggaran per halaman untuk kumpulan dokumentasi ini adalah 1500 ms wall / 128 MB peak. Resep nyata menetapkan anggarannya sendiri di front-matter.

Catatan keamanan

PdfResponse melampirkan sekumpulan header respons tetap ke setiap PDF yang dihasilkannya: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag: noindex, nofollow, dan Referrer-Policy: no-referrer. Nama berkas disanitasi, dan nama non-ASCII dikirim dengan parameter extended Request for Comments (RFC) 5987. Job antrean membatasi callable builder ke namespace App\PdfBuilders dan membatasi jalur keluaran ke WRITEPATH/pdfs/. Lihat /integrations/codeigniter/security-and-operations/ untuk model ancaman lengkap.

Konformansi

• Penemuan modul mengandalkan autoloading PSR-4 Composer. Sebuah prefiks namespace dipetakan ke direktori basis, dan nama kelas terkualifikasi penuh dipetakan ke jalur berkas (PSR-4 §x1.x3).
• Desain Services mengikuti panduan locator yang dibahas di PSR-11 §1.3.

Konteks komersial

NextPDF core berlisensi Apache-2.0. Tanda tangan digital, pengarsipan PDF/A, dan penyematan e-invoice Factur-X disediakan oleh NextPDF Pro dan NextPDF Enterprise. Paket CodeIgniter mengekspos metode layanan yang sesuai. Metode-metode tersebut mengembalikan null sampai paket Premium yang cocok terpasang di aplikasi yang sama.

Lihat juga

• /integrations/codeigniter/install/ — pemasangan dan verifikasi paket.
• /integrations/codeigniter/quickstart/ — PDF pertama di sebuah controller.
• /integrations/codeigniter/configuration/ — setiap kunci konfigurasi.
• /integrations/codeigniter/boot-and-discovery/ — bagaimana CodeIgniter menemukan kelas Services.
• /integrations/codeigniter/integration/ — referensi wiring dan smoke test.