ตั้งค่า NextPDF และเรนเดอร์ PDF ฉบับแรกของคุณ

NextPDF คือไลบรารี PHP ที่สร้างไฟล์ PDF (Portable Document Format) ในบทแนะนำนี้จะติดตั้งลงในโฟลเดอร์เปล่าและเรนเดอร์เอกสารหนึ่งหน้า ฉบับแรก สิ่งที่ต้องมีคือเทอร์มินัลและเวลาประมาณสิบนาที

สิ่งที่จะสร้าง

จะสร้างโปรเจกต์เล็กๆที่มีสคริปต์หนึ่งไฟล์คือ 01-hello.php สคริปต์นี้เรนเดอร์หน้าเดียวที่มีบรรทัดหัวเรื่องตัวหนาและย่อหน้าหนึ่งย่อหน้า บันทึกผลลัพธ์เป็น out/hello.pdf ระหว่างทางจะได้เรียนรู้คำสั่งสองคำสั่ง ที่ยืนยันว่าการติดตั้งสมบูรณ์ดี

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

ขั้นตอนที่ 1: สร้างโปรเจกต์และติดตั้ง NextPDF

Composer คือตัวจัดการแพ็กเกจสำหรับ PHP โดยจะดาวน์โหลดไลบรารีเข้าสู่ โปรเจกต์และสร้าง autoloader ขึ้นมา autoloader คือไฟล์ PHP ขนาดเล็ก ที่ค้นหาคลาสของไลบรารีให้ จึงไม่ต้องเขียนรายการ include ยาวๆด้วยตนเอง

เปิดเทอร์มินัลแล้วรันคำสั่งสามคำสั่งนี้:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer จะแสดงความคืบหน้าขณะค้นหาและดาวน์โหลดแพ็กเกจ บรรทัดที่แสดง จะแตกต่างกันไปตามเวอร์ชันของ Composer และแคชในเครื่อง การติดตั้งที่สำเร็จ จะจบโดยไม่มีข้อความแสดงข้อผิดพลาดและมีลักษณะประมาณนี้:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

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

Composer สร้างสามสิ่งขึ้นในโฟลเดอร์ composer.json บันทึกว่าโปรเจกต์นี้ ขึ้นอยู่กับเอนจิน composer.lock ตรึงเวอร์ชันที่ติดตั้งไว้อย่างแน่นอน เพื่อให้การติดตั้งครั้งถัดไปได้โค้ดชุดเดิม โฟลเดอร์ vendor/ เก็บแพ็กเกจ ที่ดาวน์โหลดมา รวมถึง vendor/autoload.php สคริปต์จะโหลดไฟล์เพียง ไฟล์เดียวนั้น แล้วทุกคลาสของเอนจินก็พร้อมใช้งาน

Composer ยังตรวจสอบการตั้งค่า PHP ระหว่างการติดตั้งด้วย เอนจินจะประกาศ ส่วนขยาย PHP ที่ต้องใช้ ส่วนขยายคือโมดูลเสริมที่มีมาในตัว PHP หากขาด ส่วนขยายใด Composer จะหยุดและระบุชื่อส่วนขยายนั้น แทนที่จะปล่อยให้การ ติดตั้งเสียหาย

ขั้นตอนที่ 2: เรนเดอร์ PDF ฉบับแรกของคุณ

สร้างไฟล์ชื่อ 01-hello.php ไว้ข้างๆ composer.json แล้ววางโปรแกรม ฉบับสมบูรณ์นี้ลงไป:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

echo "Wrote out/hello.pdf\n";

รัน:

php 01-hello.php

ควรเห็นเพียงหนึ่งบรรทัดเท่านั้น:

Wrote out/hello.pdf

เปิด out/hello.pdf ในโปรแกรมดู PDF ใดก็ได้ จะเห็นบรรทัดหัวเรื่องตัวหนา พร้อมย่อหน้าอยู่ด้านล่าง และโปรแกรมดูส่วนใหญ่จะแสดง “Hello from NextPDF” ในแถบชื่อหน้าต่าง

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

ไล่ดูสคริปต์จากบนลงล่าง:

require โหลด autoloader ของ Composer เพื่อให้คลาส Document ถูกอ้างอิงได้
@mkdir สร้างโฟลเดอร์ out/ เครื่องหมาย @ ที่นำหน้าทำให้สคริปต์ไม่แจ้งข้อผิดพลาด เมื่อโฟลเดอร์มีอยู่แล้ว จึงรันซ้ำได้
Document::createStandalone() คืนค่าเอกสารใหม่ ออกแบบมาสำหรับสคริปต์ command-line สั้นๆแบบนี้โดยเฉพาะ
setTitle() กำหนดชื่อเอกสาร ซึ่งโปรแกรมดูจะแสดงในแถบชื่อหน้าต่าง
addPage() เพิ่มหน้าเปล่าหนึ่งหน้าและวางเคอร์เซอร์ไว้ที่มุมบนซ้าย
setFont() เลือกตระกูลฟอนต์ สไตล์ และขนาดเป็นพอยต์ พอยต์คือหน่วย มาตรฐานสำหรับขนาดฟอนต์ในงานพิมพ์ 'B' หมายถึงตัวหนา และ '' หมายถึงตัวปกติ ตระกูลชื่อ helvetica มีมาในตัว จึงไม่ต้องใช้ไฟล์ฟอนต์
cell() เขียนข้อความหนึ่งบรรทัดที่ตำแหน่งเคอร์เซอร์ ความกว้างเท่ากับ 0 หมายถึง “ยืดจนถึงขอบขวา” newLine: true เลื่อนเคอร์เซอร์ลงด้านล่าง หลังจากนั้น เหมือนการกด Enter
save() สร้าง PDF ที่เสร็จสมบูรณ์และเขียนลงดิสก์

