輔助函式 (Helpers)

簡介 (Introduction)

Laravel 包含多種全域「輔助」PHP 函式。許多這些函式由框架本身使用;但是,如果你發現它們很方便,你可以在自己的應用程式中自由使用它們。

可用方法 (Available Methods)

陣列和物件 (Arrays & Objects)

數字 (Numbers)

路徑 (Paths)

URL (URLs)

其他 (Miscellaneous)

陣列和物件 (Arrays & Objects)

Arr::accessible()

Arr::accessible 方法判斷給定的值是否為陣列可存取的:

use Illuminate\Support\Arr;
use Illuminate\Support\Collection;

$isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);

// true

$isAccessible = Arr::accessible(new Collection);

// true

$isAccessible = Arr::accessible('abc');

// false

$isAccessible = Arr::accessible(new stdClass);

// false

Arr::add()

Arr::add 方法將給定的鍵/值對新增到陣列中(如果給定的鍵在陣列中不存在或設定為 null):

use Illuminate\Support\Arr;

$array = Arr::add(['name' => 'Desk'], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

$array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

Arr::array()

Arr::array 方法使用「點」符號從深度巢狀的陣列中檢索值(就像 Arr::get() 一樣),但如果請求的值不是 array,則拋出 InvalidArgumentException:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$value = Arr::array($array, 'languages');

// ['PHP', 'Ruby']

$value = Arr::array($array, 'name');

// throws InvalidArgumentException

Arr::boolean()

Arr::boolean 方法使用「點」符號從深度巢狀的陣列中檢索值(就像 Arr::get() 一樣),但如果請求的值不是 boolean,則拋出 InvalidArgumentException:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'available' => true];

$value = Arr::boolean($array, 'available');

// true

$value = Arr::boolean($array, 'name');

// throws InvalidArgumentException

Arr::collapse()

Arr::collapse 方法將陣列的陣列或集合摺疊成單個陣列:

use Illuminate\Support\Arr;

$array = Arr::collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);

// [1, 2, 3, 4, 5, 6, 7, 8, 9]

Arr::crossJoin()

Arr::crossJoin 方法交叉連線給定的陣列,返回具有所有可能排列的笛卡兒積:

use Illuminate\Support\Arr;

$matrix = Arr::crossJoin([1, 2], ['a', 'b']);

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

$matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

Arr::divide()

Arr::divide 方法返回兩個陣列:一個包含鍵,另一個包含給定陣列的值:

use Illuminate\Support\Arr;

[$keys, $values] = Arr::divide(['name' => 'Desk']);

// $keys: ['name']

// $values: ['Desk']

Arr::dot()

Arr::dot 方法將多維陣列展平為使用「點」符號指示深度的單層陣列:

use Illuminate\Support\Arr;

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

$flattened = Arr::dot($array);

// ['products.desk.price' => 100]

Arr::every()

Arr::every 方法確保陣列中的所有值都通過給定的真值測試:

use Illuminate\Support\Arr;

$array = [1, 2, 3];

Arr::every($array, fn ($i) => $i > 0);

// true

Arr::every($array, fn ($i) => $i > 2);

// false

Arr::except()

Arr::except 方法從陣列中移除給定的鍵/值對:

use Illuminate\Support\Arr;

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

$filtered = Arr::except($array, ['price']);

// ['name' => 'Desk']

Arr::exists()

Arr::exists 方法檢查給定的鍵是否存在於提供的陣列中:

use Illuminate\Support\Arr;

$array = ['name' => 'John Doe', 'age' => 17];

$exists = Arr::exists($array, 'name');

// true

$exists = Arr::exists($array, 'salary');

// false

Arr::first()

Arr::first 方法返回通過給定真值測試的陣列的第一個元素:

use Illuminate\Support\Arr;

$array = [100, 200, 300];

$first = Arr::first($array, function (int $value, int $key) {
    return $value >= 150;
});

// 200

也可以將預設值作為第三個參數傳遞給該方法。如果沒有值通過真值測試,則將返回此值:

use Illuminate\Support\Arr;

$first = Arr::first($array, $callback, $default);

Arr::flatten()

Arr::flatten 方法將多維陣列展平為單層陣列:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$flattened = Arr::flatten($array);

// ['Joe', 'PHP', 'Ruby']

Arr::float()

Arr::float 方法使用「點」符號從深度巢狀的陣列中檢索值(就像 Arr::get() 一樣),但如果請求的值不是 float,則拋出 InvalidArgumentException:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'balance' => 123.45];

$value = Arr::float($array, 'balance');

// 123.45

$value = Arr::float($array, 'name');

// throws InvalidArgumentException

Arr::forget()

Arr::forget 方法使用「點」符號從深度巢狀的陣列中移除給定的鍵/值對:

use Illuminate\Support\Arr;

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

Arr::forget($array, 'products.desk');

// ['products' => []]

Arr::from()

Arr::from 方法將各種輸入類型轉換為純 PHP 陣列。它支援一系列輸入類型,包括陣列、物件和幾個常見的 Laravel 介面,如 Arrayable、Enumerable、Jsonable 和 JsonSerializable。此外,它還處理 Traversable 和 WeakMap 實例:

use Illuminate\Support\Arr;

Arr::from((object) ['foo' => 'bar']); // ['foo' => 'bar']

class TestJsonableObject implements Jsonable
{
    public function toJson($options = 0)
    {
        return json_encode(['foo' => 'bar']);
    }
}

Arr::from(new TestJsonableObject); // ['foo' => 'bar']

Arr::get()

Arr::get 方法使用「點」符號從深度巢狀的陣列中檢索值:

use Illuminate\Support\Arr;

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

$price = Arr::get($array, 'products.desk.price');

// 100

Arr::get 方法也接受一個預設值,如果指定的鍵在陣列中不存在,則返回該預設值:

use Illuminate\Support\Arr;

$discount = Arr::get($array, 'products.desk.discount', 0);

// 0

Arr::has()

Arr::has 方法使用「點」符號檢查陣列中是否存在給定的項目或項目:

use Illuminate\Support\Arr;

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

$contains = Arr::has($array, 'product.name');

// true

$contains = Arr::has($array, ['product.price', 'product.discount']);

// false

Arr::hasAll()

Arr::hasAll 方法使用「點」符號判斷給定陣列中是否存在所有指定的鍵:

use Illuminate\Support\Arr;

$array = ['name' => 'Taylor', 'language' => 'PHP'];

Arr::hasAll($array, ['name']); // true
Arr::hasAll($array, ['name', 'language']); // true
Arr::hasAll($array, ['name', 'IDE']); // false

Arr::hasAny()

Arr::hasAny 方法使用「點」符號檢查給定集合中的任何項目是否存在於陣列中:

use Illuminate\Support\Arr;

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

$contains = Arr::hasAny($array, 'product.name');

// true

$contains = Arr::hasAny($array, ['product.name', 'product.discount']);

// true

$contains = Arr::hasAny($array, ['category', 'product.discount']);

// false

Arr::integer()

Arr::integer 方法使用「點」符號從深度巢狀的陣列中檢索值(就像 Arr::get() 一樣),但如果請求的值不是 int,則拋出 InvalidArgumentException:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'age' => 42];

$value = Arr::integer($array, 'age');

// 42

$value = Arr::integer($array, 'name');

// throws InvalidArgumentException

Arr::isAssoc()

