Hướng dẫn cho nhà phát triển CodeIgniter

Tổng quan nhanh

Gói CodeIgniter cung cấp các service factory, hàm trợ giúp và một wrapper thư viện Pdf gọn nhẹ cho một tài liệu Portable Document Format (PDF) đơn lẻ. Hãy dùng wrapper này trong controller. Các công việc trong hàng đợi dùng callable builder tĩnh, vì payload hàng đợi của CodeIgniter phải là dữ liệu đã được serialize.

Hãy dùng hướng dẫn này để thiết kế luồng controller, service, builder hàng đợi và bài kiểm thử cho nextpdf/codeigniter.

Ranh giới kiến trúc

Lớp	Thuộc về	Trách nhiệm	Không đặt ở đây
Controller	Ứng dụng	Cấp quyền, gọi một builder hoặc service, rồi trả về một `DownloadResponse`.	Logic bố cục dùng chung.
Wrapper thư viện	`nextpdf/codeigniter`	Bao bọc một `Document` và cung cấp các hàm trợ giúp để trả phản hồi và lưu tệp.	Lưu trữ tài liệu lâu dài.
Service factory	`nextpdf/codeigniter`	Tạo các registry dùng chung và các tài liệu mới.	Thư mục gốc lưu trữ riêng theo nghiệp vụ.
Builder hàng đợi	Ứng dụng	Dựng một tài liệu từ đầu vào callable tĩnh.	Các đối tượng request hoặc trạng thái không thể serialize.
Engine lõi	`nextpdf/nextpdf`	Dựng và serialize tệp PDF.	Chính sách phản hồi hoặc hàng đợi của CodeIgniter.

Vòng đời lúc chạy

Giai đoạn	Hành vi	Hành động của nhà phát triển
Đăng ký autoload	`Registrar::Autoload()` đăng ký việc nạp helper cho module.	Nạp module thông qua cấu hình CodeIgniter.
Phân giải service	`Services::pdf()` trả về một wrapper bao quanh một tài liệu mới theo mặc định.	Phân giải một lần cho mỗi request.
Soạn nội dung	Mã ứng dụng dùng `Pdf::document()` cho các lệnh gọi tài liệu lõi.	Giữ mã dựng tài liệu trong service hoặc builder.
Phản hồi	`PdfResponse` trả về một `DownloadResponse`.	Hãy để gói tự thiết lập các header PDF.
Thực thi hàng đợi	`GeneratePdfJob::process()` xác thực builder và đường dẫn đầu ra, rồi lưu tệp.	Đặt các builder hàng đợi trong `App\PdfBuilders`.

Cấu trúc ứng dụng được khuyến nghị

Đường dẫn	Mục đích
`app/PdfBuilders/*`	Các builder tĩnh an toàn cho hàng đợi, được `GeneratePdfJob` chấp nhận.
`app/Libraries/*`	Các wrapper ứng dụng tùy chọn bao quanh những luồng tài liệu lặp lại.
`app/Services/*`	Truy xuất dữ liệu nghiệp vụ và chính sách lưu trữ.
`app/Config/NextPdf.php`	Các giá trị ghi đè của ứng dụng cho cấu hình gói.
`tests/app/PdfBuilders/*`	Các bài kiểm thử builder và payload hàng đợi.

Hãy dùng các helper của gói cho những luồng ngắn. Dùng các lệnh gọi service tường minh khi việc dựng tài liệu thuộc về một lớp có thể kiểm thử trực tiếp.

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

Mẫu builder hàng đợi

Các builder hàng đợi nên là tĩnh, có tính tất định và được đặt trong App\PdfBuilders. Hãy giữ mảng context đủ đơn giản để serialize và kiểm thử.

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

Công việc này giới hạn đầu ra trong thư mục PDF đã cấu hình của ứng dụng. Nếu ứng dụng của bạn cần lưu trữ riêng theo tenant, hãy đặt chính sách đó trong một service duy nhất và kiểm thử trước khi điều phối công việc.

Điểm mở rộng