หนึ่งเอกสารสร้างหนึ่งไฟล์ เมื่อต้องการ PDF ไฟล์ที่สอง ให้สร้างเอกสารใหม่ แทนการนำเอกสารเดิมมาใช้ซ้ำ

ขั้นตอนที่ 3: ตรวจสอบการติดตั้ง

การตรวจสอบสั้นๆสองอย่างยืนยันว่าการติดตั้งนี้จะยังทำงานได้ต่อไป ไม่ใช่แค่กับสคริปต์เดียว

อย่างแรก แสดงรายการส่วนขยายที่ PHP มีอยู่:

php -m

มองหา curl, gd, intl, mbstring, openssl และ zlib ในรายการ เอนจินพึ่งพาหกส่วนขยายนี้ Composer ได้ตรวจสอบไปแล้วในขั้นตอนที่ 1 ดังนั้นทั้งหมดควรปรากฏ

อย่างที่สอง รันการตรวจสอบสุขภาพของเอนจินเอง:

vendor/bin/nextpdf doctor

บน Windows ให้เรียก vendor\bin\nextpdf doctor แทน คำสั่งนี้จะตรวจสอบ เวอร์ชัน PHP ส่วนขยาย โฟลเดอร์ชั่วคราว และการกำหนดค่า การตรวจสอบแต่ละ รายการจะแสดง [OK], [WARN] หรือ [FAIL] ตามด้วยผลสรุปโดยรวมหนึ่งรายการ

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

อ่านบล็อก Extensions ก่อน บรรทัด [OK] หกบรรทัดที่ระบุ curl, gd, intl, mbstring, openssl และ zlib หมายความว่าการติดตั้งพร้อมสำหรับ ทุกบทแนะนำที่ตามมา

รายงานยังแสดงรายการความสามารถของเอนจินด้วย บนการติดตั้ง Core แบบฟรี ความสามารถที่เป็นของแพ็กเกจเชิงพาณิชย์จะแสดง [FAIL] พร้อมข้อความ ระบุชื่อแพ็กเกจที่ให้ความสามารถนั้น สิ่งนี้เป็นเรื่องปกติในที่นี้ และอาจทำให้ ผลสรุปโดยรวมกลายเป็น UNHEALTHY แม้ว่าการติดตั้ง Core จะปกติดี สำหรับ บทแนะนำเหล่านี้ บล็อก Extensions คือสัญญาณที่สำคัญ

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

เทียบอาการที่พบกับกรณีทั่วไปเหล่านี้ก่อน:

composer: command not found หมายความว่าไม่มี Composer หรือไม่อยู่ใน PATH ติดตั้งจาก getcomposer.org แล้วทำ ขั้นตอนที่ 1 ซ้ำ
Failed opening required '.../vendor/autoload.php' หมายความว่าสคริปต์ รันนอกโฟลเดอร์โปรเจกต์ หรือการติดตั้งยังไม่เสร็จ เข้าไปในโฟลเดอร์จาก ขั้นตอนที่ 1 แล้วรัน composer install
หาก Composer หยุดระหว่างขั้นตอนที่ 1 และระบุส่วนขยาย PHP ที่ขาดหายไป ให้เปิดใช้งานส่วนขยายนั้นใน php.ini ยืนยันด้วย php -m แล้วทำการ ติดตั้งซ้ำ
บรรทัด [FAIL] ในบล็อก Extensions ของ doctor ระบุส่วนขยาย PHP ที่ขาดหายไป ให้เปิดใช้งานใน php.ini ยืนยันด้วย php -m แล้วรัน doctor อีกครั้ง บรรทัด [FAIL] ของความสามารถที่ระบุแพ็กเกจเชิงพาณิชย์เป็นเรื่อง ปกติบนการติดตั้ง Core และไม่ต้องดำเนินการใดในที่นี้

สำหรับกรณีอื่นๆ ให้เริ่มจาก ฐานความรู้การแก้ไขปัญหา หากสคริปต์เกิดข้อยกเว้น ให้ค้นหาคลาสของข้อยกเว้นนั้นใน เอกสารอ้างอิงข้อผิดพลาด ข้อผิดพลาดของผู้เริ่มต้น ส่วนใหญ่จะอยู่ใน ข้อผิดพลาดทั่วไป

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

ขณะนี้มีการติดตั้งที่ใช้งานได้และไฟล์ที่เรนเดอร์ฉบับแรกแล้ว ทำต่อด้วย ข้อความ ฟอนต์ และพื้นฐานของหน้า เพื่อควบคุมขนาดหน้า ฟอนต์ในตัว สี และการจัดแนว