如果給定的陣列是關聯陣列,則 Arr::isAssoc 方法返回 true。如果陣列沒有以零開頭的連續數字鍵,則該陣列被視為「關聯」陣列:

use Illuminate\Support\Arr;

$isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);

// true

$isAssoc = Arr::isAssoc([1, 2, 3]);

// false

Arr::isList()

如果給定陣列的鍵是從零開頭的連續整數,則 Arr::isList 方法返回 true:

use Illuminate\Support\Arr;

$isList = Arr::isList(['foo', 'bar', 'baz']);

// true

$isList = Arr::isList(['product' => ['name' => 'Desk', 'price' => 100]]);

// false

Arr::join()

Arr::join 方法使用字串連線陣列元素。使用此方法的第三個參數,你還可以指定陣列最後一個元素的連線字串:

use Illuminate\Support\Arr;

$array = ['Tailwind', 'Alpine', 'Laravel', 'Livewire'];

$joined = Arr::join($array, ', ');

// Tailwind, Alpine, Laravel, Livewire

$joined = Arr::join($array, ', ', ', and ');

// Tailwind, Alpine, Laravel, and Livewire

Arr::keyBy()

Arr::keyBy 方法按給定鍵對陣列進行鍵控。如果多個項目具有相同的鍵,則只有最後一個項目會出現在新陣列中:

use Illuminate\Support\Arr;

$array = [
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
];

$keyed = Arr::keyBy($array, 'product_id');

/*
    [
        'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

Arr::last()

Arr::last 方法返回通過給定真值測試的陣列的最後一個元素:

use Illuminate\Support\Arr;

$array = [100, 200, 300, 110];

$last = Arr::last($array, function (int $value, int $key) {
    return $value >= 150;
});

// 300

可以將預設值作為第三個參數傳遞給該方法。如果沒有值通過真值測試,則將返回此值:

use Illuminate\Support\Arr;

$last = Arr::last($array, $callback, $default);

Arr::map()

Arr::map 方法遍歷陣列並將每個值和鍵傳遞給給定的回呼。陣列值將被回呼返回的值替換:

use Illuminate\Support\Arr;

$array = ['first' => 'james', 'last' => 'kirk'];

$mapped = Arr::map($array, function (string $value, string $key) {
    return ucfirst($value);
});

// ['first' => 'James', 'last' => 'Kirk']

Arr::mapSpread()

Arr::mapSpread 方法遍歷陣列,將每個巢狀項目值傳遞給給定的閉包。閉包可以自由修改項目並返回它,從而形成一個修改後項目的新陣列:

use Illuminate\Support\Arr;

$array = [
    [0, 1],
    [2, 3],
    [4, 5],
    [6, 7],
    [8, 9],
];

$mapped = Arr::mapSpread($array, function (int $even, int $odd) {
    return $even + $odd;
});

/*
    [1, 5, 9, 13, 17]
*/

Arr::mapWithKeys()

Arr::mapWithKeys 方法遍歷陣列並將每個值傳遞給給定的回呼。回呼應返回包含單個鍵/值對的關聯陣列:

use Illuminate\Support\Arr;

$array = [
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
];

$mapped = Arr::mapWithKeys($array, function (array $item, int $key) {
    return [$item['email'] => $item['name']];
});

/*
    [
        'john@example.com' => 'John',
        'jane@example.com' => 'Jane',
    ]
*/

Arr::only()

Arr::only 方法僅返回給定陣列中指定的鍵/值對:

use Illuminate\Support\Arr;

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

$slice = Arr::only($array, ['name', 'price']);

// ['name' => 'Desk', 'price' => 100]

Arr::partition()

Arr::partition 方法可以與 PHP 陣列解構結合使用,將通過給定真值測試的元素與未通過的元素分開:

<?php

use Illuminate\Support\Arr;

$numbers = [1, 2, 3, 4, 5, 6];

[$underThree, $equalOrAboveThree] = Arr::partition($numbers, function (int $i) {
    return $i < 3;
});

dump($underThree);

// [1, 2]

dump($equalOrAboveThree);

// [3, 4, 5, 6]

Arr::pluck()

Arr::pluck 方法從陣列中檢索給定鍵的所有值:

use Illuminate\Support\Arr;

$array = [
    ['developer' => ['id' => 1, 'name' => 'Taylor']],
    ['developer' => ['id' => 2, 'name' => 'Abigail']],
];

$names = Arr::pluck($array, 'developer.name');

// ['Taylor', 'Abigail']

你也可以指定希望如何為結果清單設定鍵:

use Illuminate\Support\Arr;

$names = Arr::pluck($array, 'developer.name', 'developer.id');

// [1 => 'Taylor', 2 => 'Abigail']

Arr::prepend()

Arr::prepend 方法將一個項目推送到陣列的開頭:

use Illuminate\Support\Arr;

$array = ['one', 'two', 'three', 'four'];

$array = Arr::prepend($array, 'zero');

// ['zero', 'one', 'two', 'three', 'four']

如果需要,你可以指定應用於值的鍵:

use Illuminate\Support\Arr;

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

$array = Arr::prepend($array, 'Desk', 'name');

// ['name' => 'Desk', 'price' => 100]

Arr::prependKeysWith()

Arr::prependKeysWith 將關聯陣列的所有鍵名加上給定的前綴:

use Illuminate\Support\Arr;

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

$keyed = Arr::prependKeysWith($array, 'product.');

/*
    [
        'product.name' => 'Desk',
        'product.price' => 100,
    ]
*/

Arr::pull()

Arr::pull 方法從陣列中返回並移除鍵/值對:

use Illuminate\Support\Arr;

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

$name = Arr::pull($array, 'name');

// $name: Desk

// $array: ['price' => 100]

可以將預設值作為第三個參數傳遞給該方法。如果鍵不存在,則將返回此值:

use Illuminate\Support\Arr;

$value = Arr::pull($array, $key, $default);

Arr::push()

Arr::push 方法使用「點」符號將項目推送到陣列中。如果給定鍵處不存在陣列,則會建立它:

use Illuminate\Support\Arr;

$array = [];

Arr::push($array, 'office.furniture', 'Desk');

// $array: ['office' => ['furniture' => ['Desk']]]

Arr::query()

Arr::query 方法將陣列轉換為查詢字串:

use Illuminate\Support\Arr;

$array = [
    'name' => 'Taylor',
    'order' => [
        'column' => 'created_at',
        'direction' => 'desc'
    ]
];

Arr::query($array);

// name=Taylor&order[column]=created_at&order[direction]=desc

Arr::random()

Arr::random 方法從陣列中返回一個隨機值:

use Illuminate\Support\Arr;

$array = [1, 2, 3, 4, 5];

$random = Arr::random($array);

// 4 - (retrieved randomly)

你也可以指定要返回的項目數作為可選的第二個參數。請注意,提供此參數將返回一個陣列,即使只需要一個項目:

use Illuminate\Support\Arr;

$items = Arr::random($array, 2);

// [2, 5] - (retrieved randomly)

Arr::reject()

Arr::reject 方法使用給定的閉包從陣列中移除項目:

use Illuminate\Support\Arr;

$array = [100, '200', 300, '400', 500];

$filtered = Arr::reject($array, function (string|int $value, int $key) {
    return is_string($value);
});

// [0 => 100, 2 => 300, 4 => 500]

