HTML to PDF เส้นทางที่ง่าย

จนถึงตอนนี้ในเส้นทางบทเรียนนี้ คุณได้สร้างหน้าเอกสารทีละการเรียกใช้ เอกสารจำนวนมากอธิบายได้เร็วกว่าในรูปแบบ markup ซึ่งเป็นรูปแบบข้อความที่อิงแท็กและใช้กับหน้าเว็บ ในบทแนะนำนี้ คุณจะส่ง Hypertext Markup Language (HTML) ให้กับ NextPDF แล้วเอนจินจะวาดหน้าเอกสารให้คุณ

สิ่งที่คุณจะสร้าง

รายงานหนึ่งหน้าที่เรนเดอร์จากสตริง HTML เพียงสตริงเดียว ประกอบด้วยหัวเรื่องที่มีสี ย่อหน้าสั้นๆ และตารางที่มีแถวยอดรวม คุณจัดสไตล์ด้วย Cascading Style Sheets (CSS) ซึ่งเป็นภาษาชุดกฎที่ควบคุมลักษณะการแสดงผลของ markup ในบทแนะนำก่อนหน้านี้ คุณใช้ Application Programming Interface (API) แบบ fluent ซึ่งเป็นการเรียกเมธอดแบบต่อเนื่อง ในบทนี้คุณจะอธิบายเค้าโครงในรูปแบบ markup แทน แล้วเอนจินเดียวกันนี้จะเรนเดอร์ให้

ขั้นที่ 1: เรนเดอร์รายงานที่จัดสไตล์แล้วจาก HTML

สร้างไฟล์ชื่อ 01-html.php ในโฟลเดอร์โปรเจกต์ของคุณ ถัดจาก vendor แล้ววางสคริปต์ฉบับสมบูรณ์นี้:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

รันสคริปต์จากโฟลเดอร์โปรเจกต์:

php 01-html.php

คุณควรเห็นเอาต์พุตหนึ่งบรรทัด:

Wrote out/reading-report.pdf

เปิด out/reading-report.pdf ในโปรแกรมดู Portable Document Format (PDF) ใดก็ได้ หัวเรื่องเป็นสีน้ำเงินเข้ม และแถวหัวตารางถูกเติมด้วยสีเดียวกัน

เกิดอะไรขึ้นบ้าง

@mkdir(__DIR__ . '/out'); สร้างโฟลเดอร์เอาต์พุต เครื่องหมาย @ ซ่อนคำเตือนเมื่อโฟลเดอร์มีอยู่แล้ว การรันซ้ำจึงไม่แสดงข้อความรบกวน
Document::createStandalone(), setTitle() และ addPage() ทำงานเหมือนกับในบทแนะนำก่อนหน้าทุกประการ การเปลี่ยนมาใช้ markup ไม่ได้เปลี่ยนแปลงการตั้งค่าเอกสารแต่อย่างใด
writeHtml() อ่านสตริงของคุณหนึ่งครั้งจากบนลงล่าง และวาดแต่ละเอลิเมนต์ที่ตำแหน่งปัจจุบัน หัวเรื่องและย่อหน้ากลายเป็นข้อความที่จัดสไตล์แล้ว ตารางกลายเป็นแถวของเซลล์ที่มีเส้นขอบและวัดขนาดแล้ว
แอตทริบิวต์ style แบบ inline เป็นตัวพา CSS เอนจินเข้าใจคุณสมบัติทั่วไป เช่น color, background-color, text-align และ width
ไม่มีเบราว์เซอร์และไม่มีซอฟต์แวร์เพิ่มเติมเข้ามาเกี่ยวข้อง pipeline เป็น PHP ล้วนภายในเอนจิน สคริปต์จึงรันได้ทุกที่ที่การติดตั้ง Composer ของคุณรันได้

