Laravel 整合自訂類庫三大方案：ClassMap、Files、PSR-4 完整指南

Laravel 專案常需整合非 Composer 套件、專案私有類庫或舊版程式碼。本文詳細說明三種整合方案：classmap 直接對應、files 載入助手函式、PSR-4 規範命名空間自動載入，含實戰配置與最佳實踐。

方案一：ClassMap - 直接對應類別檔案 (最簡單)

適用場景

單一類別檔案、無命名空間、舊版程式碼遷移、快速原型

步驟

1. 建立類別檔案：app/Libraries/Class/Message.php

   <?php
   class Message {
       public static function display() {
           return 'Hello from custom library!';
       }
   }

2. 修改 composer.json autoload.classmap

   "autoload": {
       "classmap": [
           "app/Commands",
           "app/Controllers",
           "app/Models",
           "app/Libraries/Class"  // 新增此行
       ]
   }

3. 重新產生自動載入對應表

   composer dump-autoload

4. 直接使用

   Message::display(); // 即可呼叫

方案二：Files - 載入全域助手函式

適用場景

工具函式、全域助手、常數定義、不屬於任何類別的程式碼

步驟

1. 建立函式檔案：app/Libraries/Functions/helpers.php

   <?php
   function v($data) {
       var_dump($data);
   }
   
   function config_path($path = '') {
       return config_path($path);
   }

2. 修改 composer.json autoload.files

   "autoload": {
       "classmap": [...],
       "files": [
           "app/Libraries/Functions/helpers.php"
       ]
   }

3. composer dump-autoload 後全域可用

   v($user); // 任何地方直接呼叫

替代方案：手動 require (控制載入時機)

// bootstrap/app.php 或 AppServiceProvider::register()
require_once app_path('Libraries/Functions/helpers.php');

// 或在中介層載入 (按需載入)
\App::before(function ($request) {
    require_once app_path('Libraries/Functions/helpers.php');
});

方案三：PSR-4 - 規範命名空間自動載入 (標準專案推薦)

適用場景

多檔案類庫、有命名空間、團隊協作、長期維護、符合現代 PHP 標準

目錄結構範例

app/Libraries/
└── MyApp/
    ├── Search/
    │   ├── Search.php              // namespace MyApp\Search;
    │   ├── SearchFacade.php
    │   └── SearchServiceProvider.php
    └── Payment/
        ├── Gateway.php
        └── Contracts/
            └── GatewayInterface.php

配置 composer.json

"autoload": {
    "classmap": [...],
    "psr-4": {
        "MyApp\\": "app/Libraries"  // 命名空間前綴 -> 實體目錄
    }
}

使用方式

use MyApp\Search\Search;
use MyApp\Payment\Gateway;

$search = new Search();
$gateway = new Gateway();

進階：整合 Laravel 服務容器與 Facade

// MyApp/Search/SearchServiceProvider.php
namespace MyApp\Search;

use Illuminate\Support\ServiceProvider;

class SearchServiceProvider extends ServiceProvider {
    public function register() {
        $this->app->singleton('search', function ($app) {
            return new Search($app['config']->get('search'));
        });
    }
    
    public function boot() {
        // 發布設定檔、遷移等
    }
}

// 設定檔 config/app.php 新增提供者
'providers' => [
    // ...
    MyApp\Search\SearchServiceProvider::class,
],

// 可選：註冊 Facade
'aliases' => [
    'Search' => MyApp\Search\SearchFacade::class,
];

方案選擇決策表

最佳實踐總結

1. 統一放置：建議所有自訂程式碼放在 app/Libraries 或 app/Packages
2. 命名空間：新專案一律採用 PSR-4，避免全域汙染
3. Composer 管理：可考慮將常用類庫發布為私有 Composer 套件
4. 測試覆蓋：自訂類庫同樣需編寫單元測試
5. 文件化：README、PHPDoc、變更日誌不可少