Arr::select()

Arr::select 方法從陣列中選擇一個值陣列:

use Illuminate\Support\Arr;

$array = [
    ['id' => 1, 'name' => 'Desk', 'price' => 200],
    ['id' => 2, 'name' => 'Table', 'price' => 150],
    ['id' => 3, 'name' => 'Chair', 'price' => 300],
];

Arr::select($array, ['name', 'price']);

// [['name' => 'Desk', 'price' => 200], ['name' => 'Table', 'price' => 150], ['name' => 'Chair', 'price' => 300]]

Arr::set()

Arr::set 方法使用「點」符號在深度巢狀的陣列中設定值:

use Illuminate\Support\Arr;

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

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

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

Arr::shuffle()

Arr::shuffle 方法隨機打亂陣列中的項目:

use Illuminate\Support\Arr;

$array = Arr::shuffle([1, 2, 3, 4, 5]);

// [3, 2, 5, 1, 4] - (generated randomly)

Arr::sole()

Arr::sole 方法使用給定的閉包從陣列中檢索單個值。如果陣列中有多個值符合給定的真值測試,將拋出 Illuminate\Support\MultipleItemsFoundException 異常。如果沒有值符合真值測試,將拋出 Illuminate\Support\ItemNotFoundException 異常:

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$value = Arr::sole($array, fn (string $value) => $value === 'Desk');

// 'Desk'

Arr::some()

Arr::some 方法確保陣列中至少有一個值通過給定的真值測試:

use Illuminate\Support\Arr;

$array = [1, 2, 3];

Arr::some($array, fn ($i) => $i > 2);

// true

Arr::sort()

Arr::sort 方法按值對陣列進行排序:

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sort($array);

// ['Chair', 'Desk', 'Table']

你也可以按給定閉包的結果對陣列進行排序:

use Illuminate\Support\Arr;

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(Arr::sort($array, function (array $value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Chair'],
        ['name' => 'Desk'],
        ['name' => 'Table'],
    ]
*/

Arr::sortDesc()

Arr::sortDesc 方法按值對陣列進行降序排序:

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sortDesc($array);

// ['Table', 'Desk', 'Chair']

你也可以按給定閉包的結果對陣列進行排序:

use Illuminate\Support\Arr;

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(Arr::sortDesc($array, function (array $value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Table'],
        ['name' => 'Desk'],
        ['name' => 'Chair'],
    ]
*/

Arr::sortRecursive()

Arr::sortRecursive 方法使用 sort 函式遞迴排序數字索引的子陣列,並使用 ksort 函式排序關聯子陣列:

use Illuminate\Support\Arr;

$array = [
    ['Roman', 'Taylor', 'Li'],
    ['PHP', 'Ruby', 'JavaScript'],
    ['one' => 1, 'two' => 2, 'three' => 3],
];

$sorted = Arr::sortRecursive($array);

/*
    [
        ['JavaScript', 'PHP', 'Ruby'],
        ['one' => 1, 'three' => 3, 'two' => 2],
        ['Li', 'Roman', 'Taylor'],
    ]
*/

如果你希望結果按降序排序,可以使用 Arr::sortRecursiveDesc 方法。

$sorted = Arr::sortRecursiveDesc($array);

Arr::string()

Arr::string 方法使用「點」符號從深度巢狀的陣列中檢索值(就像 Arr::get() 一樣),但如果請求的值不是 string,則拋出 InvalidArgumentException:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$value = Arr::string($array, 'name');

// Joe

$value = Arr::string($array, 'languages');

// throws InvalidArgumentException

Arr::take()

Arr::take 方法返回具有指定數量項目的新陣列:

use Illuminate\Support\Arr;

$array = [0, 1, 2, 3, 4, 5];

$chunk = Arr::take($array, 3);

// [0, 1, 2]

你也可以傳遞一個負整數來從陣列末尾獲取指定數量的項目:

$array = [0, 1, 2, 3, 4, 5];

$chunk = Arr::take($array, -2);

// [4, 5]

Arr::toCssClasses()

Arr::toCssClasses 方法條件式編譯 CSS 類別字串。該方法接受一個類別陣列,其中陣列鍵包含你希望新增的類別,而值是一個布林表達式。如果陣列元素具有數字鍵,它將始終包含在渲染的類別清單中:

use Illuminate\Support\Arr;

$isActive = false;
$hasError = true;

$array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];

$classes = Arr::toCssClasses($array);

/*
    'p-4 bg-red'
*/

Arr::toCssStyles()

Arr::toCssStyles 條件式編譯 CSS 樣式字串。該方法接受一個類別陣列,其中陣列鍵包含你希望新增的類別,而值是一個布林表達式。如果陣列元素具有數字鍵,它將始終包含在渲染的類別清單中:

use Illuminate\Support\Arr;

$hasColor = true;

$array = ['background-color: blue', 'color: blue' => $hasColor];

$classes = Arr::toCssStyles($array);

/*
    'background-color: blue; color: blue;'
*/

此方法支援 Laravel 的功能,允許將類別與 Blade 元件的屬性包合併以及 @class Blade 指令。

Arr::undot()

Arr::undot 方法將使用「點」符號的一維陣列擴展為多維陣列:

use Illuminate\Support\Arr;

$array = [
    'user.name' => 'Kevin Malone',
    'user.occupation' => 'Accountant',
];

$array = Arr::undot($array);

// ['user' => ['name' => 'Kevin Malone', 'occupation' => 'Accountant']]

Arr::where()

Arr::where 方法使用給定的閉包過濾陣列:

use Illuminate\Support\Arr;

$array = [100, '200', 300, '400', 500];

$filtered = Arr::where($array, function (string|int $value, int $key) {
    return is_string($value);
});

// [1 => '200', 3 => '400']

Arr::whereNotNull()

Arr::whereNotNull 方法從給定陣列中移除所有 null 值:

use Illuminate\Support\Arr;

$array = [0, null];

$filtered = Arr::whereNotNull($array);

// [0 => 0]

Arr::wrap()

Arr::wrap 方法將給定值包裝在陣列中。如果給定值已經是陣列,則將其原樣返回:

use Illuminate\Support\Arr;

$string = 'Laravel';

$array = Arr::wrap($string);

// ['Laravel']

如果給定值為 null,將返回一個空陣列:

use Illuminate\Support\Arr;

$array = Arr::wrap(null);

// []

data_fill()

data_fill 函式使用「點」符號在巢狀陣列或物件中設定缺失值:

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

data_fill($data, 'products.desk.price', 200);

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

data_fill($data, 'products.desk.discount', 10);

// ['products' => ['desk' => ['price' => 100, 'discount' => 10]]]

此函式也接受星號作為萬用字元,並將相應地填充目標:

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2'],
    ],
];

data_fill($data, 'products.*.price', 200);

/*
    [
        'products' => [
            ['name' => 'Desk 1', 'price' => 100],
            ['name' => 'Desk 2', 'price' => 200],
        ],
    ]
*/

data_get()

data_get 函式使用「點」符號從巢狀陣列或物件中檢索值:

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

$price = data_get($data, 'products.desk.price');

// 100

data_get 函式也接受一個預設值,如果找不到指定的鍵,將返回該預設值:

$discount = data_get($data, 'products.desk.discount', 0);

// 0

該函式也接受使用星號的萬用字元,這可以針對陣列或物件的任何鍵:

$data = [
    'product-one' => ['name' => 'Desk 1', 'price' => 100],
    'product-two' => ['name' => 'Desk 2', 'price' => 150],
];

data_get($data, '*.name');

// ['Desk 1', 'Desk 2'];

{first} 和 {last} 佔位符可用於檢索陣列中的第一個或最後一個項目:

$flight = [
    'segments' => [
        ['from' => 'LHR', 'departure' => '9:00', 'to' => 'IST', 'arrival' => '15:00'],
        ['from' => 'IST', 'departure' => '16:00', 'to' => 'PKX', 'arrival' => '20:00'],
    ],
];

data_get($flight, 'segments.{first}.arrival');

// 15:00

data_set()

data_set 函式使用「點」符號在巢狀陣列或物件中設定值:

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

data_set($data, 'products.desk.price', 200);

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

此函式也接受使用星號的萬用字元,並將相應地設定目標上的值:

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2', 'price' => 150],
    ],
];

