輔助函式 - Knowledge of Laravel

輔助函式是什麼

Laravel 提供了大量的全域 PHP 函式（輔助函式）。它們大多是框架自身內部所使用，但你也可以在應用程式中自由運用。輔助函式大致分為以下幾類：

陣列 / 物件：Arr:: 類別與 data_get() 等函式
數字：Number:: 類別
路徑：app_path()、storage_path() 等取得路徑的函式
URL：route()、url()、asset() 等 URL 產生函式
其他：config()、collect()、auth() 等常用工具

輔助函式無須 use 宣告即可從任何地方呼叫。若要使用 Arr 或 Number 類別，則需 use Illuminate\Support\Arr; 等 import。

陣列輔助（Arr 類別）

`Arr::get()` — 以點記法讀取巢狀值

安全地以點記法（foo.bar.baz）從多維陣列讀取巢狀值。鍵不存在時可回傳預設值。

use Illuminate\Support\Arr;

$config = [
    'database' => [
        'connections' => [
            'mysql' => ['host' => '127.0.0.1', 'port' => 3306],
        ],
    ],
];

$host = Arr::get($config, 'database.connections.mysql.host');
// '127.0.0.1'

// 鍵不存在時的預設值
$charset = Arr::get($config, 'database.connections.mysql.charset', 'utf8mb4');
// 'utf8mb4'

全域函式 data_get() 有同樣的功能，還支援 Arrayable 物件（如 Eloquent 關聯），適用範圍更廣。