เอนจินรองรับชุดย่อยของ HTML และ CSS ที่ใช้งานได้จริง ไม่ใช่ทุกอย่างที่เบราว์เซอร์ยอมรับ สิ่งใดที่อยู่นอกชุดย่อยนั้นจะถูกข้ามไปอย่างเงียบๆ แทนที่จะเกิดข้อผิดพลาด เมทริกซ์การรองรับ CSS บันทึกสิ่งที่ครอบคลุมไว้อย่างแม่นยำ หากต้องการดูรายละเอียดเชิงลึกของ pipeline นี้ ดู เรนเดอร์ HTML ไปยังหน้า PDF

เมื่อใดควรใช้ HTML และเมื่อใดควรใช้ fluent API

ทั้งสองแนวทางทำงานบนเอนจินเดียวกัน ดังนั้นให้เลือกแนวทางที่เหมาะกับเอกสาร

เลือก writeHtml() เมื่อเอกสารอ่านดูเหมือนหน้าเว็บ ได้แก่ หัวเรื่อง ย่อหน้า รายการ และตาราง markup เขียนได้เร็วกว่าและแก้ไขง่ายกว่าสำหรับเพื่อนร่วมทีม
เลือก fluent API เมื่อคุณต้องการการจัดวางที่แม่นยำ เช่น ตำแหน่งตายตัวหรือเซลล์ที่วัดขนาดอย่างละเอียด markup ให้การไหลของเนื้อหา ส่วนการเรียกแบบ fluent ให้การควบคุม
ตรวจสอบ เมทริกซ์การรองรับ CSS ก่อนพึ่งพาคุณสมบัติใด เมื่อสไตล์ใดไม่ได้รับการรองรับ ให้สร้างส่วนนั้นด้วยการเรียกแบบ fluent แทน

ขอบเขตด้านความปลอดภัย

HTML จริงมักมาจากภายนอกโค้ดของคุณ เช่น จากฟอร์มหรือฐานข้อมูล ให้ปฏิบัติต่อ HTML นั้นเสมือนอินพุตที่ไม่น่าเชื่อถือ และตรวจสอบความถูกต้องหรือทำความสะอาดก่อนเรนเดอร์ โดยค่าเริ่มต้น pipeline ในตัวจะไม่รันสคริปต์ใดๆ และไม่ดึงทรัพยากรระยะไกล ค่าเริ่มต้นนี้ทำให้ตัวเรนเดอร์ระมัดระวังไว้ก่อนแม้ว่า markup จะไม่เป็นเช่นนั้น หากคุณต้องการตัวเลือกการเรนเดอร์ระดับเบราว์เซอร์ ดู เลือกเส้นทางของคุณ

หากมีบางอย่างผิดพลาด

Failed to open stream: No such file or directory มักหมายความว่าสคริปต์ไม่พบ vendor/autoload.php ให้รันจากโฟลเดอร์ที่คุณรัน Composer
สไตล์ที่หายไปมักเป็นคุณสมบัติที่อยู่นอกชุดย่อยที่รองรับ เอนจินจะข้ามสิ่งที่ไม่รองรับแทนที่จะล้มเหลว เปรียบเทียบ markup ของคุณกับ เมทริกซ์การรองรับ CSS
ข้อยกเว้นที่เกิดขึ้นระหว่างเรนเดอร์จะระบุปัญหาที่แน่ชัด ค้นหาได้ในเอกสารอ้างอิง ข้อผิดพลาดด้านการเรนเดอร์และอินพุต/เอาต์พุต

สำหรับกรณีอื่นๆ ให้เริ่มที่ คู่มือการแก้ปัญหา

ขั้นตอนถัดไป

ตอนนี้คุณสร้างเอกสารได้ทั้งแบบทีละการเรียกใช้และจาก markup จบเส้นทางบทเรียนนี้ด้วย จะไปต่อที่ไหน หน้านั้นจะแนะนำ cookbook เอกสารอ้างอิง และคู่มือต่างๆ ที่คุณจะใช้หลังจากเส้นทางนี้