data_set($data, 'products.*.price', 200);

/*
    [
        'products' => [
            ['name' => 'Desk 1', 'price' => 200],
            ['name' => 'Desk 2', 'price' => 200],
        ],
    ]
*/

預設情況下,任何現有值都會被覆蓋。如果你希望僅在值不存在時設定值,可以將 false 作為第四個參數傳遞給函式:

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

data_set($data, 'products.desk.price', 200, overwrite: false);

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

data_forget()

data_forget 函式使用「點」符號從巢狀陣列或物件中移除值:

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

data_forget($data, 'products.desk.price');

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

此函式也接受使用星號的萬用字元,並將相應地移除目標上的值:

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2', 'price' => 150],
    ],
];

data_forget($data, 'products.*.price');

/*
    [
        'products' => [
            ['name' => 'Desk 1'],
            ['name' => 'Desk 2'],
        ],
    ]
*/

head()

head 函式返回給定陣列中的第一個元素。如果陣列為空,將返回 false:

$array = [100, 200, 300];

$first = head($array);

// 100

last()

last 函式返回給定陣列中的最後一個元素。如果陣列為空,將返回 false:

$array = [100, 200, 300];

$last = last($array);

// 300

Numbers

Number::abbreviate()

Number::abbreviate 方法返回提供的數值的可讀格式,並帶有單位的縮寫:

use Illuminate\Support\Number;

$number = Number::abbreviate(1000);

// 1K

$number = Number::abbreviate(489939);

// 490K

$number = Number::abbreviate(1230000, precision: 2);

// 1.23M

Number::clamp()

Number::clamp 方法確保給定的數字保持在指定範圍內。如果數字低於最小值,則返回最小值。如果數字高於最大值,則返回最大值:

use Illuminate\Support\Number;

$number = Number::clamp(105, min: 10, max: 100);

// 100

$number = Number::clamp(5, min: 10, max: 100);

// 10

$number = Number::clamp(10, min: 10, max: 100);

// 10

$number = Number::clamp(20, min: 10, max: 100);

// 20

Number::currency()

Number::currency 方法以字串形式返回給定值的貨幣表示形式:

use Illuminate\Support\Number;

$currency = Number::currency(1000);

// $1,000.00

$currency = Number::currency(1000, in: 'EUR');

// €1,000.00

$currency = Number::currency(1000, in: 'EUR', locale: 'de');

// 1.000,00 €

$currency = Number::currency(1000, in: 'EUR', locale: 'de', precision: 0);

// 1.000 €

Number::defaultCurrency()

Number::defaultCurrency 方法返回 Number 類別正在使用的預設貨幣:

use Illuminate\Support\Number;

$currency = Number::defaultCurrency();

// USD

Number::defaultLocale()

Number::defaultLocale 方法返回 Number 類別正在使用的預設區域設定:

use Illuminate\Support\Number;

$locale = Number::defaultLocale();

// en

Number::fileSize()

Number::fileSize 方法以字串形式返回給定位元組值的檔案大小表示形式:

use Illuminate\Support\Number;

$size = Number::fileSize(1024);

// 1 KB

$size = Number::fileSize(1024 * 1024);

// 1 MB

$size = Number::fileSize(1024, precision: 2);

// 1.00 KB

Number::forHumans()

Number::forHumans 方法返回提供的數值的可讀格式:

use Illuminate\Support\Number;

$number = Number::forHumans(1000);

// 1 thousand

$number = Number::forHumans(489939);

// 490 thousand

$number = Number::forHumans(1230000, precision: 2);

// 1.23 million

Number::format()

Number::format 方法將給定的數字格式化為特定於區域設定的字串:

use Illuminate\Support\Number;

$number = Number::format(100000);

// 100,000

$number = Number::format(100000, precision: 2);

// 100,000.00

$number = Number::format(100000.123, maxPrecision: 2);

// 100,000.12

$number = Number::format(100000, locale: 'de');

// 100.000

Number::ordinal()

Number::ordinal 方法返回數字的序數表示形式:

use Illuminate\Support\Number;

$number = Number::ordinal(1);

// 1st

$number = Number::ordinal(2);

// 2nd

$number = Number::ordinal(21);

// 21st

Number::pairs()

Number::pairs 方法根據指定的範圍和步長值產生數字對(子範圍)的陣列。此方法對於將較大範圍的數字劃分為較小的、可管理的子範圍(例如分頁或批次處理任務)非常有用。pairs 方法返回一個陣列的陣列,其中每個內部陣列代表一對(子範圍)數字:

use Illuminate\Support\Number;

$result = Number::pairs(25, 10);

// [[0, 9], [10, 19], [20, 25]]

$result = Number::pairs(25, 10, offset: 0);

// [[0, 10], [10, 20], [20, 25]]

Number::parseInt()

Number::parseInt 方法根據指定的區域設定將字串解析為整數:

use Illuminate\Support\Number;

$result = Number::parseInt('10.123');

// (int) 10

$result = Number::parseInt('10,123', locale: 'fr');

// (int) 10

Number::parseFloat()

Number::parseFloat 方法根據指定的區域設定將字串解析為浮點數:

use Illuminate\Support\Number;

$result = Number::parseFloat('10');

// (float) 10.0

$result = Number::parseFloat('10', locale: 'fr');

// (float) 10.0

Number::percentage()

Number::percentage 方法以字串形式返回給定值的百分比表示形式:

use Illuminate\Support\Number;

$percentage = Number::percentage(10);

// 10%

$percentage = Number::percentage(10, precision: 2);

// 10.00%

$percentage = Number::percentage(10.123, maxPrecision: 2);

// 10.12%

$percentage = Number::percentage(10, precision: 2, locale: 'de');

// 10,00%

Number::spell()

Number::spell 方法將給定的數字轉換為單字字串:

use Illuminate\Support\Number;

$number = Number::spell(102);

// one hundred and two

$number = Number::spell(88, locale: 'fr');

// quatre-vingt-huit

after 參數允許你指定一個值,在此值之後所有數字都應拼寫出來:

$number = Number::spell(10, after: 10);

// 10

$number = Number::spell(11, after: 10);

// eleven

until 參數允許你指定一個值,在此值之前所有數字都應拼寫出來:

$number = Number::spell(5, until: 10);

// five

$number = Number::spell(10, until: 10);

// 10

Number::spellOrdinal()

Number::spellOrdinal 方法以單字字串形式返回數字的序數表示形式:

use Illuminate\Support\Number;

$number = Number::spellOrdinal(1);

// first

$number = Number::spellOrdinal(2);

// second

$number = Number::spellOrdinal(21);

// twenty-first

Number::trim()

Number::trim 方法移除給定數字小數點後的任何尾隨零數字:

use Illuminate\Support\Number;

$number = Number::trim(12.0);

// 12

$number = Number::trim(12.30);

// 12.3

Number::useLocale()

Number::useLocale 方法全域設定預設數字區域設定,這會影響後續呼叫 Number 類別方法時數字和貨幣的格式化方式:

use Illuminate\Support\Number;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Number::useLocale('de');
}

Number::withLocale()

Number::withLocale 方法使用指定的區域設定執行給定的閉包,然後在回呼執行後恢復原始區域設定:

use Illuminate\Support\Number;

$number = Number::withLocale('de', function () {
    return Number::format(1500);
});

Number::useCurrency()

Number::useCurrency 方法全域設定預設數字貨幣,這會影響後續呼叫 Number 類別方法時貨幣的格式化方式:

use Illuminate\Support\Number;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Number::useCurrency('GBP');
}

Number::withCurrency()

Number::withCurrency 方法使用指定的貨幣執行給定的閉包,然後在回呼執行後恢復原始貨幣:

use Illuminate\Support\Number;

$number = Number::withCurrency('GBP', function () {
    // ...
});

Paths

app_path()

app_path 函式返回應用程式 app 目錄的完全限定路徑。你也可以使用 app_path 函式產生相對於應用程式目錄的檔案的完全限定路徑:

$path = app_path();

$path = app_path('Http/Controllers/Controller.php');

base_path()

base_path 函式返回應用程式根目錄的完全限定路徑。你也可以使用 base_path 函式產生相對於專案根目錄的給定檔案的完全限定路徑:

$path = base_path();

$path = base_path('vendor/bin');

config_path()

config_path 函式返回應用程式 config 目錄的完全限定路徑。你也可以使用 config_path 函式產生應用程式設定目錄中給定檔案的完全限定路徑:

$path = config_path();

$path = config_path('app.php');

database_path()

database_path 函式返回應用程式 database 目錄的完全限定路徑。你也可以使用 database_path 函式產生資料庫目錄中給定檔案的完全限定路徑:

$path = database_path();

$path = database_path('factories/UserFactory.php');

lang_path()

lang_path 函式返回應用程式 lang 目錄的完全限定路徑。你也可以使用 lang_path 函式產生目錄中給定檔案的完全限定路徑:

$path = lang_path();

$path = lang_path('en/messages.php');

[!NOTE] 預設情況下,Laravel 應用程式骨架不包含 lang 目錄。如果你想自訂 Laravel 的語言檔案,你可以透過 lang:publish Artisan 指令發佈它們。

public_path()

public_path 函式返回應用程式 public 目錄的完全限定路徑。你也可以使用 public_path 函式產生 public 目錄中給定檔案的完全限定路徑:

$path = public_path();

$path = public_path('css/app.css');

resource_path()

resource_path 函式返回應用程式 resources 目錄的完全限定路徑。你也可以使用 resource_path 函式產生 resources 目錄中給定檔案的完全限定路徑:

$path = resource_path();

$path = resource_path('sass/app.scss');

storage_path()

storage_path 函式返回應用程式 storage 目錄的完全限定路徑。你也可以使用 storage_path 函式產生 storage 目錄中給定檔案的完全限定路徑:

$path = storage_path();

$path = storage_path('app/file.txt');

URLs

action()

action 函式為給定的控制器動作產生 URL:

use App\Http\Controllers\HomeController;

$url = action([HomeController::class, 'index']);

如果方法接受路由參數,你可以將它們作為第二個參數傳遞給該方法:

$url = action([UserController::class, 'profile'], ['id' => 1]);

asset()

asset 函式使用請求的當前方案(HTTP 或 HTTPS)為資產產生 URL:

$url = asset('img/photo.jpg');

你可以透過在 .env 檔案中設定 ASSET_URL 變數來設定資產 URL 主機。如果你將資產託管在外部服務(如 Amazon S3 或其他 CDN)上,這可能很有用:

// ASSET_URL=http://example.com/assets

$url = asset('img/photo.jpg'); // http://example.com/assets/img/photo.jpg

route()

route 函式為給定的命名路由產生 URL:

$url = route('route.name');

如果路由接受參數,你可以將它們作為第二個參數傳遞給該函式:

$url = route('route.name', ['id' => 1]);

預設情況下,route 函式產生絕對 URL。如果你希望產生相對 URL,可以將 false 作為第三個參數傳遞給該函式:

$url = route('route.name', ['id' => 1], false);

secure_asset()

secure_asset 函式使用 HTTPS 為資產產生 URL:

$url = secure_asset('img/photo.jpg');

secure_url()

secure_url 函式產生給定路徑的完全限定 HTTPS URL。額外的 URL 片段可以在函式的第二個參數中傳遞:

$url = secure_url('user/profile');

$url = secure_url('user/profile', [1]);

to_action()

to_action 函式為給定的控制器動作產生重新導向 HTTP 回應:

use App\Http\Controllers\UserController;

return to_action([UserController::class, 'show'], ['user' => 1]);

如果需要,你可以將應分配給重新導向的 HTTP 狀態碼和任何額外的回應標頭作為第三個和第四個參數傳遞給 to_action 方法:

return to_action(
    [UserController::class, 'show'],
    ['user' => 1],
    302,
    ['X-Framework' => 'Laravel']
);

to_route()

to_route 函式為給定的命名路由產生重新導向 HTTP 回應:

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

如果需要,你可以將應分配給重新導向的 HTTP 狀態碼和任何額外的回應標頭作為第三個和第四個參數傳遞給 to_route 方法:

return to_route('users.show', ['user' => 1], 302, ['X-Framework' => 'Laravel']);

uri()

uri 函式為給定的 URI 產生流暢的 URI 實例:

$uri = uri('https://example.com')
    ->withPath('/users')
    ->withQuery(['page' => 1]);

如果 uri 函式被賦予一個包含可呼叫控制器和方法對的陣列,該函式將為控制器方法的路由路徑建立一個 Uri 實例:

use App\Http\Controllers\UserController;

$uri = uri([UserController::class, 'show'], ['user' => $user]);

如果控制器是可呼叫的,你可以簡單地提供控制器類別名稱:

use App\Http\Controllers\UserIndexController;

$uri = uri(UserIndexController::class);

如果賦予 uri 函式的值與命名路由的名稱匹配,將為該路由的路徑產生一個 Uri 實例:

$uri = uri('users.show', ['user' => $user]);

url()

url 函式產生給定路徑的完全限定 URL:

$url = url('user/profile');

$url = url('user/profile', [1]);

如果未提供路徑,則返回 Illuminate\Routing\UrlGenerator 實例:

$current = url()->current();

$full = url()->full();

$previous = url()->previous();

有關使用 url 函式的更多資訊,請參閱URL 產生文件。

Miscellaneous

abort()

abort 函式拋出一個 HTTP 異常,該異常將由異常處理常式呈現:

abort(403);

你也可以提供異常的訊息和應傳送給瀏覽器的自訂 HTTP 回應標頭:

abort(403, 'Unauthorized.', $headers);

abort_if()