`Arr::set()` — 對巢狀陣列設定值

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::set($array, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

`Arr::has()` — 檢查鍵是否存在

use Illuminate\Support\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$hasName = Arr::has($array, 'product.name');
// true

// 檢查多個鍵是否全部存在
$hasAll = Arr::has($array, ['product.name', 'product.price']);
// true

`Arr::only()` / `Arr::except()` — 篩選或排除鍵

適合從請求資料或設定陣列中只取出必要的鍵，或排除不必要的鍵。

use Illuminate\Support\Arr;

$user = [
    'id' => 1,
    'name' => '山田太郎',
    'email' => '[email protected]',
    'password' => 'secret',
    'role' => 'admin',
];

// 只取出必要的鍵
$safe = Arr::only($user, ['id', 'name', 'email']);
// ['id' => 1, 'name' => '山田太郎', 'email' => '[email protected]']

// 只排除 password
$public = Arr::except($user, ['password']);
// ['id' => 1, 'name' => '山田太郎', 'email' => '...', 'role' => 'admin']

`Arr::pluck()` — 從巢狀陣列擷取特定鍵

use Illuminate\Support\Arr;

$records = [
    ['user' => ['id' => 1, 'name' => '山田太郎']],
    ['user' => ['id' => 2, 'name' => '鈴木花子']],
];

$names = Arr::pluck($records, 'user.name');
// ['山田太郎', '鈴木花子']

// 第 3 個參數指定 key
$nameById = Arr::pluck($records, 'user.name', 'user.id');
// [1 => '山田太郎', 2 => '鈴木花子']

`Arr::first()` / `Arr::last()` — 符合條件的第一個 / 最後一個

use Illuminate\Support\Arr;

$prices = [150, 80, 200, 50, 120];

// 100 以上的第一個價格
$first = Arr::first($prices, fn ($price) => $price >= 100);
// 150

// 若無符合條件的預設值
$first = Arr::first($prices, fn ($price) => $price >= 500, 0);
// 0

// 最後一個元素（不加條件）
$last = Arr::last($prices);
// 120

`Arr::flatten()` — 將多維陣列扁平化

use Illuminate\Support\Arr;

$tags = [
    'frontend' => ['html', 'css', 'javascript'],
    'backend'  => ['php', 'laravel', 'mysql'],
];

$allTags = Arr::flatten($tags);
// ['html', 'css', 'javascript', 'php', 'laravel', 'mysql']

`Arr::wrap()` — 確保值為陣列

若值非陣列則包裝為陣列。null 會變成空陣列。適合讓函式參數更彈性。

use Illuminate\Support\Arr;

Arr::wrap('Laravel');
// ['Laravel']

Arr::wrap(['Laravel', 'PHP']);
// ['Laravel', 'PHP']

Arr::wrap(null);
// []

`Arr::sort()` — 依值排序

use Illuminate\Support\Arr;

$fruits = ['banana', 'apple', 'cherry'];
$sorted = Arr::sort($fruits);
// ['apple', 'banana', 'cherry']

// 以閉包指定排序 key
$products = [
    ['name' => '筆電', 'price' => 120000],
    ['name' => '滑鼠', 'price' => 3500],
    ['name' => '鍵盤', 'price' => 8000],
];

$byPrice = Arr::sort($products, fn ($product) => $product['price']);
// 滑鼠、鍵盤、筆電 的順序

`Arr::dot()` / `Arr::undot()` — 點記法轉換 / 復原

use Illuminate\Support\Arr;

$nested = [
    'user' => [
        'profile' => ['name' => '山田太郎', 'age' => 28],
    ],
];

$dotted = Arr::dot($nested);
// ['user.profile.name' => '山田太郎', 'user.profile.age' => 28]

// 還原成原結構
$restored = Arr::undot($dotted);
// ['user' => ['profile' => ['name' => '山田太郎', 'age' => 28]]]

`Arr::join()` — 將陣列結合為字串

use Illuminate\Support\Arr;

$items = ['PHP', 'Laravel', 'MySQL'];

Arr::join($items, ', ');
// 'PHP, Laravel, MySQL'

// 只在最後一個元素前用不同字串
Arr::join($items, ', ', ' 與 ');
// 'PHP, Laravel 與 MySQL'

`data_get()` — 存取巢狀資料

Arr::get() 的通用版本。除了陣列，也支援物件、Eloquent 模型、集合。

$users = [
    ['name' => '山田太郎', 'address' => ['city' => '東京']],
    ['name' => '鈴木花子', 'address' => ['city' => '大阪']],
];

// 用點記法存取
$city = data_get($users, '0.address.city');
// '東京'

// 用萬用字元一次取所有元素
$cities = data_get($users, '*.address.city');
// ['東京', '大阪']

數字輔助（Number 類別）

`Number::format()` — 將數字轉為易讀的格式

use Illuminate\Support\Number;

Number::format(1234567.89);
// '1,234,567.89'

Number::format(1234567.89, precision: 0, locale: 'ja');
// '1,234,568'

`Number::currency()` — 幣別格式

use Illuminate\Support\Number;

Number::currency(10000, 'JPY', locale: 'ja');
// '￥10,000'

Number::currency(29.99, 'USD');
// '$29.99'

`Number::fileSize()` — 將檔案大小轉為易讀格式

use Illuminate\Support\Number;

Number::fileSize(1024);
// '1 KB'

Number::fileSize(1024 * 1024 * 2.5);
// '2.5 MB'

`Number::abbreviate()` — 將大數字縮寫

use Illuminate\Support\Number;

Number::abbreviate(1000);
// '1K'

Number::abbreviate(1500000);
// '1.5M'

`Number::percentage()` — 百分比顯示

use Illuminate\Support\Number;

Number::percentage(75.5, precision: 1);
// '75.5%'

路徑輔助

取得應用程式的目錄路徑。即使環境或部署目的地不同，也能回傳正確路徑。

// app 目錄的絕對路徑
app_path();
// /var/www/html/app

// app/Http/Controllers/UserController.php 的路徑
app_path('Http/Controllers/UserController.php');

// 專案根目錄的相對路徑
base_path('composer.json');

// config 目錄
config_path('database.php');

// database 目錄
database_path('migrations');

// storage 目錄
storage_path('app/uploads');

// public 目錄
public_path('css/app.css');

// resources 目錄
resource_path('views/welcome.blade.php');

URL 輔助

`route()` — 產生命名路由的 URL

// 路由定義
// Route::get('/users/{user}', [UserController::class, 'show'])->name('users.show');

// 絕對 URL（預設）
$url = route('users.show', ['user' => 1]);
// 'https://example.com/users/1'

// 相對 URL
$url = route('users.show', ['user' => 1], false);
// '/users/1'

`url()` — 產生任意路徑的絕對 URL

$url = url('user/profile');
// 'https://example.com/user/profile'

// 取得 URL Generator 實例
$current  = url()->current();   // 目前 URL
$full     = url()->full();      // 含查詢字串的目前 URL
$previous = url()->previous();  // 前一個 URL

`asset()` — 產生靜態資產的 URL

$url = asset('img/logo.png');
// 'https://example.com/img/logo.png'

`to_route()` — 重新導向至命名路由

return to_route('users.show', ['user' => 1]);

// 可指定 HTTP 狀態與標頭
return to_route('users.show', ['user' => 1], 302, ['X-Custom' => 'value']);

其他常用輔助函式

`config()` — 讀寫設定值

// 以點記法讀取設定
$timezone = config('app.timezone');
// 'Asia/Tokyo'

// 附預設值
$debug = config('app.debug', false);

// 執行期變更設定（僅該次處理內生效）
config(['app.locale' => 'ja']);

`collect()` — 建立集合

$collection = collect([1, 2, 3, 4, 5]);

$sum = collect([1, 2, 3])->sum(); // 6

collect() 是進入集合世界的最重要輔助函式。詳細請見集合。

`auth()` — 取得已認證使用者

// 取得目前使用者
$user = auth()->user();

// 檢查是否登入
if (auth()->check()) {
    // 已登入處理
}

// 使用特定 guard
$admin = auth('admin')->user();

`blank()` / `filled()` — 空值檢查

blank() 會把 null、空字串、只有空白、空集合 / 陣列視為 true。filled() 為其相反。

blank('');         // true
blank('   ');      // true
blank(null);       // true
blank(collect()); // true

blank(0);      // false（0 不是「空」）
blank(false);  // false

filled('hello'); // true
filled(0);       // true

`abort()` / `abort_if()` / `abort_unless()` — HTTP 例外

// 直接拋出 HTTP 錯誤
abort(404);
abort(403, '你沒有存取此頁面的權限。');

// 條件為 true 時錯誤
abort_if(! auth()->user()->isAdmin(), 403);

// 條件為 false 時錯誤
abort_unless(auth()->check(), 401);

`dd()` / `dump()` — 除錯

// 輸出變數並結束腳本
dd($user);
dd($user, $orders, $config);

// 只輸出，不結束腳本
dump($query);

`dispatch()` — 派發 Job 至佇列

dispatch(new App\Jobs\SendWelcomeEmail($user));

// 立即執行（同步）
dispatch_sync(new App\Jobs\GenerateReport($data));

`encrypt()` / `decrypt()` — 加解密

$encrypted = encrypt('sensitive-value');
$decrypted = decrypt($encrypted);

`env()` — 取得環境變數

$debug = env('APP_DEBUG', false);
$dbHost = env('DB_HOST', '127.0.0.1');

env() 建議只在 config/ 檔案中呼叫，於其他地方請透過 config() 存取，這是最佳實踐。當設定快取（php artisan config:cache）啟用時，env() 可能不會回傳你預期的值。

與 collect() 的取捨

Arr:: 類別以純 PHP 陣列為操作對象；collect() 則會回傳集合物件。

use Illuminate\Support\Arr;

// 想維持陣列 → 用 Arr 類別
$filtered = Arr::where($items, fn ($v) => $v > 0);
// 結果仍是陣列

// 想以方法鏈串接多個操作 → 用 collect()
$result = collect($items)
    ->filter(fn ($v) => $v > 0)
    ->map(fn ($v) => $v * 2)
    ->values()
    ->all();
// 結果是陣列（用 all() 取出）

Eloquent 查詢結果本身就是集合，不需要再 collect()。若只是簡單的陣列操作，用 Arr:: 會更簡潔。

總結

常用輔助函式一覽

輔助	用途
`Arr::get($array, 'a.b.c', $default)`	安全讀取巢狀陣列
`Arr::only($array, $keys)`	只保留指定鍵
`Arr::except($array, $keys)`	排除指定鍵
`Arr::pluck($array, 'key')`	取得特定鍵的值清單
`Arr::flatten($array)`	將多維陣列扁平化
`Arr::wrap($value)`	確保為陣列
`data_get($target, 'a.*.b')`	支援萬用字元
`Number::format($n)`	將數字格式化
`Number::currency($n, 'JPY')`	幣別顯示
`Number::fileSize($bytes)`	檔案大小顯示
`route('name', $params)`	命名路由 URL
`url('path')`	產生絕對 URL
`asset('path')`	靜態資產 URL
`config('key', $default)`	取得設定值
`collect($array)`	建立集合
`auth()->user()`	取得目前使用者
`blank($value)`	空值檢查
`filled($value)`	檢查是否非空
`abort(403)`	拋出 HTTP 例外
`dispatch($job)`	派發 Job 到佇列
`env('KEY', $default)`	取得環境變數

Arr 類別 vs collect()

使用 Arr:: 類別的情境：

單純的陣列操作（存取巢狀鍵、鍵的篩選等）
不需要集合物件的額外開銷
結果要直接以陣列處理

使用 collect() 的情境：

想以方法鏈串接多個操作
對 Eloquent 結果再加工（本身就是集合）
想使用 map、filter、groupBy 等集合專屬方法

​輔助函式是什麼

​陣列輔助（Arr 類別）

​Arr::get() — 以點記法讀取巢狀值

​Arr::set() — 對巢狀陣列設定值

​Arr::has() — 檢查鍵是否存在

​Arr::only() / Arr::except() — 篩選或排除鍵

​Arr::pluck() — 從巢狀陣列擷取特定鍵

​Arr::first() / Arr::last() — 符合條件的第一個 / 最後一個

​Arr::flatten() — 將多維陣列扁平化

​Arr::wrap() — 確保值為陣列

​Arr::sort() — 依值排序

​Arr::dot() / Arr::undot() — 點記法轉換 / 復原

​Arr::join() — 將陣列結合為字串

​data_get() — 存取巢狀資料

​數字輔助（Number 類別）

​Number::format() — 將數字轉為易讀的格式

​Number::currency() — 幣別格式

​Number::fileSize() — 將檔案大小轉為易讀格式

​Number::abbreviate() — 將大數字縮寫

​Number::percentage() — 百分比顯示

​路徑輔助

​URL 輔助

​route() — 產生命名路由的 URL

​url() — 產生任意路徑的絕對 URL

​asset() — 產生靜態資產的 URL

​to_route() — 重新導向至命名路由

​其他常用輔助函式

​config() — 讀寫設定值

​collect() — 建立集合

​auth() — 取得已認證使用者

​blank() / filled() — 空值檢查

​abort() / abort_if() / abort_unless() — HTTP 例外

​dd() / dump() — 除錯

​dispatch() — 派發 Job 至佇列

​encrypt() / decrypt() — 加解密

​env() — 取得環境變數

​與 collect() 的取捨

​總結

輔助函式是什麼

陣列輔助（Arr 類別）

`Arr::get()` — 以點記法讀取巢狀值

`Arr::set()` — 對巢狀陣列設定值

`Arr::has()` — 檢查鍵是否存在

`Arr::only()` / `Arr::except()` — 篩選或排除鍵

`Arr::pluck()` — 從巢狀陣列擷取特定鍵

`Arr::first()` / `Arr::last()` — 符合條件的第一個 / 最後一個

`Arr::flatten()` — 將多維陣列扁平化

`Arr::wrap()` — 確保值為陣列

`Arr::sort()` — 依值排序

`Arr::dot()` / `Arr::undot()` — 點記法轉換 / 復原

`Arr::join()` — 將陣列結合為字串

`data_get()` — 存取巢狀資料

數字輔助（Number 類別）

`Number::format()` — 將數字轉為易讀的格式

`Number::currency()` — 幣別格式

`Number::fileSize()` — 將檔案大小轉為易讀格式

`Number::abbreviate()` — 將大數字縮寫

`Number::percentage()` — 百分比顯示

路徑輔助

URL 輔助

`route()` — 產生命名路由的 URL

`url()` — 產生任意路徑的絕對 URL

`asset()` — 產生靜態資產的 URL

`to_route()` — 重新導向至命名路由

其他常用輔助函式

`config()` — 讀寫設定值

`collect()` — 建立集合

`auth()` — 取得已認證使用者

`blank()` / `filled()` — 空值檢查

`abort()` / `abort_if()` / `abort_unless()` — HTTP 例外

`dd()` / `dump()` — 除錯

`dispatch()` — 派發 Job 至佇列

`encrypt()` / `decrypt()` — 加解密

`env()` — 取得環境變數

與 collect() 的取捨

總結