Laravel 整合自訂類庫完整指南：三種載入方式與最佳實踐

雖然 Composer 與 Packagist 提供豐富套件生態，但專案仍常需整合非 Compliance 套件、內部私有類庫或專案專用工具類。本文詳細介紹 Laravel 整合自訂類庫的三種標準方式，涵蓋簡單類別、輔助函數、複雜套件結構。

方式一：可直接實例化的類別（Classmap 載入）

適用場景

• 單一或少量工具類別
• 不需命名空間管理
• Queue Worker 類別、服務類等

步驟

1. 建立類別檔案：app/libraries/class/Message.php

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

2. 註冊 Classmap 目錄：修改 app/start/global.php（Laravel 4）或 composer.json（Laravel 5+）

// Laravel 4: app/start/global.php
ClassLoader::addDirectories([
    app_path().'/commands',
    app_path().'/controllers',
    app_path().'/models',
    app_path().'/database/seeds',
    app_path().'/libraries/class', // 新增此行
]);

// Laravel 5+: composer.json
"autoload": {
    "classmap": [
        "app/commands",
        "app/controllers",
        "app/models",
        "app/database/migrations",
        "app/database/seeds",
        "app/tests/TestCase.php",
        "app/libraries/class" // 新增此行
    ]
}

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

composer dump-autoload

4. 直接使用

Message::display(); // 任意處直接呼叫

Queue Worker 類別放置建議

在 app/ 建立 queues/ 目錄，同樣加入 classmap，即可直接實例化佇列處理類。

方式二：可直接呼叫的輔助函數

適用場景

• 全域輔助函數（如 v($var) 替代 var_dump()）
• 不屬於任何類別的工具函數

步驟

1. 建立函數檔案：app/libraries/functions/helpers.php

<?php
// app/libraries/functions/helpers.php
function v($msg) {
    var_dump($msg);
}

function dd($data) {
    echo '<pre>';
    var_dump($data);
    echo '</pre>';
    die;
}

2. 註冊至 Composer 自動載入（推薦）

// composer.json
"autoload": {
    "classmap": [...],
    "files": [
        "app/libraries/functions/helpers.php" // 關鍵：files 區塊
    ]
}

3. 執行重新生成

composer dump-autoload

替代方案：手動 require

// 方案 A: app/start/global.php 末尾
require app_path().'/libraries/functions/helpers.php';

// 方案 B: 透過 Filter 延遲載入
App::before(function ($request) {
    require "{$GLOBALS['app']['path.base']}/app/libraries/functions/helpers.php";
});

使用方式

v('hello world'); // 任意處直接呼叫
dd($user->toArray());

方式三：複雜結構類庫（PSR-0/PSR-4 標準）

適用場景

• 多檔案、多命名空間的完整類庫
• 包含 Facade、Service Provider 的 Laravel 套件雛形
• 團隊共用核心元件

目錄結構範例

app/libraries/
└── MyApp/
    └── Search/
        ├── Search.php              // 命名空間 MyApp\Search
        ├── SearchFacade.php
        └── SearchServiceProvider.php

Search.php 範例

<?php
// app/libraries/MyApp/Search/Search.php
namespace MyApp\Search;

class Search {
    public function query($keywords) {
        // 搜尋邏輯
        return "搜尋結果: {$keywords}";
    }
}

修改 composer.json 註冊 PSR-4

"autoload": {
    "classmap": [
        "app/commands",
        "app/controllers",
        "app/models",
        "app/libraries",  // 保留 classmap 掃描
        "app/database/migrations",
        "app/database/seeds",
        "app/tests/TestCase.php"
    ],
    "psr-4": {
        "MyApp\\": "app/libraries"  // 關鍵：PSR-4 對應
    }
}

重新生成並使用

composer dump-autoload

// 使用
$search = new MyApp\Search\Search();
echo $search->query('Laravel 教學');

三種方式比較與選型指南

進階：建立 Laravel 專用套件結構

若類庫需深度整合 Laravel（路由、配置、視圖、遷移），建議遵循套件開發標準：

packages/
└── vendor-name/
    └── package-name/
        ├── src/
        │   ├── PackageServiceProvider.php
        │   ├── Facades/
        │   └── ...
        ├── config/
        ├── views/
        ├── migrations/
        ├── routes.php
        └── composer.json

本地套件開發工作流

// 專案 composer.json
"repositories": [
    {
        "type": "path",
        "url": "./packages/vendor-name/package-name"
    }
],
"require": {
    "vendor-name/package-name": "*"
}

最佳實踐總結

1. 優先考慮 Composer 套件化：即使內部使用，標準結構利於維護與分享
2. 統一存放位置：建議 app/Libraries 或 app/Services，避免散落
3. 命名空間規範：PSR-4 對應目錄結構，類別名稱 StudlyCase
4. 服務提供者註冊：複雜類庫透過 Service Provider 綁定至容器
5. Facade 簡化呼叫：提供靜態介面存取服務
6. 配置檔發布：php artisan vendor:publish 讓使用者自訂設定

總結

Laravel 整合自訂類庫三大路徑：

• Classmap：簡單類別快速可用
• Files：全域函數零門檻
• PSR-4：專業級結構、長期維護首選

隨專案成長，建議逐步從前兩者遷移至 PSR-4 結構，並考慮抽離為獨立 Composer 套件。良好的類庫組織不僅提升開發效率，更是團隊協作與技術傳承的基礎設施。