abort_if 函式如果給定的布林表達式評估為 true,則拋出 HTTP 異常:

abort_if(! Auth::user()->isAdmin(), 403);

像 abort 方法一樣,你也可以提供異常的回應文字作為第三個參數,並將自訂回應標頭陣列作為第四個參數傳遞給該函式。

abort_unless()

abort_unless 函式如果給定的布林表達式評估為 false,則拋出 HTTP 異常:

abort_unless(Auth::user()->isAdmin(), 403);

像 abort 方法一樣,你也可以提供異常的回應文字作為第三個參數,並將自訂回應標頭陣列作為第四個參數傳遞給該函式。

app()

app 函式返回服務容器實例:

$container = app();

你可以傳遞類別或介面名稱以從容器中解析它:

$api = app('HelpSpot\API');

auth()

auth 函式返回一個認證器實例。你可以使用它作為 Auth facade 的替代方案:

$user = auth()->user();

如果需要,你可以指定要存取的守衛實例:

$user = auth('admin')->user();

back()

back 函式產生重新導向 HTTP 回應到使用者的前一個位置:

return back($status = 302, $headers = [], $fallback = '/');

return back();

bcrypt()

bcrypt 函式使用 Bcrypt 雜湊給定值。你可以使用此函式作為 Hash facade 的替代方案:

$password = bcrypt('my-secret-password');

blank()

blank 函式判斷給定值是否為「空白」:

blank('');
blank('   ');
blank(null);
blank(collect());

// true

blank(0);
blank(true);
blank(false);

// false

有關 blank 的反向操作,請參閱 filled 函式。

broadcast()

broadcast 函式將給定事件廣播給其監聽器:

broadcast(new UserRegistered($user));

broadcast(new UserRegistered($user))->toOthers();

broadcast_if()

broadcast_if 函式如果給定的布林表達式評估為 true,則將給定事件廣播給其監聽器:

broadcast_if($user->isActive(), new UserRegistered($user));

broadcast_if($user->isActive(), new UserRegistered($user))->toOthers();

broadcast_unless()

broadcast_unless 函式如果給定的布林表達式評估為 false,則將給定事件廣播給其監聽器:

broadcast_unless($user->isBanned(), new UserRegistered($user));

broadcast_unless($user->isBanned(), new UserRegistered($user))->toOthers();

cache()

cache 函式可用於從 cache 中獲取值。如果快取中不存在給定的鍵,將返回可選的預設值:

$value = cache('key');

$value = cache('key', 'default');

你可以透過將鍵/值對陣列傳遞給函式來將項目新增到快取中。你還應該傳遞快取值應被視為有效的秒數或持續時間:

cache(['key' => 'value'], 300);

cache(['key' => 'value'], now()->addSeconds(10));

class_uses_recursive()

class_uses_recursive 函式返回類別使用的所有 trait,包括其所有父類別使用的 trait:

$traits = class_uses_recursive(App\Models\User::class);

collect()

collect 函式從給定值建立一個 collection 實例:

$collection = collect(['Taylor', 'Abigail']);

config()

config 函式獲取 configuration 變數的值。可以使用「點」語法存取設定值,其中包括檔案名稱和你希望存取的選項。你也可以提供一個預設值,如果設定選項不存在,將返回該預設值:

$value = config('app.timezone');

$value = config('app.timezone', $default);

你可以透過傳遞鍵/值對陣列在執行時設定設定變數。但是,請注意,此函式僅影響當前請求的設定值,不會更新你的實際設定值:

config(['app.debug' => true]);

context()

context 函式從當前 context 中獲取值。你也可以提供一個預設值,如果上下文鍵不存在,將返回該預設值:

$value = context('trace_id');

$value = context('trace_id', $default);

你可以透過傳遞鍵/值對陣列來設定上下文值:

use Illuminate\Support\Str;

context(['trace_id' => Str::uuid()->toString()]);

cookie()

cookie 函式建立一個新的 cookie 實例:

$cookie = cookie('name', 'value', $minutes);

csrf_field()

csrf_field 函式產生一個包含 CSRF 權杖值的 HTML hidden 輸入欄位。例如,使用 Blade 語法:

{{ csrf_field() }}

csrf_token()

csrf_token 函式檢索當前 CSRF 權杖的值:

$token = csrf_token();

decrypt()

decrypt 函式解密給定值。你可以使用此函式作為 Crypt facade 的替代方案:

$password = decrypt($value);

有關 decrypt 的反向操作,請參閱 encrypt 函式。

dd()

dd 函式傾印給定變數並結束指令碼的執行:

dd($value);

dd($value1, $value2, $value3, ...);

如果你不想停止執行指令碼,請改用 dump 函式。

dispatch()

dispatch 函式將給定任務推送到 Laravel 任務佇列:

dispatch(new App\Jobs\SendEmails);

dispatch_sync()

dispatch_sync 函式將給定任務推送到 sync 佇列,以便立即處理:

dispatch_sync(new App\Jobs\SendEmails);

dump()

dump 函式傾印給定變數:

dump($value);

dump($value1, $value2, $value3, ...);

如果你想在傾印變數後停止執行指令碼,請改用 dd 函式。

encrypt()

encrypt 函式加密給定值。你可以使用此函式作為 Crypt facade 的替代方案:

$secret = encrypt('my-secret-value');

有關 encrypt 的反向操作,請參閱 decrypt 函式。

env()

env 函式檢索環境變數的值或返回預設值:

$env = env('APP_ENV');

$env = env('APP_ENV', 'production');

[!WARNING] 如果你在部署過程中執行 config:cache 指令,你應該確保只在設定檔中呼叫 env 函式。一旦設定被快取,.env 檔案將不會被載入,所有對 env 函式的呼叫都將返回外部環境變數(如伺服器級別或系統級別的環境變數)或 null。

event()

event 函式將給定事件分派給其監聽器:

event(new UserRegistered($user));

fake()

fake 函式從容器中解析 Faker 單例,這在模型工廠、資料庫填充、測試和原型設計檢視中建立假資料時非常有用:

@for ($i = 0; $i < 10; $i++)
    <dl>
        <dt>Name</dt>
        <dd>{{ fake()->name() }}</dd>

        <dt>Email</dt>
        <dd>{{ fake()->unique()->safeEmail() }}</dd>
    </dl>
@endfor

預設情況下,fake 函式將使用 config/app.php 設定中的 app.faker_locale 設定選項。通常,此設定選項是透過 APP_FAKER_LOCALE 環境變數設定的。你也可以透過將其傳遞給 fake 函式來指定區域設定。每個區域設定將解析一個單獨的單例:

fake('nl_NL')->name()

filled()

filled 函式判斷給定值是否不為「空白」:

filled(0);
filled(true);
filled(false);

// true

filled('');
filled('   ');
filled(null);
filled(collect());

// false

有關 filled 的反向操作,請參閱 blank 函式。

info()

info 函式將資訊寫入應用程式的 log:

info('Some helpful information!');

也可以將上下文資料陣列傳遞給該函式:

info('User login attempt failed.', ['id' => $user->id]);

literal()

literal 函式建立一個新的 stdClass 實例,並將給定的命名參數作為屬性:

$obj = literal(
    name: 'Joe',
    languages: ['PHP', 'Ruby'],
);

$obj->name; // 'Joe'
$obj->languages; // ['PHP', 'Ruby']

