Tham khảo API CodeIgniter

Tổng quan nhanh

Gói CodeIgniter cung cấp một giao diện lập trình ứng dụng (API) nhỏ, hướng đến controller. Gói này gồm lớp bao bọc Pdf cho một tài liệu (Services::pdf() và hàm trợ giúp toàn cục pdf()), các hàm trợ giúp phản hồi để chuyển tài liệu đã dựng thành DownloadResponse (PdfResponse), các factory Services đứng phía sau chúng (registry phông chữ và hình ảnh, factory tài liệu, cùng signer tùy chọn và client của nhà cung cấp dấu thời gian (TSA)), lớp cấu hình NextPdf, và GeneratePdfJob để tạo bất đồng bộ từ các builder callable tĩnh.

Bắt đầu từ đường dẫn controller chính: gọi Services::pdf() (hoặc hàm trợ giúp pdf()), thêm nội dung vào $pdf->document(), rồi trả về $pdf->download('file.pdf'). Đường dẫn này bao quát trường hợp phổ biến. Các bảng tham khảo được sắp xếp theo từng bề mặt API; mục Tác vụ phổ biến trình bày trước các mẫu có thể chạy.

Tác vụ phổ biến

Đây là các luồng phổ biến nhất trong môi trường production. Mỗi mẫu đều đã được xác minh theo mã nguồn của nextpdf/codeigniter.

Dùng đường dẫn kết xuất chuẩn để trả về một tệp Portable Document Format (PDF) có thể tải xuống từ controller:

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

Luồng này tạo một Pdf mới bao quanh một Document mới, ghi một ô, rồi trả về một DownloadResponse với attachment cùng các header bảo mật của gói.

Xem trước một PDF nội tuyến trong trình duyệt bằng cùng lớp bao bọc đó và inline() thay cho 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');
    }
}

Luồng này dùng hàm trợ giúp toàn cục pdf() (tương đương với Services::pdf()) và trả về một DownloadResponse với inline để trình duyệt hiển thị PDF thay vì tải xuống.

Tạo một PDF bất đồng bộ trên hàng đợi bằng GeneratePdfJob và một builder tĩnh:

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

Luồng này đưa quá trình tạo vào hàng đợi. Worker xác thực builder (phải là một callable tĩnh dạng App\PdfBuilders\...::method) và đường dẫn đầu ra (phải nằm trong WRITEPATH/pdfs/ và kết thúc bằng .pdf), dựng một tài liệu mới, rồi lưu lại.

Lớp bao bọc thư viện

Dùng bảng này khi bạn đã có lớp bao bọc Pdf và cần các phương thức phản hồi hoặc lưu của nó.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: tài liệu lõi mới.	Bao bọc tài liệu được cung cấp cho thao tác phản hồi hoặc lưu.	`Pdf`	Không dự kiến có lỗi.	Không dùng lại lớp bao bọc sau khi đã xuất.
`Pdf::document()`	không có.	Trả về tài liệu đang được bao bọc.	`NextPDF\Core\Document`	Không dự kiến có lỗi.	Dùng phương thức này để gọi các API biên soạn của lõi.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: tên tệp phản hồi.	Dùng disposition nội tuyến của trình duyệt.	`CodeIgniter\HTTP\DownloadResponse`	Các lỗi tuần tự hóa của lõi.	Ủy thác cho `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: tên tệp phản hồi.	Dùng disposition đính kèm của trình duyệt.	`DownloadResponse`	Các lỗi tuần tự hóa của lõi.	Ủy thác cho `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: tên tệp phản hồi.	Cung cấp API tương đương với các gói framework khác.	`DownloadResponse`	Các lỗi tuần tự hóa của lõi.	CodeIgniter xử lý đầu ra nhị phân một cách tự nhiên.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: tên tệp phản hồi.	Cung cấp API tương đương với các gói framework khác.	`DownloadResponse`	Các lỗi tuần tự hóa của lõi.	Dùng cùng các kiểm soát kích thước như phản hồi không stream.
`Pdf::save(string $path)`	`path`: đích trên hệ thống tệp.	Ghi tài liệu đang được bao bọc.	`void`	Các lỗi ghi của hệ thống tệp hoặc của lõi.	Xác thực các thư mục gốc lưu trữ trước khi lưu.

Dịch vụ và hàm trợ giúp

