Khởi động và phát hiện Gotenberg trong NextPDF

Tổng quan nhanh

Bridge không có cơ chế phát hiện tự động. Bạn khởi tạo nó như một service thông thường qua constructor injection tường minh: một configuration value object và các thành phần cộng tác Hypertext Transfer Protocol (HTTP) do PHP Standard Recommendation (PSR) định nghĩa. Package này không đi kèm service provider, bundle hay container extension nào, và bản thân nó không đọc bất kỳ biến môi trường nào. Ở đây, “phát hiện” nghĩa là cách host framework cung cấp các thành phần cộng tác đó. Trách nhiệm này nằm ở framework, không nằm ở package này.

Cách bridge được phát hiện

Nó không được phát hiện tự động. Bạn tự khởi tạo nó. GotenbergBridge yêu cầu bốn tham số và chấp nhận thêm ba tham số tùy chọn:

• Bắt buộc: một GotenbergConfig, một PSR-18 client, một PSR-17 request factory và một PSR-17 stream factory.
• Tùy chọn: một PSR-3 logger, một chính sách bảo mật Hypertext Markup Language (HTML) (mặc định dùng chính sách mặc định của NextPDF core), và một PSR-17 response factory.

Response factory kích hoạt transport ghim dựa trên cURL. Hãy cung cấp nó; khi bridge có thứ gì đó để ghim (các địa chỉ đã phân giải hoặc các pin SubjectPublicKeyInfo (SPKI) đã được cấu hình), nó sẽ dùng transport ghim. Nếu bạn bỏ qua, PSR-18 client được inject sẽ luôn được dùng. Hợp đồng tham số đầy đủ nằm ở /integrations/gotenberg/configuration/.

Trình tự khởi động

Không có bước đăng ký. Vòng đời diễn ra như sau:

1. Host phân giải một PSR-18 client và các PSR-17 factory. Host container thực hiện việc này; package thì không.
2. Ứng dụng khởi tạo một GotenbergConfig từ nguồn cấu hình của nó. GotenbergConfig::fromArray() chấp nhận một mảng snake_case và thay thế các giá trị không hợp lệ bằng giá trị mặc định. Hãy xác thực nguồn trong boot path của bạn để một giá trị Uniform Resource Locator (URL) bị thiếu sẽ lỗi ngay khi khởi động, thay vì ở từng lần chuyển đổi.
3. Ứng dụng khởi tạo GotenbergBridge với config và các thành phần cộng tác.
4. Lệnh gọi chuyển đổi đầu tiên chạy xác thực URL, sàng lọc server-side request forgery (SSRF), sàng lọc tên tệp, rồi thực hiện yêu cầu. Không có việc gì diễn ra tại thời điểm dựng; bridge chưa hoạt động cho đến khi bạn gọi nó.

Binding trong container

Package này không đi kèm binding container nào. Để có thể inject bridge, hãy đăng ký nó trong container của host application như sau:

• Bind GotenbergConfig từ nguồn cấu hình của bạn.
• Bind PSR-18 client và các PSR-17 factory tới các implementation bạn đã chọn.
• Bind GotenbergBridge như một service nhận các dependency đó.

Auto-wiring đặc thù của framework, việc publish cấu hình và việc đăng ký service-provider hay bundle thuộc về các package tích hợp framework riêng, không thuộc phạm vi ở đây. Package này được thiết kế độc lập với framework. Nó chỉ phụ thuộc vào các interface PSR, nên có thể hoạt động trong mọi container.

Thứ tự phân giải cấu hình

Package không tự đọc bất kỳ cấu hình nào. Thứ tự phân giải là bất cứ logic nào ứng dụng của bạn triển khai trước khi gọi GotenbergConfig::fromArray() hoặc constructor. Một thứ tự phổ biến là các biến môi trường, rồi đến một tệp config đã publish, rồi đến các giá trị mặc định trong code. Thứ tự đó là hợp đồng của ứng dụng của bạn, không phải của package này. Điều package có định nghĩa là giá trị mặc định cho từng trường mà mảng truyền vào fromArray() để trống: URL application programming interface (API) rỗng, timeout 30 giây, giới hạn kích thước 50 MiB, API key rỗng, và các danh sách pin rỗng.

Chẩn đoán

Hai tín hiệu tích hợp sẵn xác nhận việc kết nối:

• isAvailable() xác thực URL mà không tạo lưu lượng mạng, rồi gửi một yêu cầu HEAD tới <apiUrl>/health và báo cáo là sẵn sàng khi mã trạng thái nhỏ hơn 500. Nó trả về false thay vì ném lỗi khi gặp bất kỳ thất bại nào. Hãy gọi nó từ một readiness check.
• Một lần chuyển đổi thử nghiệm với một tài liệu nhỏ đã biết là hợp lệ sẽ xác nhận toàn bộ luồng từ đầu đến cuối. Việc này bao gồm yêu cầu multipart tới <apiUrl>/forms/libreoffice/convert và bước xác thực phản hồi.

Xem thêm

• /integrations/gotenberg/integration/ — điều khiển một pipeline NextPDF thông qua service.
• /integrations/gotenberg/install/ — cài đặt package và service.
• /integrations/gotenberg/configuration/ — hợp đồng đầy đủ của constructor và config.
• /integrations/gotenberg/overview/ — luồng chuyển đổi và mô hình dependency.