ติดตั้งแพ็กเกจ NextPDF สำหรับ Laravel

ภาพรวมโดยสังเขป

ติดตั้ง nextpdf/laravel ด้วย Composer แล้วการค้นพบอัตโนมัติ (auto-discovery) ของ Laravel จะลงทะเบียน service provider ให้โดยอัตโนมัติ เมื่อต้องการแก้ไขการตั้งค่า ให้เผยแพร่ไฟล์การกำหนดค่าก่อน แพ็กเกจจะตรวจหาส่วนขยาย NextPDF ที่เป็นตัวเลือกโดยอัตโนมัติ

การติดตั้ง

composer require nextpdf/laravel

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

ข้อกำหนด	ข้อจำกัด
PHP	>=8.4 <9.0
laravel/framework	^12.0
nextpdf/core	^3.0 || ^5.2
psr/http-client	^1.0

แพ็กเกจจะโหลดอัตโนมัติผ่าน PHP Standard Recommendation 4 (PSR-4) map เพียงรายการเดียว โดยคำนำหน้า NextPDF\Laravel\ จะถูกแมปไปยัง src/Laravel/ การทำงานนี้เป็นไปตามกฎ prefix-to-base-directory ของ PSR-4 (PSR-4 §3)

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

เมื่อเรียกใช้ composer require แล้ว การค้นพบแพ็กเกจอัตโนมัติของ Laravel จะอ่านบล็อก extra.laravel ใน composer.json ของแพ็กเกจนี้ จากนั้นลงทะเบียน provider และ facade alias ให้โดยอัตโนมัติ จึงไม่จำเป็นต้องแก้ไข config/app.php ด้วยตนเอง บล็อกดังกล่าวมีลักษณะดังนี้:

resource: composer.json (extra.laravel)

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

เอกสารแพ็กเกจของ Laravel อธิบายพฤติกรรมนี้ไว้ว่า อาร์เรย์ extra.laravel.providers จะลงทะเบียน service provider โดยอัตโนมัติ และอาร์เรย์ extra.laravel.aliases จะลงทะเบียน facade alias โดยอัตโนมัติ (คู่มือการพัฒนาแพ็กเกจ Laravel 12 https://laravel.com/docs/12.x/packages เข้าถึงเมื่อ 2026-05-18)

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

ใช้แท็ก nextpdf-config เพื่อเผยแพร่ไฟล์การกำหนดค่า โดยชื่อแท็กนี้กำหนดไว้ใน NextPdfServiceProvider::boot()

php artisan vendor:publish --tag=nextpdf-config

คำสั่งนี้จะเขียน config/nextpdf.php ลงในแอปพลิเคชัน provider ยังรวมการกำหนดค่าเริ่มต้นของแพ็กเกจไว้ภายใต้คีย์ nextpdf ระหว่าง register() ด้วย แพ็กเกจจึงทำงานได้ก่อนมีการเผยแพร่ไฟล์ การเผยแพร่จะทำให้มีไฟล์ที่แก้ไขได้ภายในแอปพลิเคชัน

ตรวจยืนยันว่า Laravel ค้นพบ provider แล้ว:

php artisan package:discover --ansi

ตัวอย่างโค้ด — โปรดักชัน

ตรึงข้อจำกัดเพื่อให้การปรับใช้ทำซ้ำได้ ปิดการค้นพบอย่างชัดเจนเฉพาะกรณีที่ลงทะเบียน provider ด้วยตนเองเท่านั้น:

resource: opt-out pattern (Laravel 12 packages guide)

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "nextpdf/laravel"
      ]
    }
  }
}

เมื่อปิดการค้นพบแล้ว ให้ลงทะเบียน provider ด้วยตนเองใน bootstrap/providers.php:

resource: bootstrap/providers.php (manual registration)

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

ส่วนขยายที่เป็นตัวเลือก

แพ็กเกจนี้ระบุแพ็กเกจคู่หูที่เป็นตัวเลือกไว้ภายใต้ suggest ใน composer.json ของแพ็กเกจ และจะตรวจหาแพ็กเกจคู่หูที่ติดตั้งไว้ในขณะรันไทม์:

