ติดตั้ง NextPDF Artisan

ภาพรวมโดยย่อ

ติดตั้ง nextpdf/artisan ด้วย Composer ซึ่งจะติดตั้งการพึ่งพา runtime chrome-php/chrome ให้ด้วย จากนั้นเตรียมไบนารี Chrome หรือ Chromium ให้พร้อมใช้งานสำหรับโปรเซส PHP

การติดตั้ง

composer require nextpdf/artisan

แพ็กเกจประกาศข้อกำหนดเหล่านี้ใน composer.json:

ข้อกำหนด	เงื่อนไขเวอร์ชัน	หมายเหตุ
`php`	`>=8.4 <9.0`	PHP 8.4 เท่านั้น
`nextpdf/core`	`^3.0 \|\| ^5.2`	เอนจิน NextPDF แบบโอเพนซอร์ส
`chrome-php/chrome`	`^1.15`	ไลบรารีไคลเอนต์ Chrome DevTools Protocol (CDP) ที่ถูกดึงเข้ามาแบบ transitive
`psr/log`	`^3.0`	จุดสำหรับ inject logger แบบเลือกใช้ได้

Composer จะ resolve การพึ่งพา chrome-php/chrome โดยอัตโนมัติ แต่จะไม่ติดตั้งไบนารี Chrome ให้ไม่ว่ากรณีใด ไบนารีดังกล่าวเป็นการพึ่งพาระดับระบบ

จัดเตรียมไบนารี Chrome

bridge นี้ต้องมีไบนารี Chrome หรือ Chromium ที่เรียกใช้งานได้ ตามค่าเริ่มต้น chrome-php/chrome จะค้นหาไบนารีในเส้นทางทั่วไป หากต้องการกำหนดเส้นทางอย่างชัดเจน ให้ส่งผ่านการกำหนดค่า ดู /integrations/artisan/configuration/ และหน้าเฉพาะ /integrations/artisan/chrome-renderer-setup/

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

ก่อนนำไบนารีไปเชื่อมกับแอปพลิเคชัน ให้ตรวจสอบว่าไบนารีทำงานในโหมด headless ได้:

chromium --headless --dump-dom about:blank

เมื่อรันสำเร็จ คำสั่งจะพิมพ์เอกสาร Document Object Model (DOM) เปล่าและจบด้วยรหัส 0 หากจบด้วยรหัสที่ไม่ใช่ศูนย์ แสดงว่าไบนารีหรือ shared library ของไบนารีนั้นขาดหายไป ให้แก้ไขปัญหานี้ก่อนดำเนินการต่อ เพราะ bridge จะแสดงความล้มเหลวเดียวกันเป็น ChromeRenderException ตอนเรนเดอร์

ตรวจสอบว่าแพ็กเกจถูกเชื่อมต่อแล้ว

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

โค้ดนี้สร้าง renderer และอ่านนโยบายความปลอดภัยของ Hypertext Markup Language (HTML) ค่าเริ่มต้นโดยไม่ต้องเรียกใช้งาน Chrome โค้ดนี้ยืนยันว่า autoloading และการ bind contract ของ nextpdf/core resolve ได้ (พฤติกรรมนี้ยืนยันโดย tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected)

การติดตั้งในคอนเทนเนอร์

ใน Docker นั้น Chrome sandbox มักเริ่มทำงานในฐานะ process ID (PID) 1 / root ไม่ได้หากไม่มี kernel capability เพิ่มเติม แพ็กเกจมีสวิตช์ noSandbox สำหรับกรณีดังกล่าว การปิดใช้งาน Chrome sandbox มีต้นทุนด้านความปลอดภัยที่ชัดเจน หน้า /integrations/artisan/security-and-operations/ และ /integrations/artisan/chrome-renderer-setup/ อธิบายต้นทุนดังกล่าวและระบุข้อจำกัดไว้อย่างชัดเจน อย่าตั้งค่าสวิตช์นี้โดยไม่อ่านส่วนดังกล่าว

กรณีขอบเขตและข้อควรระวัง

มี chrome-php/chrome แต่ไม่มีไบนารี Composer จะทำงานสำเร็จ แต่การเรนเดอร์ครั้งแรกจะ throw ChromeRenderException และห่อหุ้มความล้มเหลวในการเปิดใช้งานไว้ การตรวจสอบไลบรารีเป็นคนละขั้นตอนกับการตรวจสอบไบนารี
ไม่มี chrome-php/chrome หากลบไลบรารีออกจาก autoloader แล้ว BrowserPool::getBrowser() จะ throw ChromeNotAvailableException พร้อมคำแนะนำในการแก้ไขที่แม่นยำ (ยืนยันโดย tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable)
เงื่อนไขเวอร์ชัน nextpdf/core: ^3.0 || ^5.2 — Artisan รองรับ core ทั้งสองสายเวอร์ชันหลัก ปักหมุดเวอร์ชัน core ให้ตรงกับที่แอปพลิเคชันกำหนดเป้าหมายไว้

หมายเหตุด้านความปลอดภัย

การติดตั้ง bridge จะนำโปรเซสภายนอก (Chrome) เข้ามาในขอบเขตความเชื่อถือ ตรวจสอบ /integrations/artisan/security-and-operations/ ก่อนเปิดเส้นทางการเรนเดอร์ใดๆ ที่รับ HTML จากผู้ใช้

ดูเพิ่มเติม

/integrations/artisan/overview/ (ภาพรวม)
/integrations/artisan/configuration/ (การกำหนดค่า)
/integrations/artisan/quickstart/ (เริ่มต้นใช้งานอย่างรวดเร็ว)
/integrations/artisan/chrome-renderer-setup/ (การตั้งค่าตัวเรนเดอร์ Chrome)
/integrations/artisan/security-and-operations/ (ความปลอดภัยและการดำเนินการ)