Vòng đời phiên an toàn cho worker trên NextPDF Connect

Tổng quan nhanh

Hãy dùng vòng đời phiên được giới hạn theo từng yêu cầu trong một worker PHP chạy lâu dài (RoadRunner, Swoole, Laravel Octane). Mỗi yêu cầu tạo phiên tài liệu riêng và hủy phiên đó sau khi gọi output_pdf. Trạng thái phông chữ, trang và handle được giữ trong ranh giới yêu cầu của worker. Các công cụ là create_pdf, set_font, add_text và output_pdf — tất cả đều thuộc Core.

Cài đặt

composer require nextpdf/server

Hãy ràng buộc một transport. Mẫu này hoạt động như nhau với mọi transport.

Tổng quan khái niệm

Một document_id là handle mờ chỉ có phạm vi trong một yêu cầu. Hãy tuân theo một quy tắc: tạo theo từng yêu cầu, hủy theo từng yêu cầu, không bao giờ lưu vào bộ nhớ đệm hay chia sẻ. Với giá trị mặc định destroy: true, output_pdf kết xuất tài liệu và giải phóng phiên trong một bước nguyên tử. Yêu cầu tiếp theo trên cùng worker sẽ nhận một phiên mới, độc lập. Phông chữ và nội dung của phiên trước đó đã biến mất. Mỗi kết quả công cụ là một phản hồi transport thông thường (PSR-18 §p2). Mã của server được cô lập bởi ranh giới autoload (PSR-4 §3). Kho lưu trữ phiên là trạng thái xuyên yêu cầu duy nhất và được khóa theo id.

Bề mặt API

Công cụ	Vai trò	Bậc rủi ro
`create_pdf`	Mở một phiên cho mỗi yêu cầu	An toàn
`set_font`	Đặt phông chữ đang hoạt động (theo từng phiên)	Thận trọng
`add_text`	Ghi nội dung	Thận trọng
`output_pdf`	Kết xuất và hủy phiên	Cần phê duyệt / Xem xét (base64)

Trang danh mục công cụ là nguồn chuẩn. Các công cụ bạn có thể dùng phụ thuộc vào bậc đã cài đặt.

Mã mẫu — Bắt đầu nhanh

Yêu cầu 1: create_pdf → set_font → add_text → output_pdf (destroy: true). Yêu cầu 2 trên cùng worker sẽ bắt đầu một phiên create_pdf mới. id cũ giờ không còn hợp lệ. Hãy đặt lại phông chữ vì nó không được mang sang.

Mã mẫu — Production

Hãy bao bọc vòng đời phiên để việc dọn dẹp luôn chạy:

Lấy phiên khi yêu cầu bắt đầu.
Dựng nội dung.
Trong một khối tương đương finally, hãy gọi output_pdf; lệnh này hủy phiên. Nếu bạn đã dùng destroy: false cho luồng kiểm tra rõ ràng sau khi xuất, hãy hủy phiên một cách tường minh sau đó.

Không bao giờ lưu một document_id trong container toàn cục của worker, container tĩnh hoặc container dùng chung. Không bao giờ truyền nó giữa các coroutine, fiber hoặc bộ xử lý yêu cầu.

Trường hợp biên & điểm dễ vấp

Dùng lại id sau khi hủy. Sẽ trả về lỗi tài liệu không xác định. Hãy tạo một phiên mới cho mỗi yêu cầu.
Quên output_pdf. Bộ nhớ âm thầm tăng lên cho đến khi TTL của phiên hết hạn hoặc tiến trình khởi động lại. Hãy luôn hoàn tất vòng đời phiên.
Giới hạn phiên khi có tải. Kho lưu trữ có mức trần về số phiên đồng thời. Việc hủy kịp thời giúp bạn ở dưới mức đó.
destroy: false mà không dọn dẹp. Bộ nhớ sẽ tăng dần. Chỉ dùng nó cho một luồng kiểm tra rõ ràng sau khi xuất, rồi hủy phiên.
Dùng chung id giữa các yêu cầu đồng thời. Một tình huống tranh chấp sẽ làm hỏng kết quả xuất. Mỗi yêu cầu sở hữu phiên riêng.

Hiệu năng

Kết quả xuất của mỗi yêu cầu chỉ vài KB. Lợi ích là bộ nhớ worker được giới hạn trong suốt vòng đời worker. Hồ sơ là structural.

Ghi chú bảo mật

Sự cô lập phiên cũng là một thuộc tính bảo mật. Nội dung của một yêu cầu không bao giờ lọt sang yêu cầu khác, vì handle không được chia sẻ và phiên bị hủy lúc xuất.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Mỗi kết quả của công cụ là một phản hồi transport thông thường.	PSR-18	§p2
Mã được cô lập bởi ánh xạ class→tệp của autoload.	PSR-4	§3

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

Không áp dụng — tất cả công cụ đều thuộc Core.

Khả dụng của transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	Thông thường là một tiến trình stdio cho mỗi worker.
REST	Có	Ranh giới yêu cầu HTTP ánh xạ tới ranh giới phiên.
gRPC	Có	Một phiên cho mỗi luồng RPC.

Bậc rủi ro HITL

create_pdf là An toàn. set_font và add_text là Thận trọng. output_pdf là Cần phê duyệt, được hạ xuống Xem xét ở chế độ base64. Trong một worker, kết quả xuất base64 là luồng thông thường và không thêm cổng kiểm soát nào (Bậc rủi ro HITL).

Bao bọc JSON của cổng xác nhận

Kết quả xuất base64 của worker:

{ "allowed": true }