เริ่มใช้งาน Artisan อย่างรวดเร็ว

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

แนบ ChromeRendererConfig กับเอกสาร NextPDF เรียกใช้ writeHtmlChrome() แล้วบันทึกเป็นไฟล์ Portable Document Format (PDF) Chrome จะเรนเดอร์ Hypertext Markup Language (HTML) และบริดจ์จะนำเข้าผลลัพธ์เป็น Form XObject โดยข้อความยังคงเลือกได้

ภาพรวมเชิงแนวคิด

writeHtmlChrome() เป็นเมธอดบน Document ของคอร์ NextPDF โดย concern ชื่อ HasTextOutput เป็นผู้จัดเตรียมเมธอดนี้ เมธอดนี้จะตรวจสอบความถูกต้องของอินพุตและระบุตัวเรนเดอร์ของ Artisan ที่จะใช้ จากนั้นส่ง HTML ไปยัง Chrome แยกวิเคราะห์ PDF ที่ได้กลับมา และฝังหน้า 0 เป็น Form XObject ที่ตำแหน่งเคอร์เซอร์ปัจจุบัน ซิกเนเจอร์สาธารณะคือ writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — ตรวจสอบยืนยันกับ nextpdf/coresrc/Core/Concerns/HasTextOutput.php แล้ว

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

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

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

นี่คือลำดับการทำงานหลักจาก README.md ของแพ็กเกจ Chrome จะจัดการเค้าโครง flex ของ Cascading Style Sheets (CSS) และตัวเลขในผลลัพธ์ยังคงเป็นข้อความที่เลือกได้ เนื่องจากหน้าถูกฝังเป็น Form XObject ไม่ใช่ภาพแรสเตอร์

ขนาดหน้าแบบกำหนดเอง

ส่งค่าความกว้างและความสูงอย่างชัดเจนในหน่วย PDF point เพื่อให้พอดีกับหน้าขนาดคงที่ (ตัวอย่างนี้ใช้ A4):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

เมื่อระบุค่าทั้งสอง Chrome จะพิมพ์ตามขนาดกระดาษนั้นพอดี เมื่อละเว้นความสูง (หรือส่ง null) บริดจ์จะปรับให้พอดีกับความสูงของเนื้อหาที่วัดได้ และเพิ่มบัฟเฟอร์สำรองเล็กน้อยเพื่อรองรับการจัดเรียงใหม่ ดู /integrations/artisan/production-usage/ เพื่อทราบเหตุผลที่มีบัฟเฟอร์นี้และกรณีที่ควรแทนที่ค่า

สิ่งที่จะได้รับ

คุณสมบัติ	พฤติกรรม
ข้อความ	เลือกได้และค้นหาได้ (ข้อความแบบเวกเตอร์ ไม่ใช่แบบแรสเตอร์)
สไตล์ชีตแบบเรียงซ้อน (Cascading Style Sheets, CSS)	เค้าโครงที่ Chrome จัดการ: flexbox, grid, ตัวเลือกที่ซับซ้อน, เว็บฟอนต์ผ่านค่า data Uniform Resource Identifier (URI)
เครือข่าย	ไม่มีการดึงทรัพยากรย่อย ดังนั้น Uniform Resource Locator (URL) ระยะไกลจึงไม่โหลด (ดู /integrations/artisan/security-and-operations/)
หน้า	หน้า 0 ของผลลัพธ์จาก Chrome จะถูกนำเข้า

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

• HTML ว่างเปล่าไม่ก่อให้เกิดผลใดๆ writeHtmlChrome('') จะคืนค่าเอกสารเดิมโดยไม่เปลี่ยนแปลง (ตรวจสอบยืนยันใน HasTextOutput::writeHtmlChrome)
• ยังไม่มีหน้า หากเอกสารยังไม่มีหน้า writeHtmlChrome() จะเพิ่มหน้าหนึ่งหน้าก่อนเรนเดอร์
• ทรัพยากรระยะไกลจะไม่โหลด <img src="https://..."> จะเรนเดอร์ออกมาว่างเปล่า ฝังทรัพยากรแบบอินไลน์เป็น URI ชนิด data: นี่เป็นมาตรการแยกเครือข่าย ไม่ใช่ข้อบกพร่อง ดู /integrations/artisan/security-and-operations/
• ไม่มีบริดจ์ หากไม่ได้ติดตั้ง nextpdf/artisan คอร์จะยกข้อยกเว้นเกี่ยวกับเค้าโครงแทนการเกิดข้อผิดพลาดร้ายแรง

ประสิทธิภาพ

การเรียกครั้งแรกจะรวมเวลาเริ่มต้น Chrome และเวลาจัดเค้าโครงไว้ด้วย การเรียกครั้งต่อๆไปจะนำกระบวนการ Chrome ที่กำลังทำงานอยู่กลับมาใช้ซ้ำผ่าน BrowserPool สำหรับงานแบบแบตช์หรือเวิร์กเกอร์ที่ทำงานระยะยาว ให้อ่านคำแนะนำเกี่ยวกับวงจรชีวิตและทรัพยากรในหน้า /integrations/artisan/production-usage/

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

คู่มือเริ่มต้นอย่างรวดเร็วนี้ใช้ HTML ที่เชื่อถือได้และกำหนดไว้ในโค้ดโดยตรง ก่อนส่ง HTML ใดๆที่ผู้ใช้มีผลต่อเนื้อหาไปยัง writeHtmlChrome() ให้อ่าน /integrations/artisan/security-and-operations/ บริดจ์จะแยกการเข้าถึงเครือข่ายออก แต่การเรนเดอร์ HTML ยังคงมีพื้นผิวการโจมตีอยู่

บริบทเชิงพาณิชย์

วิธีนี้สร้าง PDF จาก HTML โดยใช้บริดจ์โอเพนซอร์ส หากต้องการฝังไฟล์ Extensible Markup Language (XML) ของ e-invoice ที่เป็นไปตามข้อกำหนดลงในเอกสารเดียวกัน ระดับ Premium Pro จะจัดเตรียมตัวฝังให้ การใช้งานผ่านโอเพนซอร์สจะไม่ได้รับผลกระทบหากไม่มี Premium

ดูเพิ่มเติม

• /integrations/artisan/install/ — การติดตั้ง
• /integrations/artisan/configuration/ — การกำหนดค่า
• /integrations/artisan/production-usage/ — การใช้งานในระบบโปรดักชัน
• /integrations/artisan/troubleshooting/ — การแก้ไขปัญหา
• /integrations/artisan/security-and-operations/ — ความปลอดภัยและการดำเนินการ