Dùng bảng này khi bạn cần một factory dịch vụ cụ thể hoặc một hàm trợ giúp toàn cục, bao gồm hành vi chia sẻ và kiểu trả về.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`Services::fontRegistry(bool $getShared = true)`	`getShared`: cờ dịch vụ dùng chung của CodeIgniter.	Trả về một registry dùng chung, nạp sẵn các phông chữ đã cấu hình, rồi khóa registry.	`FontRegistryInterface`	`RuntimeException` khi thiếu extension hoặc đường dẫn phông chữ không an toàn.	Từ chối các stream wrapper và byte null trong `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: cờ dịch vụ dùng chung.	Trả về một registry hình ảnh dùng chung, có giới hạn, theo cơ chế ít được dùng gần đây nhất (LRU).	`ImageRegistry`	Không dự kiến có lỗi.	Kích thước bộ nhớ đệm do `imageCacheMb` điều khiển.
`Services::documentFactory(bool $getShared = true)`	`getShared`: cờ dịch vụ dùng chung.	Trả về một factory dùng chung sử dụng các registry dùng chung.	`DocumentFactoryInterface`	Các lỗi thiết lập registry.	Factory có thể dùng lại; tài liệu thì không.
`Services::tsaClient(bool $getShared = true)`	`getShared`: cờ dịch vụ dùng chung.	Trả về `null` khi `tsa.url` rỗng.	`TsaClient	null`	Lỗi của client Hypertext Transfer Protocol (HTTP) hoặc lỗi cấu hình TSA.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: cờ dịch vụ dùng chung.	Trả về `null` khi ký được tắt.	`SignerInterface	null`	Các lỗi ở mức chứng chỉ hoặc chữ ký.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: cờ dịch vụ dùng chung.	Tạo một tài liệu mới, áp dụng các giá trị mặc định, và tùy chọn cấu hình PDF/A hoặc Artisan.	`Document`	Các lỗi extension tùy chọn hoặc lỗi cấu hình tài liệu.	Giữ giá trị mặc định `false` để bảo đảm an toàn theo từng request.
`Services::pdf(bool $getShared = false)`	`getShared`: cờ dịch vụ dùng chung.	Tạo một lớp bao bọc `Pdf` mới bao quanh một tài liệu mới.	`NextPDF\CodeIgniter\Libraries\Pdf`	Các lỗi thiết lập tài liệu.	Dịch vụ chính hướng đến controller.
`Services::eInvoiceEmbedder()`	không có.	Trả về `null` trừ khi lớp embedder hóa đơn điện tử của Premium Pro tồn tại.	`EmbedderInterface	null`	Các lỗi khởi tạo gói tùy chọn.
`Services::eInvoiceValidator()`	không có.	Trả về `null` trừ khi lớp validator của Premium Enterprise tồn tại.	`ValidatorInterface	null`	Các lỗi khởi tạo gói tùy chọn.
`Services::eInvoiceProfile()`	không có.	Trả về profile EN16931 khi Premium Pro được cài đặt.	`ProfileInterface	null`	Các lỗi gói tùy chọn.
`Services::schematronRunner()`	không có.	Trả về `null` trừ khi validator Schematron của Premium Enterprise tồn tại.	`SchematronRunnerInterface	null`	Các lỗi khởi tạo gói tùy chọn.
`Registrar::Autoload()`	không có.	Thêm hàm trợ giúp của gói vào cấu hình autoload của CodeIgniter.	`array`	Không dự kiến có lỗi.	Bật `pdf()` và `pdf_document()` khi module được nạp.
`pdf()`	không có.	Gọi `Services::pdf(false)`.	`Pdf`	Các lỗi thiết lập tài liệu.	Hàm trợ giúp tiện lợi cho các controller.
`pdf_document()`	không có.	Gọi `Services::pdfDocument(false)`.	`Document`	Các lỗi thiết lập tài liệu.	Hàm trợ giúp tiện lợi khi muốn dùng trực tiếp API tài liệu của lõi.

Phản hồi HTTP

Dùng bảng này khi bạn đã có một Document đã dựng và muốn tự xây dựng DownloadResponse thay vì dùng lớp bao bọc Pdf.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: tài liệu đã dựng; `filename`: tên tệp phản hồi.	Bảo đảm có phần mở rộng `.pdf` và disposition nội tuyến.	`DownloadResponse`	Các lỗi tuần tự hóa của lõi.	Thêm kiểu nội dung PDF và các header phòng vệ.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Giống như `inline`; disposition là đính kèm.	Bảo đảm có phần mở rộng `.pdf`.	`DownloadResponse`	Giống như `inline`.	Dùng cho tải xuống qua trình duyệt.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Giống như `inline`.	Cùng hành vi như `inline` trong CodeIgniter 4 (CI4).	`DownloadResponse`	Giống như `inline`.	Tồn tại để bảo đảm sự tương đương API giữa các framework.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Giống như `download`.	Cùng hành vi như `download` trong CI4.	`DownloadResponse`	Giống như `download`.	Tồn tại để bảo đảm sự tương đương API giữa các framework.

Tác vụ hàng đợi

Dùng bảng này khi bạn nối quá trình tạo bất đồng bộ và cần đúng khóa dữ liệu tác vụ cùng hợp đồng builder-callable.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`GeneratePdfJob::process()`	Các khóa dữ liệu tác vụ: `builder`, `outputPath`, và tùy chọn `context`.	Dùng một mảng context rỗng khi bị bỏ qua.	`void`	`InvalidArgumentException` khi builder hoặc đường dẫn đầu ra không an toàn; các lỗi ghi của lõi.	Builder phải là `App\PdfBuilders\...\*::method`.
Builder callable	`Document $doc`, `array $context`.	Không có context mặc định ngoài dữ liệu tác vụ.	`Document`	Các ngoại lệ riêng của builder.	Yêu cầu callable tĩnh vì payload hàng đợi của CI4 là dữ liệu được tuần tự hóa.

Cấu hình

Dùng bảng này khi bạn thay đổi các giá trị mặc định cho định dạng trang, đường dẫn, ký, TSA, hoặc siêu dữ liệu tài liệu trong lớp cấu hình NextPdf.

Thuộc tính	Kiểu	Hành vi mặc định	Ghi chú
`pageFormat`	`string`	`A4`.	Đặt định dạng trang mặc định.
`orientation`	`string`	`P`.	Đặt hướng trang mặc định.
`unit`	`string`	`mm`.	Đặt đơn vị mặc định.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` và `WRITEPATH . 'cache/nextpdf'`.	Giữ các đường dẫn bên trong vùng lưu trữ do ứng dụng kiểm soát.
`signature`	`array`	Tắt với mức `B-B`.	Chứng chỉ, khóa, mật khẩu, các chứng chỉ bổ sung và mức.
`tsa`	`array`	Tắt khi Uniform Resource Locator (URL) là `null`; thời gian chờ 30 giây.	Thông tin xác thực, các tệp mutual Transport Layer Security (mTLS), public-key pin và chính sách HTTP.
`ocspCache`	`array`	Bật với thời gian sống (TTL) là 86400 giây.	Được dùng bởi các luồng xác thực chữ ký khi có sẵn.
`preloadFonts`	`list<string>`	Rỗng.	Được nạp sẵn trước khi registry bị khóa.
`imageCacheMb`	`int`	`50`.	Điều khiển bộ nhớ đệm hình ảnh tồn tại suốt vòng đời tiến trình.
`fontCacheLocking`	`bool`	`true`.	Tách các thay đổi registry phông chữ khỏi quá trình xử lý request.
`artisan`	`array`	Bộ kết xuất Chrome bị tắt trừ khi được cấu hình và cài đặt.	Ánh xạ tới `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Creator `NextPDF`, author rỗng, ngôn ngữ `en`, các lề mặc định và phông chữ mặc định.	`Services::pdfDocument()` chỉ áp dụng `creator`, `language`, và (khi không rỗng) `author`; `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box`, và `bleed_box` là các giá trị mặc định đã được định nghĩa, nhưng hiện chưa được áp dụng.

Ghi chú phát triển

GeneratePdfJob giới hạn đầu ra trong WRITEPATH . 'pdfs' và yêu cầu .pdf.
Các builder callable nằm ngoài App\PdfBuilders bị từ chối để tránh thực thi mã tùy ý từ các payload hàng đợi bị sửa đổi.
Dùng service('pdf') hoặc hàm trợ giúp của gói cho các luồng controller; dùng tác vụ hàng đợi cho quá trình tạo chạy lâu.