logger()

logger 函式可用於將 debug 級別訊息寫入 log:

logger('Debug message');

也可以將上下文資料陣列傳遞給該函式:

logger('User has logged in.', ['id' => $user->id]);

如果未將任何值傳遞給該函式,將返回 logger 實例:

logger()->error('You are not allowed here.');

method_field()

method_field 函式產生一個包含表單 HTTP 動詞欺騙值的 HTML hidden 輸入欄位。例如,使用 Blade 語法:

<form method="POST">
    {{ method_field('DELETE') }}
</form>

now()

now 函式為當前時間建立一個新的 Illuminate\Support\Carbon 實例:

$now = now();

old()

old 函式檢索快閃到工作階段中的舊輸入值:

$value = old('value');

$value = old('value', 'default');

由於作為第二個參數提供給 old 函式的「預設值」通常是 Eloquent 模型的屬性,因此 Laravel 允許你簡單地將整個 Eloquent 模型作為第二個參數傳遞給 old 函式。這樣做時,Laravel 將假設提供給 old 函式的第一個參數是應被視為「預設值」的 Eloquent 屬性名稱:

{{ old('name', $user->name) }}

// Is equivalent to...

{{ old('name', $user) }}

once()

once 函式執行給定的回呼並將結果快取在記憶體中以供請求期間使用。任何後續使用相同回呼對 once 函式的呼叫都將返回先前快取的結果:

function random(): int
{
    return once(function () {
        return random_int(1, 1000);
    });
}

random(); // 123
random(); // 123 (cached result)
random(); // 123 (cached result)

當從物件實例中執行 once 函式時,快取的結果將對該物件實例是唯一的:

<?php

class NumberService
{
    public function all(): array
    {
        return once(fn () => [1, 2, 3]);
    }
}

$service = new NumberService;

$service->all();
$service->all(); // (cached result)

$secondService = new NumberService;

$secondService->all();
$secondService->all(); // (cached result)

optional()

optional 函式接受任何參數,並允許你存取屬性或呼叫該物件上的方法。如果給定物件為 null,屬性和方法將返回 null 而不是導致錯誤:

return optional($user->address)->street;

{!! old('name', optional($user)->name) !!}

optional 函式也接受一個閉包作為其第二個參數。如果作為第一個參數提供的值不為 null,將呼叫該閉包:

return optional(User::find($id), function (User $user) {
    return $user->name;
});

policy()

policy 方法檢索給定類別的 policy 實例:

$policy = policy(App\Models\User::class);

redirect()

redirect 函式返回 redirect HTTP response,或者如果呼叫時沒有參數,則返回重新導向器實例:

return redirect($to = null, $status = 302, $headers = [], $secure = null);

return redirect('/home');

return redirect()->route('route.name');

report()

report 函式將使用你的 exception handler 報告異常:

report($e);

report 函式也接受字串作為參數。當將字串提供給函式時,函式將建立一個以給定字串為訊息的異常:

report('Something went wrong.');

report_if()

report_if 函式如果給定的布林表達式評估為 true,將使用你的 exception handler 報告異常:

report_if($shouldReport, $e);

report_if($shouldReport, 'Something went wrong.');

report_unless()

report_unless 函式如果給定的布林表達式評估為 false,將使用你的 exception handler 報告異常:

report_unless($reportingDisabled, $e);

report_unless($reportingDisabled, 'Something went wrong.');

request()

request 函式返回當前 request 實例或從當前請求中獲取輸入欄位的值:

$request = request();

$value = request('key', $default);

rescue()

rescue 函式執行給定的閉包並捕獲執行期間發生的任何異常。所有捕獲的異常都將傳送到你的 exception handler;但是,請求將繼續處理:

return rescue(function () {
    return $this->method();
});

你也可以將第二個參數傳遞給 rescue 函式。此參數將是如果在執行閉包時發生異常應返回的「預設」值:

return rescue(function () {
    return $this->method();
}, false);

return rescue(function () {
    return $this->method();
}, function () {
    return $this->failure();
});

可以向 rescue 函式提供 report 參數,以確定是否應透過 report 函式報告異常:

return rescue(function () {
    return $this->method();
}, report: function (Throwable $throwable) {
    return $throwable instanceof InvalidArgumentException;
});

resolve()

resolve 函式使用 service container 將給定類別或介面名稱解析為實例:

$api = resolve('HelpSpot\API');

response()

response 函式建立 response 實例或獲取回應工廠的實例:

return response('Hello World', 200, $headers);

return response()->json(['foo' => 'bar'], 200, $headers);

retry()

retry 函式嘗試執行給定的回呼,直到達到給定的最大嘗試閾值。如果回呼未拋出異常,則將返回其返回值。如果回呼拋出異常,它將自動重試。如果超過最大嘗試次數,將拋出異常:

return retry(5, function () {
    // Attempt 5 times while resting 100ms between attempts...
}, 100);

如果你想手動計算嘗試之間睡眠的毫秒數,可以將閉包作為第三個參數傳遞給 retry 函式:

use Exception;

return retry(5, function () {
    // ...
}, function (int $attempt, Exception $exception) {
    return $attempt * 100;
});

為了方便起見,你可以提供一個陣列作為 retry 函式的第一個參數。此陣列將用於確定後續嘗試之間睡眠的毫秒數:

return retry([100, 200], function () {
    // Sleep for 100ms on first retry, 200ms on second retry...
});

要僅在特定條件下重試,可以將閉包作為第四個參數傳遞給 retry 函式:

use App\Exceptions\TemporaryException;
use Exception;

return retry(5, function () {
    // ...
}, 100, function (Exception $exception) {
    return $exception instanceof TemporaryException;
});

session()

session 函式可用於獲取或設定 session 值:

$value = session('key');

你可以透過將鍵/值對陣列傳遞給函式來設定值:

session(['chairs' => 7, 'instruments' => 3]);

如果未將任何值傳遞給函式,將返回工作階段儲存區:

$value = session()->get('key');

session()->put('key', $value);

tap()

tap 函式接受兩個參數:一個任意的 $value 和一個閉包。$value 將傳遞給閉包,然後由 tap 函式返回。閉包的返回值無關緊要:

$user = tap(User::first(), function (User $user) {
    $user->name = 'Taylor';

    $user->save();
});

如果未將閉包傳遞給 tap 函式,你可以呼叫給定 $value 上的任何方法。你呼叫的方法的返回值將始終為 $value,無論該方法在定義中實際返回什麼。例如,Eloquent update 方法通常返回一個整數。但是,我們可以透過 tap 函式連結 update 方法呼叫來強制該方法返回模型本身:

$user = tap($user)->update([
    'name' => $name,
    'email' => $email,
]);

要向類別新增 tap 方法,你可以將 Illuminate\Support\Traits\Tappable trait 新增到類別中。此 trait 的 tap 方法接受一個閉包作為其唯一參數。物件實例本身將傳遞給閉包,然後由 tap 方法返回:

return $user->tap(function (User $user) {
    // ...
});

throw_if()

throw_if 函式如果給定的布林表達式評估為 true,則拋出給定的異常:

throw_if(! Auth::user()->isAdmin(), AuthorizationException::class);

throw_if(
    ! Auth::user()->isAdmin(),
    AuthorizationException::class,
    'You are not allowed to access this page.'
);

throw_unless()