Điểm mở rộng	Dùng cho	Ràng buộc
`Services::pdfDocument()`	Tùy chỉnh việc tạo tài liệu.	Phải trả về một tài liệu mới.
`Services::fontRegistry()`	Khởi động trước các phông chữ và truy cập registry.	Từ chối các đường dẫn không an toàn và giữ registry ở trạng thái khóa sau khi khởi động.
`Services::pdfSigner()`	Bật tính năng ký số tùy chọn.	Trả về `null` khi việc ký bị tắt.
`NextPDF\CodeIgniter\Libraries\Pdf`	Bao bọc phần xử lý tài liệu hướng tới controller.	Một wrapper tương ứng với một tài liệu.
`App\PdfBuilders::*`	Các builder tài liệu an toàn cho hàng đợi.	Bắt buộc dùng chuỗi callable tĩnh.
`app/Config/NextPdf.php`	Các giá trị mặc định của ứng dụng và thiết lập tích hợp.	Hãy giữ các giá trị production thật tường minh.

Quy trình phát triển

Bắt đầu với một controller gọi pdf() hoặc service('pdf').
Chuyển phần dựng tài liệu lặp lại vào app/PdfBuilders hoặc một service trong ứng dụng.
Dùng GeneratePdfJob khi việc tạo quá chậm so với luồng request.
Giữ context hàng đợi nhỏ gọn và có thể serialize.
Lưu đầu ra trong thư mục gốc lưu trữ PDF đã được duyệt, trừ khi bạn cố ý mở rộng chính sách.
Thêm bài kiểm thử cho các helper, service, payload hàng đợi và các đường dẫn không an toàn.

Xử lý lỗi

Lỗi	Nơi nên xử lý	Phản hồi được khuyến nghị
Thiếu extension hoặc đường dẫn phông chữ không an toàn	Service factory.	Báo lỗi ngay trong lúc phân giải service.
Callable builder không hợp lệ	Xác thực của công việc hàng đợi.	Từ chối công việc và ghi log chuỗi builder mà không kèm thông tin bí mật.
Đường dẫn đầu ra không an toàn	Service lưu trữ và công việc hàng đợi.	Từ chối trước khi điều phối và duy trì việc xác thực công việc.
Lỗi serialize phản hồi	Xử lý lỗi trong controller hoặc framework.	Không gửi phần thân phản hồi dở dang.
Lớp Premium tùy chọn không khả dụng	Giá trị trả về của phương thức service.	Xử lý `null` một cách tường minh trước khi dùng các tính năng e-invoice tùy chọn.

Giá trị mặc định an toàn

Mối quan tâm	Mặc định	Khi nào nên ghi đè
Namespace của builder hàng đợi	`App\PdfBuilders`.	Hãy giữ giá trị mặc định, trừ khi bạn cũng cập nhật chính sách bảo mật.
Thư mục gốc đầu ra	`WRITEPATH/pdfs`.	Chỉ ghi đè bằng một allowlist chặt chẽ hơn.
Tên tệp phản hồi	`document.pdf`.	Dùng các tên tệp nghiệp vụ đã được làm sạch.
Các phương thức stream	Tương đương về application programming interface (API) với các framework khác.	Không xem việc stream như một ranh giới bộ nhớ trong CodeIgniter.
Service tài liệu	Mới theo mặc định.	Không yêu cầu tài liệu dùng chung từ mã trong request.

Danh sách kiểm tra khi kiểm thử

Các bài kiểm thử service xác nhận mỗi lần phân giải Services::pdf() đều trả về một tài liệu độc lập.
Các bài kiểm thử helper xác nhận pdf() và pdf_document() trả về các đối tượng mới.
Các bài kiểm thử phản hồi xác nhận các header và việc chuẩn hóa tên tệp.
Các bài kiểm thử hàng đợi bao phủ các chuỗi builder không hợp lệ và các đường dẫn đầu ra không an toàn.
Các bài kiểm thử builder dùng dữ liệu context tiêu biểu.
Các bài kiểm thử cấu hình bao phủ đường dẫn phông chữ, đường dẫn cache, trạng thái tắt ký và trạng thái tắt Time-Stamp Authority (TSA).