Tích hợp NextPDF với CodeIgniter

Tổng quan nhanh

Cài đặt gói, rồi CodeIgniter 4 sẽ tự liên kết gói đó cho bạn. Hãy dùng trang này để xác nhận tích hợp: tự phát hiện, mô hình liên kết, xuất bản cấu hình và một bài kiểm tra nhanh bằng một phương thức duy nhất để chứng minh tích hợp hoạt động.

Cài đặt

composer require nextpdf/codeigniter

Bạn không cần chỉnh sửa service provider hay thay đổi tệp bootstrap. Xem /integrations/codeigniter/install/ để biết các ràng buộc phiên bản đã được kiểm chứng.

Khởi động / tự phát hiện

CodeIgniter 4 tìm thấy gói thông qua cơ chế tự phát hiện gói của Composer khi Config\Modules::$discoverInComposer là true, giá trị mặc định của framework. Tiền tố PHP Standard Recommendation 4 (PSR-4) NextPDF\CodeIgniter\ ánh xạ tới src/CodeIgniter/, nên framework có thể phân giải NextPDF\CodeIgniter\Config\Services về đúng tệp của lớp đó (PSR-4 §x1.x3). /integrations/codeigniter/boot-and-discovery/ ghi lại đầy đủ trình tự và các thuộc tính Config\Modules chi phối trình tự này.

Liên kết container

CodeIgniter 4 không đi kèm container PSR-11. PSR-11 §1.3 không khuyến khích mẫu service-locator (động từ tình thái SHOULD NOT). Gói tuân theo quy ước locator của framework và giữ việc dùng locator ở mức tối thiểu. Mỗi liên kết là một static factory có tên, với tham số bool $getShared.

Tên dịch vụ	Trả về	Vòng đời mặc định
`fontRegistry`	`FontRegistryInterface`	dùng chung
`imageRegistry`	`ImageRegistry`	dùng chung
`documentFactory`	`DocumentFactoryInterface`	dùng chung
`pdfDocument`	`Document`	tạo mới
`pdf`	`Pdf`	tạo mới
`tsaClient`	`?TsaClient`	dùng chung
`pdfSigner`	`?SignerInterface`	tạo mới

Bạn có thể dùng điểm vào nào cũng được; chúng tương đương nhau:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

$a = Services::pdf(false);   // direct
$b = \service('pdf');        // helper → Services::pdf()

Các helper toàn cục pdf() và pdf_document() bọc quanh Services::pdf(false) và Services::pdfDocument(false).

Xuất bản cấu hình

Cấu hình của gói nằm trong NextPDF\CodeIgniter\Config\NextPdf, một BaseConfig không phải final. Bạn có thể ghi đè cấu hình bằng một trong hai cách được hỗ trợ:

1. Kế thừa lớp (có kiểu, quản lý được phiên bản). Tạo app/Config/NextPdf.php:

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;
}

CodeIgniter nạp lớp trong ứng dụng của bạn thay cho lớp mặc định của gói.

2. Ghi đè bằng .env (theo từng môi trường). Dùng tên lớp ngắn ở dạng chữ thường, nextpdf, làm tiền tố:

nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem

/integrations/codeigniter/configuration/ ghi lại từng khóa và các quy tắc ghi đè mảng.

Kiểm tra nhanh service provider / bundle

CodeIgniter không có lớp service provider hay bundle nào để kiểm tra. Hãy dùng bài kiểm tra nhanh tương đương để xác minh hai điều: tính năng tự phát hiện đã phân giải được các dịch vụ, và vòng đời hoạt động đúng như mô tả. Hành động controller bên dưới có thể chạy được và phản ánh đúng các khẳng định chức năng của chính gói.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\CodeIgniter\Libraries\Pdf;
use NextPDF\Core\Document;

final class NextPdfSmokeController extends BaseController
{
    public function check(): ResponseInterface
    {
        // Discovery resolved the services.
        $document = Services::pdfDocument(false);
        $library = Services::pdf(false);

        // Documents are fresh per call (no cross-request leakage).
        $freshIsolated = Services::pdfDocument(false) !== $document;

        // Registries are shared singletons.
        $registrySingleton = Services::fontRegistry() === Services::fontRegistry();

        // Optional services degrade to null without Premium / TSA config.
        $signerOptional = Services::pdfSigner(false) === null;

        $ok = $document instanceof Document
            && $library instanceof Pdf
            && $freshIsolated
            && $registrySingleton
            && $signerOptional;

        return $this->response
            ->setStatusCode($ok ? 200 : 500)
            ->setJSON([
                'discovery' => $document instanceof Document,
                'document_fresh_per_call' => $freshIsolated,
                'registry_shared' => $registrySingleton,
                'signer_optional_null' => $signerOptional,
            ]);
    }
}

Ánh xạ một route tới hành động này, rồi gửi yêu cầu tới route đó. Phản hồi 200 với mọi cờ được đặt thành true chứng minh tích hợp đã hoạt động. Mỗi khẳng định ở đây tương ứng với một hành vi đã được kiểm chứng trong bộ kiểm thử chức năng của gói.

Trường hợp đặc biệt & lưu ý

Nếu ứng dụng chủ tắt tính năng tự phát hiện của Composer, hãy thêm nextpdf/codeigniter vào Config\Modules::$composerPackages['only'].
Services::pdfDocument(true) trả về một tài liệu dùng chung. Nó chỉ tồn tại để đặt lại trạng thái trong kiểm thử. Đừng bao giờ yêu cầu tài liệu dùng chung trong mã xử lý request hay job.
Services::pdfSigner() và Services::tsaClient() trả về null cho đến khi cấu hình việc ký hoặc một endpoint Time-Stamping Authority (TSA). Đây là cơ chế suy giảm có chủ đích và êm ái, không phải lỗi.

Tuân thủ

Ánh xạ class-path để phát hiện module (PSR-4 Autoloader §x1.x3).
Hướng dẫn về service-locator cho mô hình liên kết (PSR-11 Container §1.3).

Bối cảnh thương mại

Phần lõi NextPDF dùng giấy phép Apache-2.0. Sau khi bạn cài đặt Pro hoặc Enterprise, các dịch vụ của gói đó xuất hiện trên cùng bề mặt Services. Gói CodeIgniter cung cấp các phương thức dịch vụ tương ứng. Mỗi phương thức trả về null cho đến khi bạn cài đặt gói Premium tương ứng. Xem </get-license/?intent=codeigniter>.

Xem thêm

/integrations/codeigniter/boot-and-discovery/ — chi tiết nội bộ của tính năng tự phát hiện.
/integrations/codeigniter/install/ — ràng buộc phiên bản và cách kiểm chứng.
/integrations/codeigniter/quickstart/ — PDF đầu tiên.
/integrations/codeigniter/production-usage/ — các controller được liên kết qua dependency injection và job hàng đợi.
/integrations/codeigniter/configuration/ — mọi khóa cấu hình.