throw_unless 函式如果給定的布林表達式評估為 false,則拋出給定的異常:

throw_unless(Auth::user()->isAdmin(), AuthorizationException::class);

throw_unless(
    Auth::user()->isAdmin(),
    AuthorizationException::class,
    'You are not allowed to access this page.'
);

today()

today 函式為當前日期建立一個新的 Illuminate\Support\Carbon 實例:

$today = today();

trait_uses_recursive()

trait_uses_recursive 函式返回 trait 使用的所有 trait:

$traits = trait_uses_recursive(\Illuminate\Notifications\Notifiable::class);

transform()

transform 函式如果給定值不為 blank,則對該值執行閉包,然後返回閉包的返回值:

$callback = function (int $value) {
    return $value * 2;
};

$result = transform(5, $callback);

// 10

可以將預設值或閉包作為第三個參數傳遞給該函式。如果給定值為空白,將返回此值:

$result = transform(null, $callback, 'The value is blank');

// The value is blank

validator()

validator 函式使用給定的參數建立一個新的 validator 實例。你可以使用它作為 Validator facade 的替代方案:

$validator = validator($data, $rules, $messages);

value()

value 函式返回給它的值。但是,如果你將閉包傳遞給該函式,則將執行該閉包並返回其返回值:

$result = value(true);

// true

$result = value(function () {
    return false;
});

// false

可以將其他參數傳遞給 value 函式。如果第一個參數是閉包,則其他參數將作為參數傳遞給閉包,否則它們將被忽略:

$result = value(function (string $name) {
    return $name;
}, 'Taylor');

// 'Taylor'

view()

view 函式檢索 view 實例:

return view('auth.login');

with()

with 函式返回給它的值。如果將閉包作為第二個參數傳遞給該函式,則將執行該閉包並返回其返回值:

$callback = function (mixed $value) {
    return is_numeric($value) ? $value * 2 : 0;
};

$result = with(5, $callback);

// 10

$result = with(null, $callback);

// 0

$result = with(5, null);

// 5

when()

when 函式如果給定條件評估為 true,則返回給它的值。否則,返回 null。如果將閉包作為第二個參數傳遞給該函式,則將執行該閉包並返回其返回值:

$value = when(true, 'Hello World');

$value = when(true, fn () => 'Hello World');

when 函式主要用於條件式渲染 HTML 屬性:

<div {!! when($condition, 'wire:poll="calculate"') !!}>
    ...
</div>

其他工具 (Other Utilities)

Benchmarking (Benchmarking)

有時你可能希望快速測試應用程式某些部分的效能。在這種情況下,你可以使用 Benchmark 支援類別來測量給定回呼完成所需的毫秒數:

<?php

use App\Models\User;
use Illuminate\Support\Benchmark;

Benchmark::dd(fn () => User::find(1)); // 0.1 ms

Benchmark::dd([
    'Scenario 1' => fn () => User::count(), // 0.5 ms
    'Scenario 2' => fn () => User::all()->count(), // 20.0 ms
]);

預設情況下,給定的回呼將執行一次(一次迭代),其持續時間將顯示在瀏覽器/控制台中。

要多次呼叫回呼,你可以指定回呼應被呼叫的迭代次數作為方法的第二個參數。當多次執行回呼時,Benchmark 類別將返回在所有迭代中執行回呼所需的平均毫秒數:

Benchmark::dd(fn () => User::count(), iterations: 10); // 0.5 ms

有時,你可能希望在對回呼的執行進行基準測試的同時獲取回呼返回的值。value 方法將返回一個包含回呼返回的值和執行回呼所需的毫秒數的元組:

[$count, $duration] = Benchmark::value(fn () => User::count());

Dates (Dates)

Laravel 包含 Carbon,這是一個強大的日期和時間操作函式庫。要建立一個新的 Carbon 實例,你可以呼叫 now 函式。此函式在你的 Laravel 應用程式中全域可用:

$now = now();

或者,你可以使用 Illuminate\Support\Carbon 類別建立一個新的 Carbon 實例:

use Illuminate\Support\Carbon;

$now = Carbon::now();

有關 Carbon 及其功能的詳細討論,請參閱 Carbon 官方文件。

延遲函式 (Deferred Functions)

雖然 Laravel 的 queued jobs 允許你將任務排隊以進行背景處理,但有時你可能有一些簡單的任務希望延遲執行,而無需設定或維護長時間執行的佇列工作執行緒。

延遲函式允許你將閉包的執行延遲到 HTTP 回應傳送給使用者之後,從而保持應用程式的快速回應。要延遲執行閉包,只需將閉包傳遞給 Illuminate\Support\defer 函式:

use App\Services\Metrics;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use function Illuminate\Support\defer;

Route::post('/orders', function (Request $request) {
    // Create order...

    defer(fn () => Metrics::reportOrder($order));

    return $order;
});

預設情況下,只有當呼叫 Illuminate\Support\defer 的 HTTP 回應、Artisan 指令或佇列任務成功完成時,才會執行延遲函式。這意味著如果請求導致 4xx 或 5xx HTTP 回應,則不會執行延遲函式。如果你希望延遲函式始終執行,可以將 always 方法連結到你的延遲函式:

defer(fn () => Metrics::reportOrder($order))->always();

[!WARNING] 如果你安裝了 Swoole PHP extension,Laravel 的 defer 函式可能會與 Swoole 自己的全域 defer 函式衝突,導致 Web 伺服器錯誤。請確保透過顯式命名空間呼叫 Laravel 的 defer 輔助函式: use function Illuminate\Support\defer;

取消延遲函式 (Cancelling Deferred Functions)

如果你需要在執行之前取消延遲函式,可以使用 forget 方法按名稱取消該函式。要命名延遲函式,請將第二個參數提供給 Illuminate\Support\defer 函式:

defer(fn () => Metrics::report(), 'reportMetrics');

defer()->forget('reportMetrics');

在測試中停用延遲函式 (Disabling Deferred Functions In Tests)

在編寫測試時,停用延遲函式可能很有用。你可以在測試中呼叫 withoutDefer 來指示 Laravel 立即呼叫所有延遲函式:

test('without defer', function () {
    $this->withoutDefer();

    // ...
});

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_without_defer(): void
    {
        $this->withoutDefer();

        // ...
    }
}

如果你想為測試案例中的所有測試停用延遲函式,可以從基礎 TestCase 類別的 setUp 方法中呼叫 withoutDefer 方法:

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void// [tl! add:start]
    {
        parent::setUp();

        $this->withoutDefer();
    }// [tl! add:end]
}

Lottery (Lottery)

Laravel 的 lottery 類別可用於根據給定的機率執行回呼。當你只想為傳入請求的一定百分比執行程式碼時,這特別有用:

use Illuminate\Support\Lottery;

Lottery::odds(1, 20)
    ->winner(fn () => $user->won())
    ->loser(fn () => $user->lost())
    ->choose();

你可以將 Laravel 的 lottery 類別與其他 Laravel 功能結合使用。例如,你可能希望只向異常處理常式報告一小部分慢查詢。而且,由於 lottery 類別是可呼叫的,我們可以將該類別的實例傳遞給任何接受可呼叫物件的方法:

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Lottery;

DB::whenQueryingForLongerThan(
    CarbonInterval::seconds(2),
    Lottery::odds(1, 100)->winner(fn () => report('Querying > 2 seconds.')),
);