安裝 NextPDF Laravel 套件

快速概覽

使用 Composer 安裝 nextpdf/laravel。自動探索（auto-discovery）會替你註冊服務提供者。接著發布組態檔，讓你可以編輯它。此套件會自行偵測任何選用的 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`

此套件透過單一份 PSR-4 對應表自動載入。NextPDF\Laravel\ 前綴會 resolve（解析）到 src/Laravel/。這遵循 PSR-4 將前綴對應至基底目錄的規則（PSR-4 §3）。

概念總覽

你執行 composer require 之後，Laravel 套件自動探索會讀取此套件的 extra.laravel 區塊（位於其 composer.json 中）。接著它會替你註冊提供者與外觀（facade）別名，因此你不需要手動編輯 config/app.php。該區塊如下：

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

Laravel 的套件文件說明了此機制如何運作。extra.laravel.providers 陣列會自動註冊服務提供者，而 extra.laravel.aliases 陣列會自動註冊外觀別名（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 寫入你的應用程式。提供者也會把套件預設組態合併到 nextpdf 鍵底下（於 register() 期間），因此即使你尚未發布，套件也能運作。發布只是讓此檔案在你的應用程式中變得可以編輯。

確認提供者已被探索到：

php artisan package:discover --ansi

程式碼範例 — 正式環境

為了讓部署可重現，請鎖定限制條件。只有在你自行註冊提供者時，才需要明確停用探索：

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

停用探索時，請自行在 bootstrap/providers.php 中註冊提供者：

<?php

declare(strict_types=1);

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

選用擴充套件

此套件會在 suggest 底下列出選用的搭配套件（位於其 composer.json 中）。此套件會在執行階段偵測它們：

套件	安裝後的效果	偵測點
`nextpdf/artisan`	當 Chrome 工廠類別存在時，Chrome CDP HTML renderer（渲染器）組態會套用到文件繫結	`NextPdfServiceProvider::register()` 會檢查 Chrome 瀏覽器工廠類別
`nextpdf/premium`	簽章（PAdES B-B）、PDF/A 封存與電子發票合約具體實作，會透過既有的容器鍵解析	在第一次容器解析時延遲解析

以相同方式安裝擴充套件：

composer require nextpdf/artisan

不需要再做任何接線設定。提供者會在下一次註冊時偵測到這個擴充套件。

邊界案例與陷阱

發布是冪等的。它不會覆寫既有的 config/nextpdf.php。當你想刻意覆寫它時，請加上 --force。
提供者是延遲載入的，所以執行一次可確認套件存在的 php artisan package:discover 就足夠了。繫結本身要到第一次解析時才會出現。
此套件支援 nextpdf/core，且 ^3.0 與 ^5.2 兩條主版本線皆受支援。請把 core 限制條件對齊你的應用程式所鎖定的版本線。兩者的 Laravel 配接層介面都相同。
README 徽章與 composer.json 在 Apache-2.0 上保持一致。此套件已從 LGPL-3.0-or-later 重新授權。遷移前已標記的版本仍維持在先前的授權條款下（見 CHANGELOG.md）。

效能

解析 nextpdf/core 佔了 composer require 成本的主要部分。提供者註冊不會增加可量測的啟動成本，因為所有繫結都是延遲載入的閉包。第一次解析的建構成本記載於 /integrations/laravel/boot-and-discovery/。

安全性注意事項

請從正規的 Packagist 套件 nextpdf/laravel 安裝。此套件隨附 SPDX REUSE 標頭與一份 Apache-2.0 NOTICE 檔案。請在 composer.json 中鎖定限制條件，並提交 composer.lock，讓已部署的 worker 解析到經過驗證的相依樹。

符合性

主張	來源	條款	參考 ID
PSR-4 前綴對應到基底目錄	PSR-4 自動載入器	§3

Laravel 自動探索的鍵名稱已比對官方 Laravel 12 套件開發文件並加以佐證（https://laravel.com/docs/12.x/packages 於 2026-05-18 擷取）。

商業情境

nextpdf/premium 加入了簽章、PDF/A 與電子發票的具體實作。這是選用的 Enterprise 能力。此處所記載的 Core 套件不需要任何程式碼變更即可採用它。見 https://nextpdf.dev/get-license/?intent=laravel-signing。

另見

/integrations/laravel/overview/ — 套件架構與繫結對照表
/integrations/laravel/quickstart/ — 第一個可執行的控制器
/integrations/laravel/configuration/ — 逐一說明每個組態鍵
/integrations/laravel/boot-and-discovery/ — 探索內部機制與繫結生命週期