แพ็กเกจ	ผลเมื่อติดตั้ง	จุดตรวจหา
nextpdf/artisan	เมื่อมีคลาส Chrome factory อยู่ การกำหนดค่าตัวเรนเดอร์ Hypertext Markup Language (HTML) ผ่าน Chrome DevTools Protocol (CDP) จะถูกนำไปใช้กับ binding ของเอกสาร	NextPdfServiceProvider::register() จะตรวจหาคลาส Chrome browser-factory
nextpdf/premium	คีย์ container ที่มีอยู่จะถูกผูกกับคอนกรีตสำหรับการลงนาม PDF Advanced Electronic Signatures (PAdES B-B) การจัดเก็บถาวรแบบ PDF/A และสัญญา e-invoice	resolve แบบ lazy เมื่อมีการ resolve container ครั้งแรก

ติดตั้งส่วนขยายด้วยวิธีเดียวกัน:

composer require nextpdf/artisan

ไม่จำเป็นต้องเชื่อมต่อเพิ่มเติม provider จะตรวจพบส่วนขยายในการลงทะเบียนรอบถัดไป

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

• การเผยแพร่เป็นแบบ idempotent และจะไม่เขียนทับ config/nextpdf.php ที่มีอยู่แล้ว เพิ่ม --force เมื่อต้องการเขียนทับโดยตั้งใจ
• provider เป็นแบบ deferred ดังนั้นการเรียกใช้ php artisan package:discover ที่สำเร็จจึงเพียงพอสำหรับยืนยันแพ็กเกจ ตัว binding จะยังไม่ปรากฏจนกว่าจะถูก resolve ครั้งแรก
• แพ็กเกจรองรับ nextpdf/core ทั้งเมเจอร์ไลน์ ^3.0 และ ^5.2 กำหนดข้อจำกัดของ core ให้ตรงกับไลน์ที่แอปพลิเคชันตรึงไว้ พื้นผิวของ Laravel adapter เหมือนกันในทั้งสองไลน์
• ป้าย README และ composer.json ระบุ Apache-2.0 ตรงกัน แพ็กเกจได้รับการเปลี่ยนสัญญาอนุญาตจาก LGPL-3.0-or-later เวอร์ชันที่ติดแท็กก่อนการย้ายยังคงอยู่ภายใต้สัญญาอนุญาตเดิม (ดู CHANGELOG.md)

ประสิทธิภาพ

การ resolve nextpdf/core เป็นต้นทุนหลักของ composer require การลงทะเบียน provider ไม่เพิ่มต้นทุนการบูตที่วัดได้ เนื่องจาก binding ทั้งหมดเป็น deferred closure ดู /integrations/laravel/boot-and-discovery/ สำหรับต้นทุนการสร้างเมื่อมีการ resolve ครั้งแรก

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

ติดตั้งจากแพ็กเกจ Packagist ทางการ nextpdf/laravel แพ็กเกจนี้มาพร้อมส่วนหัว Software Package Data Exchange (SPDX) REUSE และไฟล์ Apache-2.0 NOTICE ตรึงข้อจำกัดไว้ใน composer.json และคอมมิต composer.lock เพื่อให้เวิร์กเกอร์ที่ปรับใช้แล้ว resolve dependency tree ที่ผ่านการตรวจสอบ

ความสอดคล้อง

การกล่าวอ้าง	แหล่งที่มา	ข้อกำหนด	รหัสอ้างอิง (reference_id)
คำนำหน้า PSR-4 แมปไปยังไดเรกทอรีฐาน	PSR-4 Autoloader	§3

ชื่อคีย์สำหรับการค้นพบอัตโนมัติของ Laravel ได้รับการตรวจสอบกับเอกสารการพัฒนาแพ็กเกจ Laravel 12 ที่เป็นทางการ (https://laravel.com/docs/12.x/packages เข้าถึงเมื่อ 2026-05-18)

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

nextpdf/premium เพิ่มคอนกรีตสำหรับการลงนาม, PDF/A และ e-invoice เป็นความสามารถระดับ Enterprise ที่เป็นตัวเลือก สามารถนำมาใช้ได้โดยไม่ต้องเปลี่ยนแพ็กเกจ Core ที่อธิบายไว้ที่นี่ ดู https://nextpdf.dev/get-license/?intent=laravel-signing

ดูเพิ่มเติม

• /integrations/laravel/overview/ — สถาปัตยกรรมแพ็กเกจและตาราง binding
• /integrations/laravel/quickstart/ — controller ตัวแรกที่รันได้
• /integrations/laravel/configuration/ — คำอธิบายของคีย์การกำหนดค่าทุกคีย์
• /integrations/laravel/boot-and-discovery/ — กลไกภายในของการค้นพบและอายุการใช้งานของ binding