Laravel 採用 Composer 管理依賴,整合自有類庫有三種標準化路徑:直接實例化類(簡單)、全域 Helper 函數(便利)、PSR-4 獨立命名空間套件(專業、可復用、可發布)。本文詳細演示三種方案的配置步驟與最佳實踐。
// app/Libraries/Class/Message.php
<?php
namespace App\Libraries\Class;
class Message {
public static function display(): string {
return 'Hello from custom library!';
}
}
app/start/global.php(Laravel 4 風格,Laravel 5+ 已棄用,保留參考):
ClassLoader::addDirectories([
app_path('commands'),
app_path('controllers'),
app_path('models'),
app_path('database/seeds'),
app_path('libraries/class'), // 新增
]);
composer.json(現代標準,Laravel 5+ 必須):
"autoload": {
"classmap": [
"app/commands",
"app/controllers",
"app/models",
"app/database/migrations",
"app/database/seeds",
"app/tests/TestCase.php",
"app/libraries/class" // 新增
]
}
composer dump-autoload
use App\Libraries\Class\Message;
Message::display(); // "Hello from custom library!"
// app/Libraries/Function/helper.php
<?php
if (!function_exists('v')) {
function v(mixed $data): void {
echo '';
var_dump($data);
echo '';
}
}
if (!function_exists('dd')) {
function dd(mixed ...$vars): never {
foreach ($vars as $var) {
echo '';
var_dump($var);
echo '';
}
die;
}
}
"autoload": {
"classmap": [...],
"files": [
"app/libraries/function/helper.php" // 新增 files 區塊
]
}
composer dump-autoload
// app/start/global.php (L4) 或 bootstrap/app.php (L5+)
require app_path('libraries/function/helper.php');
或在中介軟體/ServiceProvider 中載入:
// App\Providers\AppServiceProvider::boot()
public function boot() {
if (app()->runningInConsole()) return;
require_once app_path('libraries/function/helper.php');
}
v(['user' => 'John', 'role' => 'admin']);
dd($request->all(), $user->permissions);
app/
└── Libraries/ # 或專案根目錄下的 src/
└── MyApp/ # 廠商/專案命名空間前綴 (Vendor/Package)
├── Search/
│ ├── Search.php
│ ├── SearchFacade.php
│ └── SearchServiceProvider.php
└── AnotherLib/
└── ...
// app/Libraries/MyApp/Search/Search.php
<?php
namespace MyApp\Search;
class Search {
public function query(string $keywords): array {
// 實作邏輯
return [];
}
}
"autoload": {
"classmap": [...],
"psr-4": {
"MyApp\\": "app/Libraries" // 命名空間前綴 -> 物理目錄
}
}
composer dump-autoload
use MyApp\Search\Search;
$search = new Search();
$results = $search->query('laravel');
| 維度 | 方案一:Classmap | 方案二:Helper Files | 方案三:PSR-4 Package |
|---|---|---|---|
| 適用複雜度 | 單一類/少數類 | 純函數集合 | 多類、多層級、有介面/契約 |
| 命名空間 | 可選(扁平) | 無(全域函數) | 強制 PSR-4 結構 |
| 自動載入機制 | 類映射表 (classmap) | 檔案包含 (files) | PSR-4 目錄掃描 |
| 發包潛力 | 無 | 無 | 高(可獨立發布 Packagist) |
| IDE 支援 | 良好 | 需 @function 註解 | 完美 |
| 測試友善度 | 中(靜態調用難 Mock) | 低(全域函數) | 高(介面綁定、容器解析) |
| 維護成本 | 低 | 低 | 中(需遵循規範) |
my-vendor/my-packagecomposer init 產生 composer.json,設定 "autoload": {"psr-4": {"MyVendor\\MyPackage\\": "src/"}}composer.json 加入本地/私有倉庫源:"repositories": [
{"type": "vcs", "url": "https://github.com/my-vendor/my-package"}
],
"require": {
"my-vendor/my-package": "^1.0"
}
執行 composer require my-vendor/my-package 即可跨專案共享。
require 檔案、硬編碼路徑、全域命名空間汙染app/Libraries 或 src 為自有代碼根目錄,嚴格遵循 PSR-4/PSR-12標準化的自動載入策略是 Laravel 專案可維護性的基石,請在專案初期即確立並貫徹執行。