跳到内容

辅助函数

简介

Laravel 包含各种全局 “辅助” PHP 函数。许多这些函数被框架本身使用;但是,如果您觉得方便,您可以自由地在自己的应用程序中使用它们。

可用方法

数组 & 对象

数字

路径

URL

杂项

数组 & 对象

Arr::accessible()

Arr::accessible 方法用于判断给定的值是否可以作为数组访问

1use Illuminate\Support\Arr;
2use Illuminate\Support\Collection;
3 
4$isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);
5 
6// true
7 
8$isAccessible = Arr::accessible(new Collection);
9 
10// true
11 
12$isAccessible = Arr::accessible('abc');
13 
14// false
15 
16$isAccessible = Arr::accessible(new stdClass);
17 
18// false

Arr::add()

如果给定的键在数组中不存在或设置为 null,则 Arr::add 方法会将给定的键/值对添加到数组中

1use Illuminate\Support\Arr;
2 
3$array = Arr::add(['name' => 'Desk'], 'price', 100);
4 
5// ['name' => 'Desk', 'price' => 100]
6 
7$array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);
8 
9// ['name' => 'Desk', 'price' => 100]

Arr::collapse()

Arr::collapse 方法将数组的数组折叠成一个单一的数组

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

Arr::crossJoin()

Arr::crossJoin 方法交叉连接给定的数组,返回包含所有可能排列的笛卡尔积

1use Illuminate\Support\Arr;
2 
3$matrix = Arr::crossJoin([1, 2], ['a', 'b']);
4 
5/*
6 [
7 [1, 'a'],
8 [1, 'b'],
9 [2, 'a'],
10 [2, 'b'],
11 ]
12*/
13 
14$matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);
15 
16/*
17 [
18 [1, 'a', 'I'],
19 [1, 'a', 'II'],
20 [1, 'b', 'I'],
21 [1, 'b', 'II'],
22 [2, 'a', 'I'],
23 [2, 'a', 'II'],
24 [2, 'b', 'I'],
25 [2, 'b', 'II'],
26 ]
27*/

Arr::divide()

Arr::divide 方法返回两个数组:一个包含键,另一个包含给定数组的值

1use Illuminate\Support\Arr;
2 
3[$keys, $values] = Arr::divide(['name' => 'Desk']);
4 
5// $keys: ['name']
6 
7// $values: ['Desk']

Arr::dot()

Arr::dot 方法将多维数组展平成一个单层数组,该数组使用 “点” 表示法来指示深度

1use Illuminate\Support\Arr;
2 
3$array = ['products' => ['desk' => ['price' => 100]]];
4 
5$flattened = Arr::dot($array);
6 
7// ['products.desk.price' => 100]

Arr::except()

Arr::except 方法从数组中移除给定的键/值对

1use Illuminate\Support\Arr;
2 
3$array = ['name' => 'Desk', 'price' => 100];
4 
5$filtered = Arr::except($array, ['price']);
6 
7// ['name' => 'Desk']

Arr::exists()

Arr::exists 方法检查给定的键是否存在于提供的数组中

1use Illuminate\Support\Arr;
2 
3$array = ['name' => 'John Doe', 'age' => 17];
4 
5$exists = Arr::exists($array, 'name');
6 
7// true
8 
9$exists = Arr::exists($array, 'salary');
10 
11// false

Arr::first()

Arr::first 方法返回数组中第一个通过给定真值测试的元素

1use Illuminate\Support\Arr;
2 
3$array = [100, 200, 300];
4 
5$first = Arr::first($array, function (int $value, int $key) {
6 return $value >= 150;
7});
8 
9// 200

默认值也可以作为第三个参数传递给该方法。如果没有值通过真值测试,则将返回此值

1use Illuminate\Support\Arr;
2 
3$first = Arr::first($array, $callback, $default);

Arr::flatten()

Arr::flatten 方法将多维数组展平成一个单层数组

1use Illuminate\Support\Arr;
2 
3$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];
4 
5$flattened = Arr::flatten($array);
6 
7// ['Joe', 'PHP', 'Ruby']

Arr::forget()

Arr::forget 方法使用 “点” 表示法从深度嵌套的数组中移除给定的键/值对

1use Illuminate\Support\Arr;
2 
3$array = ['products' => ['desk' => ['price' => 100]]];
4 
5Arr::forget($array, 'products.desk');
6 
7// ['products' => []]

Arr::get()

Arr::get 方法使用 “点” 表示法从深度嵌套的数组中检索值

1use Illuminate\Support\Arr;
2 
3$array = ['products' => ['desk' => ['price' => 100]]];
4 
5$price = Arr::get($array, 'products.desk.price');
6 
7// 100

Arr::get 方法还接受一个默认值,如果指定的键在数组中不存在,则将返回该值

1use Illuminate\Support\Arr;
2 
3$discount = Arr::get($array, 'products.desk.discount', 0);
4 
5// 0

Arr::has()

Arr::has 方法检查给定的项或多个项是否使用 “点” 表示法存在于数组中

1use Illuminate\Support\Arr;
2 
3$array = ['product' => ['name' => 'Desk', 'price' => 100]];
4 
5$contains = Arr::has($array, 'product.name');
6 
7// true
8 
9$contains = Arr::has($array, ['product.price', 'product.discount']);
10 
11// false

Arr::hasAny()

Arr::hasAny 方法检查给定集合中的任何项是否使用 “点” 表示法存在于数组中

1use Illuminate\Support\Arr;
2 
3$array = ['product' => ['name' => 'Desk', 'price' => 100]];
4 
5$contains = Arr::hasAny($array, 'product.name');
6 
7// true
8 
9$contains = Arr::hasAny($array, ['product.name', 'product.discount']);
10 
11// true
12 
13$contains = Arr::hasAny($array, ['category', 'product.discount']);
14 
15// false

Arr::isAssoc()

如果给定的数组是关联数组,则 Arr::isAssoc 方法返回 true。如果数组没有从零开始的顺序数字键,则被认为是 “关联数组”

1use Illuminate\Support\Arr;
2 
3$isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);
4 
5// true
6 
7$isAssoc = Arr::isAssoc([1, 2, 3]);
8 
9// false

Arr::isList()

如果给定数组的键是从零开始的顺序整数,则 Arr::isList 方法返回 true

1use Illuminate\Support\Arr;
2 
3$isList = Arr::isList(['foo', 'bar', 'baz']);
4 
5// true
6 
7$isList = Arr::isList(['product' => ['name' => 'Desk', 'price' => 100]]);
8 
9// false

Arr::join()

Arr::join 方法使用字符串连接数组元素。使用此方法的第二个参数,您还可以为数组的最后一个元素指定连接字符串

1use Illuminate\Support\Arr;
2 
3$array = ['Tailwind', 'Alpine', 'Laravel', 'Livewire'];
4 
5$joined = Arr::join($array, ', ');
6 
7// Tailwind, Alpine, Laravel, Livewire
8 
9$joined = Arr::join($array, ', ', ' and ');
10 
11// Tailwind, Alpine, Laravel and Livewire

Arr::keyBy()

Arr::keyBy 方法通过给定的键对数组进行键控。如果多个项具有相同的键,则只有最后一个项会出现在新数组中

1use Illuminate\Support\Arr;
2 
3$array = [
4 ['product_id' => 'prod-100', 'name' => 'Desk'],
5 ['product_id' => 'prod-200', 'name' => 'Chair'],
6];
7 
8$keyed = Arr::keyBy($array, 'product_id');
9 
10/*
11 [
12 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
13 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
14 ]
15*/

Arr::last()

Arr::last 方法返回数组中最后一个通过给定真值测试的元素

1use Illuminate\Support\Arr;
2 
3$array = [100, 200, 300, 110];
4 
5$last = Arr::last($array, function (int $value, int $key) {
6 return $value >= 150;
7});
8 
9// 300

默认值可以作为第三个参数传递给该方法。如果没有值通过真值测试,则将返回此值

1use Illuminate\Support\Arr;
2 
3$last = Arr::last($array, $callback, $default);

Arr::map()

Arr::map 方法迭代数组,并将每个值和键传递给给定的回调函数。数组值将被回调函数返回的值替换

1use Illuminate\Support\Arr;
2 
3$array = ['first' => 'james', 'last' => 'kirk'];
4 
5$mapped = Arr::map($array, function (string $value, string $key) {
6 return ucfirst($value);
7});
8 
9// ['first' => 'James', 'last' => 'Kirk']

Arr::mapSpread()

Arr::mapSpread 方法迭代数组,并将每个嵌套项值传递给给定的闭包。闭包可以自由修改项并返回它,从而形成一个新的修改项数组

1use Illuminate\Support\Arr;
2 
3$array = [
4 [0, 1],
5 [2, 3],
6 [4, 5],
7 [6, 7],
8 [8, 9],
9];
10 
11$mapped = Arr::mapSpread($array, function (int $even, int $odd) {
12 return $even + $odd;
13});
14 
15/*
16 [1, 5, 9, 13, 17]
17*/

Arr::mapWithKeys()

Arr::mapWithKeys 方法迭代数组,并将每个值传递给给定的回调函数。回调函数应返回一个包含单个键/值对的关联数组

1use Illuminate\Support\Arr;
2 
3$array = [
4 [
5 'name' => 'John',
6 'department' => 'Sales',
7 'email' => '[email protected]',
8 ],
9 [
10 'name' => 'Jane',
11 'department' => 'Marketing',
12 'email' => '[email protected]',
13 ]
14];
15 
16$mapped = Arr::mapWithKeys($array, function (array $item, int $key) {
17 return [$item['email'] => $item['name']];
18});
19 
20/*
21 [
22 '[email protected]' => 'John',
23 '[email protected]' => 'Jane',
24 ]
25*/

Arr::only()

Arr::only 方法仅从给定数组返回指定的键/值对

1use Illuminate\Support\Arr;
2 
3$array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];
4 
5$slice = Arr::only($array, ['name', 'price']);
6 
7// ['name' => 'Desk', 'price' => 100]

Arr::pluck()

Arr::pluck 方法从数组中检索给定键的所有值

1use Illuminate\Support\Arr;
2 
3$array = [
4 ['developer' => ['id' => 1, 'name' => 'Taylor']],
5 ['developer' => ['id' => 2, 'name' => 'Abigail']],
6];
7 
8$names = Arr::pluck($array, 'developer.name');
9 
10// ['Taylor', 'Abigail']

您还可以指定希望如何键控结果列表

1use Illuminate\Support\Arr;
2 
3$names = Arr::pluck($array, 'developer.name', 'developer.id');
4 
5// [1 => 'Taylor', 2 => 'Abigail']

Arr::prepend()

Arr::prepend 方法会将一个项推送到数组的开头

1use Illuminate\Support\Arr;
2 
3$array = ['one', 'two', 'three', 'four'];
4 
5$array = Arr::prepend($array, 'zero');
6 
7// ['zero', 'one', 'two', 'three', 'four']

如果需要,您可以指定应用于该值的键

1use Illuminate\Support\Arr;
2 
3$array = ['price' => 100];
4 
5$array = Arr::prepend($array, 'Desk', 'name');
6 
7// ['name' => 'Desk', 'price' => 100]

Arr::prependKeysWith()

Arr::prependKeysWith 使用给定的前缀预先添加关联数组的所有键名

1use Illuminate\Support\Arr;
2 
3$array = [
4 'name' => 'Desk',
5 'price' => 100,
6];
7 
8$keyed = Arr::prependKeysWith($array, 'product.');
9 
10/*
11 [
12 'product.name' => 'Desk',
13 'product.price' => 100,
14 ]
15*/

Arr::pull()

Arr::pull 方法返回并从数组中移除键/值对

1use Illuminate\Support\Arr;
2 
3$array = ['name' => 'Desk', 'price' => 100];
4 
5$name = Arr::pull($array, 'name');
6 
7// $name: Desk
8 
9// $array: ['price' => 100]

默认值可以作为第三个参数传递给该方法。如果键不存在,则将返回此值

1use Illuminate\Support\Arr;
2 
3$value = Arr::pull($array, $key, $default);

Arr::query()

Arr::query 方法将数组转换为查询字符串

1use Illuminate\Support\Arr;
2 
3$array = [
4 'name' => 'Taylor',
5 'order' => [
6 'column' => 'created_at',
7 'direction' => 'desc'
8 ]
9];
10 
11Arr::query($array);
12 
13// name=Taylor&order[column]=created_at&order[direction]=desc

Arr::random()

Arr::random 方法从数组中返回一个随机值

1use Illuminate\Support\Arr;
2 
3$array = [1, 2, 3, 4, 5];
4 
5$random = Arr::random($array);
6 
7// 4 - (retrieved randomly)

您还可以将要返回的项数指定为可选的第二个参数。请注意,即使只需要一项,提供此参数也会返回一个数组

1use Illuminate\Support\Arr;
2 
3$items = Arr::random($array, 2);
4 
5// [2, 5] - (retrieved randomly)

Arr::set()

Arr::set 方法使用 “点” 表示法在深度嵌套的数组中设置值

1use Illuminate\Support\Arr;
2 
3$array = ['products' => ['desk' => ['price' => 100]]];
4 
5Arr::set($array, 'products.desk.price', 200);
6 
7// ['products' => ['desk' => ['price' => 200]]]

Arr::shuffle()

Arr::shuffle 方法随机打乱数组中的项

1use Illuminate\Support\Arr;
2 
3$array = Arr::shuffle([1, 2, 3, 4, 5]);
4 
5// [3, 2, 5, 1, 4] - (generated randomly)

Arr::sort()

Arr::sort 方法按值对数组进行排序

1use Illuminate\Support\Arr;
2 
3$array = ['Desk', 'Table', 'Chair'];
4 
5$sorted = Arr::sort($array);
6 
7// ['Chair', 'Desk', 'Table']

您还可以通过给定闭包的结果对数组进行排序

1use Illuminate\Support\Arr;
2 
3$array = [
4 ['name' => 'Desk'],
5 ['name' => 'Table'],
6 ['name' => 'Chair'],
7];
8 
9$sorted = array_values(Arr::sort($array, function (array $value) {
10 return $value['name'];
11}));
12 
13/*
14 [
15 ['name' => 'Chair'],
16 ['name' => 'Desk'],
17 ['name' => 'Table'],
18 ]
19*/

Arr::sortDesc()

Arr::sortDesc 方法按值降序对数组进行排序

1use Illuminate\Support\Arr;
2 
3$array = ['Desk', 'Table', 'Chair'];
4 
5$sorted = Arr::sortDesc($array);
6 
7// ['Table', 'Desk', 'Chair']

您还可以通过给定闭包的结果对数组进行排序

1use Illuminate\Support\Arr;
2 
3$array = [
4 ['name' => 'Desk'],
5 ['name' => 'Table'],
6 ['name' => 'Chair'],
7];
8 
9$sorted = array_values(Arr::sortDesc($array, function (array $value) {
10 return $value['name'];
11}));
12 
13/*
14 [
15 ['name' => 'Table'],
16 ['name' => 'Desk'],
17 ['name' => 'Chair'],
18 ]
19*/

Arr::sortRecursive()

Arr::sortRecursive 方法使用 sort 函数对数字索引的子数组进行递归排序,并使用 ksort 函数对关联子数组进行递归排序

1use Illuminate\Support\Arr;
2 
3$array = [
4 ['Roman', 'Taylor', 'Li'],
5 ['PHP', 'Ruby', 'JavaScript'],
6 ['one' => 1, 'two' => 2, 'three' => 3],
7];
8 
9$sorted = Arr::sortRecursive($array);
10 
11/*
12 [
13 ['JavaScript', 'PHP', 'Ruby'],
14 ['one' => 1, 'three' => 3, 'two' => 2],
15 ['Li', 'Roman', 'Taylor'],
16 ]
17*/

如果您希望结果以降序排序,则可以使用 Arr::sortRecursiveDesc 方法。

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

Arr::take()

Arr::take 方法返回一个包含指定数量项的新数组

1use Illuminate\Support\Arr;
2 
3$array = [0, 1, 2, 3, 4, 5];
4 
5$chunk = Arr::take($array, 3);
6 
7// [0, 1, 2]

您还可以传递一个负整数,以从数组末尾获取指定数量的项

1$array = [0, 1, 2, 3, 4, 5];
2 
3$chunk = Arr::take($array, -2);
4 
5// [4, 5]

Arr::toCssClasses()

Arr::toCssClasses 方法有条件地编译 CSS 类字符串。该方法接受一个类数组,其中数组键包含您希望添加的类或多个类,而值是布尔表达式。如果数组元素具有数字键,它将始终包含在呈现的类列表中

1use Illuminate\Support\Arr;
2 
3$isActive = false;
4$hasError = true;
5 
6$array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];
7 
8$classes = Arr::toCssClasses($array);
9 
10/*
11 'p-4 bg-red'
12*/

Arr::toCssStyles()

Arr::toCssStyles 有条件地编译 CSS 样式字符串。该方法接受一个类数组,其中数组键包含您希望添加的类或多个类,而值是布尔表达式。如果数组元素具有数字键,它将始终包含在呈现的类列表中

1use Illuminate\Support\Arr;
2 
3$hasColor = true;
4 
5$array = ['background-color: blue', 'color: blue' => $hasColor];
6 
7$classes = Arr::toCssStyles($array);
8 
9/*
10 'background-color: blue; color: blue;'
11*/

此方法为 Laravel 的功能提供支持,允许使用 Blade 组件的属性包合并类以及 @class Blade 指令

Arr::undot()

Arr::undot 方法将使用 “点” 表示法的单维数组展开为多维数组

1use Illuminate\Support\Arr;
2 
3$array = [
4 'user.name' => 'Kevin Malone',
5 'user.occupation' => 'Accountant',
6];
7 
8$array = Arr::undot($array);
9 
10// ['user' => ['name' => 'Kevin Malone', 'occupation' => 'Accountant']]

Arr::where()

Arr::where 方法使用给定的闭包过滤数组

1use Illuminate\Support\Arr;
2 
3$array = [100, '200', 300, '400', 500];
4 
5$filtered = Arr::where($array, function (string|int $value, int $key) {
6 return is_string($value);
7});
8 
9// [1 => '200', 3 => '400']

Arr::whereNotNull()

Arr::whereNotNull 方法从给定数组中移除所有 null

1use Illuminate\Support\Arr;
2 
3$array = [0, null];
4 
5$filtered = Arr::whereNotNull($array);
6 
7// [0 => 0]

Arr::wrap()

Arr::wrap 方法将给定值包装在一个数组中。如果给定值已经是数组,它将不经修改地返回

1use Illuminate\Support\Arr;
2 
3$string = 'Laravel';
4 
5$array = Arr::wrap($string);
6 
7// ['Laravel']

如果给定值为 null,则将返回一个空数组

1use Illuminate\Support\Arr;
2 
3$array = Arr::wrap(null);
4 
5// []

data_fill()

data_fill 函数使用 “点” 表示法在嵌套数组或对象中设置缺失值

1$data = ['products' => ['desk' => ['price' => 100]]];
2 
3data_fill($data, 'products.desk.price', 200);
4 
5// ['products' => ['desk' => ['price' => 100]]]
6 
7data_fill($data, 'products.desk.discount', 10);
8 
9// ['products' => ['desk' => ['price' => 100, 'discount' => 10]]]

此函数还接受星号作为通配符,并将相应地填充目标

1$data = [
2 'products' => [
3 ['name' => 'Desk 1', 'price' => 100],
4 ['name' => 'Desk 2'],
5 ],
6];
7 
8data_fill($data, 'products.*.price', 200);
9 
10/*
11 [
12 'products' => [
13 ['name' => 'Desk 1', 'price' => 100],
14 ['name' => 'Desk 2', 'price' => 200],
15 ],
16 ]
17*/

data_get()

data_get 函数使用 “点” 表示法从嵌套数组或对象中检索值

1$data = ['products' => ['desk' => ['price' => 100]]];
2 
3$price = data_get($data, 'products.desk.price');
4 
5// 100

data_get 函数还接受一个默认值,如果未找到指定的键,则将返回该值

1$discount = data_get($data, 'products.desk.discount', 0);
2 
3// 0

该函数还接受使用星号的通配符,该通配符可以定位数组或对象的任何键

1$data = [
2 'product-one' => ['name' => 'Desk 1', 'price' => 100],
3 'product-two' => ['name' => 'Desk 2', 'price' => 150],
4];
5 
6data_get($data, '*.name');
7 
8// ['Desk 1', 'Desk 2'];

{first}{last} 占位符可用于检索数组中的第一个或最后一个项

1$flight = [
2 'segments' => [
3 ['from' => 'LHR', 'departure' => '9:00', 'to' => 'IST', 'arrival' => '15:00'],
4 ['from' => 'IST', 'departure' => '16:00', 'to' => 'PKX', 'arrival' => '20:00'],
5 ],
6];
7 
8data_get($flight, 'segments.{first}.arrival');
9 
10// 15:00

data_set()

data_set 函数使用 “点” 表示法在嵌套数组或对象中设置值

1$data = ['products' => ['desk' => ['price' => 100]]];
2 
3data_set($data, 'products.desk.price', 200);
4 
5// ['products' => ['desk' => ['price' => 200]]]

此函数还接受使用星号的通配符,并将相应地在目标上设置值

1$data = [
2 'products' => [
3 ['name' => 'Desk 1', 'price' => 100],
4 ['name' => 'Desk 2', 'price' => 150],
5 ],
6];
7 
8data_set($data, 'products.*.price', 200);
9 
10/*
11 [
12 'products' => [
13 ['name' => 'Desk 1', 'price' => 200],
14 ['name' => 'Desk 2', 'price' => 200],
15 ],
16 ]
17*/

默认情况下,任何现有值都将被覆盖。如果您希望仅在值不存在时才设置值,则可以将 false 作为函数的第四个参数传递

1$data = ['products' => ['desk' => ['price' => 100]]];
2 
3data_set($data, 'products.desk.price', 200, overwrite: false);
4 
5// ['products' => ['desk' => ['price' => 100]]]

data_forget()

data_forget 函数使用 “点” 表示法移除嵌套数组或对象中的值

1$data = ['products' => ['desk' => ['price' => 100]]];
2 
3data_forget($data, 'products.desk.price');
4 
5// ['products' => ['desk' => []]]

此函数还接受使用星号的通配符,并将相应地移除目标上的值

1$data = [
2 'products' => [
3 ['name' => 'Desk 1', 'price' => 100],
4 ['name' => 'Desk 2', 'price' => 150],
5 ],
6];
7 
8data_forget($data, 'products.*.price');
9 
10/*
11 [
12 'products' => [
13 ['name' => 'Desk 1'],
14 ['name' => 'Desk 2'],
15 ],
16 ]
17*/

head()

head 函数返回给定数组中的第一个元素

1$array = [100, 200, 300];
2 
3$first = head($array);
4 
5// 100

last()

last 函数返回给定数组中的最后一个元素

1$array = [100, 200, 300];
2 
3$last = last($array);
4 
5// 300

数字

Number::abbreviate()

Number::abbreviate 方法返回提供的数值的人类可读格式,并带有单位的缩写

1use Illuminate\Support\Number;
2 
3$number = Number::abbreviate(1000);
4 
5// 1K
6 
7$number = Number::abbreviate(489939);
8 
9// 490K
10 
11$number = Number::abbreviate(1230000, precision: 2);
12 
13// 1.23M

Number::clamp()

Number::clamp 方法确保给定的数字保持在指定的范围内。如果该数字低于最小值,则返回最小值。如果该数字高于最大值,则返回最大值

1use Illuminate\Support\Number;
2 
3$number = Number::clamp(105, min: 10, max: 100);
4 
5// 100
6 
7$number = Number::clamp(5, min: 10, max: 100);
8 
9// 10
10 
11$number = Number::clamp(10, min: 10, max: 100);
12 
13// 10
14 
15$number = Number::clamp(20, min: 10, max: 100);
16 
17// 20

Number::currency()

Number::currency 方法以字符串形式返回给定值的货币表示形式

1use Illuminate\Support\Number;
2 
3$currency = Number::currency(1000);
4 
5// $1,000.00
6 
7$currency = Number::currency(1000, in: 'EUR');
8 
9// €1,000.00
10 
11$currency = Number::currency(1000, in: 'EUR', locale: 'de');
12 
13// 1.000,00 €

Number::defaultCurrency()

Number::defaultCurrency 方法返回 Number 类正在使用的默认货币

1use Illuminate\Support\Number;
2 
3$currency = Number::defaultCurrency();
4 
5// USD

Number::defaultLocale()

Number::defaultLocale 方法返回 Number 类正在使用的默认区域设置

1use Illuminate\Support\Number;
2 
3$locale = Number::defaultLocale();
4 
5// en

Number::fileSize()

Number::fileSize 方法以字符串形式返回给定字节值的文件大小表示形式

1use Illuminate\Support\Number;
2 
3$size = Number::fileSize(1024);
4 
5// 1 KB
6 
7$size = Number::fileSize(1024 * 1024);
8 
9// 1 MB
10 
11$size = Number::fileSize(1024, precision: 2);
12 
13// 1.00 KB

Number::forHumans()

Number::forHumans 方法返回提供的数值的人类可读格式

1use Illuminate\Support\Number;
2 
3$number = Number::forHumans(1000);
4 
5// 1 thousand
6 
7$number = Number::forHumans(489939);
8 
9// 490 thousand
10 
11$number = Number::forHumans(1230000, precision: 2);
12 
13// 1.23 million

Number::format()

Number::format 方法将给定的数字格式化为特定于区域设置的字符串

1use Illuminate\Support\Number;
2 
3$number = Number::format(100000);
4 
5// 100,000
6 
7$number = Number::format(100000, precision: 2);
8 
9// 100,000.00
10 
11$number = Number::format(100000.123, maxPrecision: 2);
12 
13// 100,000.12
14 
15$number = Number::format(100000, locale: 'de');
16 
17// 100.000

Number::ordinal()

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

1use Illuminate\Support\Number;
2 
3$number = Number::ordinal(1);
4 
5// 1st
6 
7$number = Number::ordinal(2);
8 
9// 2nd
10 
11$number = Number::ordinal(21);
12 
13// 21st

Number::pairs()

Number::pairs 方法根据指定的范围和步长值生成数字对(子范围)数组。此方法可用于将较大的数字范围划分为较小的、可管理的子范围,用于分页或批处理任务等。pairs 方法返回一个数组的数组,其中每个内部数组代表一对(子范围)数字

1use Illuminate\Support\Number;
2 
3$result = Number::pairs(25, 10);
4 
5// [[1, 10], [11, 20], [21, 25]]
6 
7$result = Number::pairs(25, 10, offset: 0);
8 
9// [[0, 10], [10, 20], [20, 25]]

Number::percentage()

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

1use Illuminate\Support\Number;
2 
3$percentage = Number::percentage(10);
4 
5// 10%
6 
7$percentage = Number::percentage(10, precision: 2);
8 
9// 10.00%
10 
11$percentage = Number::percentage(10.123, maxPrecision: 2);
12 
13// 10.12%
14 
15$percentage = Number::percentage(10, precision: 2, locale: 'de');
16 
17// 10,00%

Number::spell()

Number::spell 方法将给定的数字转换为单词字符串

1use Illuminate\Support\Number;
2 
3$number = Number::spell(102);
4 
5// one hundred and two
6 
7$number = Number::spell(88, locale: 'fr');
8 
9// quatre-vingt-huit

after 参数允许您指定一个值,在此值之后应拼写出所有数字

1$number = Number::spell(10, after: 10);
2 
3// 10
4 
5$number = Number::spell(11, after: 10);
6 
7// eleven

until 参数允许您指定一个值,在此值之前应拼写出所有数字

1$number = Number::spell(5, until: 10);
2 
3// five
4 
5$number = Number::spell(10, until: 10);
6 
7// 10

Number::trim()

Number::trim 方法移除给定数字的小数点后的任何尾随零数字

1use Illuminate\Support\Number;
2 
3$number = Number::trim(12.0);
4 
5// 12
6 
7$number = Number::trim(12.30);
8 
9// 12.3

Number::useLocale()

Number::useLocale 方法全局设置默认数字区域设置,这会影响后续调用 Number 类的方法时数字和货币的格式化方式

1use Illuminate\Support\Number;
2 
3/**
4 * Bootstrap any application services.
5 */
6public function boot(): void
7{
8 Number::useLocale('de');
9}

Number::withLocale()

Number::withLocale 方法使用指定的区域设置执行给定的闭包,然后在回调函数执行后恢复原始区域设置

1use Illuminate\Support\Number;
2 
3$number = Number::withLocale('de', function () {
4 return Number::format(1500);
5});

Number::useCurrency()

Number::useCurrency 方法全局设置默认数字货币,这会影响后续调用 Number 类的方法时货币的格式化方式

1use Illuminate\Support\Number;
2 
3/**
4 * Bootstrap any application services.
5 */
6public function boot(): void
7{
8 Number::useCurrency('GBP');
9}

Number::withCurrency()

Number::withCurrency 方法使用指定的货币执行给定的闭包,然后在回调函数执行后恢复原始货币

1use Illuminate\Support\Number;
2 
3$number = Number::withCurrency('GBP', function () {
4 // ...
5});

路径

app_path()

app_path 函数返回应用程序 app 目录的完全限定路径。您还可以使用 app_path 函数生成相对于应用程序目录的文件的完全限定路径

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

base_path()

base_path 函数返回应用程序根目录的完全限定路径。您还可以使用 base_path 函数生成相对于项目根目录的给定文件的完全限定路径

1$path = base_path();
2 
3$path = base_path('vendor/bin');

config_path()

config_path 函数返回应用程序 config 目录的完全限定路径。您还可以使用 config_path 函数生成应用程序配置目录中给定文件的完全限定路径

1$path = config_path();
2 
3$path = config_path('app.php');

database_path()

database_path 函数返回应用程序 database 目录的完全限定路径。您还可以使用 database_path 函数生成数据库目录中给定文件的完全限定路径

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

lang_path()

lang_path 函数返回应用程序 lang 目录的完全限定路径。您还可以使用 lang_path 函数生成目录中给定文件的完全限定路径

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

默认情况下,Laravel 应用程序骨架不包含 lang 目录。如果您想自定义 Laravel 的语言文件,您可以通过 lang:publish Artisan 命令发布它们。

mix()

mix 函数返回 版本化的 Mix 文件 的路径

1$path = mix('css/app.css');

public_path()

public_path 函数返回应用程序 public 目录的完全限定路径。您还可以使用 public_path 函数生成公共目录中给定文件的完全限定路径

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

resource_path()

resource_path 函数返回应用程序 resources 目录的完全限定路径。您还可以使用 resource_path 函数生成资源目录中给定文件的完全限定路径

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

storage_path()

storage_path 函数返回应用程序 storage 目录的完全限定路径。您还可以使用 storage_path 函数生成存储目录中给定文件的完全限定路径

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

URL

action()

action 函数为给定的控制器操作生成 URL

1use App\Http\Controllers\HomeController;
2 
3$url = action([HomeController::class, 'index']);

如果该方法接受路由参数,您可以将它们作为第二个参数传递给该方法

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

asset()

asset 函数使用当前请求的方案(HTTP 或 HTTPS)生成资源的 URL

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

您可以通过在 .env 文件中设置 ASSET_URL 变量来配置资源 URL 主机。如果您将资源托管在 Amazon S3 或其他 CDN 等外部服务上,这将非常有用

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

route()

route 函数为给定的命名路由生成 URL

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

如果路由接受参数,您可以将它们作为第二个参数传递给该函数

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

默认情况下,route 函数生成绝对 URL。如果您希望生成相对 URL,可以将 false 作为函数的第三个参数传递

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

secure_asset()

secure_asset 函数使用 HTTPS 为资源生成 URL

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

secure_url()

secure_url 函数为给定的路径生成完全限定的 HTTPS URL。其他 URL 段可以在函数的第二个参数中传递

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

to_route()

to_route 函数为给定的命名路由生成重定向 HTTP 响应

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

如有必要,您可以将应分配给重定向的 HTTP 状态代码以及任何其他响应标头作为 to_route 方法的第三个和第四个参数传递

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

url()

url 函数为给定路径生成完全限定的 URL

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

如果没有提供路径,则返回 Illuminate\Routing\UrlGenerator 实例

1$current = url()->current();
2 
3$full = url()->full();
4 
5$previous = url()->previous();

杂项

abort()

abort 函数抛出 HTTP 异常,该异常将由 异常处理器呈现

1abort(403);

您还可以提供异常的消息和应发送到浏览器的自定义 HTTP 响应标头

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

abort_if()

如果给定的布尔表达式求值为 true,则 abort_if 函数抛出 HTTP 异常

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

abort 方法一样,您还可以提供异常的响应文本作为第三个参数,并将自定义响应标头数组作为函数的第四个参数。

abort_unless()

如果给定的布尔表达式求值为 false,则 abort_unless 函数抛出 HTTP 异常

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

abort 方法一样,您还可以提供异常的响应文本作为第三个参数,并将自定义响应标头数组作为函数的第四个参数。

app()

app 函数返回服务容器实例

1$container = app();

您可以传递类或接口名称以从容器中解析它

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

auth()

auth 函数返回身份验证器实例。您可以将其用作 Auth 外观模式的替代方法

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

如果需要,您可以指定要访问的守卫实例

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

back()

back 函数为用户的上一个位置生成重定向 HTTP 响应

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

bcrypt()

bcrypt 函数使用 Bcrypt 哈希给定的值。您可以将此函数用作 Hash 外观模式的替代方法

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

blank()

blank 函数确定给定值是否为 “空”

1blank('');
2blank(' ');
3blank(null);
4blank(collect());
5 
6// true
7 
8blank(0);
9blank(true);
10blank(false);
11 
12// false

有关 blank 的反义词,请参阅 filled 方法。

broadcast()

broadcast 函数广播给定的事件到其监听器

1broadcast(new UserRegistered($user));
2 
3broadcast(new UserRegistered($user))->toOthers();

cache()

cache 函数可用于从缓存中获取值。如果给定的键在缓存中不存在,则将返回可选的默认值

1$value = cache('key');
2 
3$value = cache('key', 'default');

您可以通过将键/值对数组传递给函数来向缓存中添加项。您还应该传递缓存值应被视为有效的秒数或持续时间

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

class_uses_recursive()

class_uses_recursive 函数返回类使用的所有 trait,包括其所有父类使用的 trait

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

collect()

collect 函数从给定值创建一个集合实例

1$collection = collect(['taylor', 'abigail']);

config()

config 函数获取配置变量的值。可以使用 “点” 语法访问配置值,其中包括文件名和要访问的选项的名称。可以指定默认值,如果配置选项不存在,则返回该默认值

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

您可以在运行时通过传递键/值对数组来设置配置变量。但是,请注意,此函数仅影响当前请求的配置值,并且不会更新您的实际配置值

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

context()

context 函数从当前上下文中获取值。可以指定默认值,如果上下文键不存在,则返回该默认值

1$value = context('trace_id');
2 
3$value = context('trace_id', $default);

您可以通过传递键/值对数组来设置上下文值

1use Illuminate\Support\Str;
2 
3context(['trace_id' => Str::uuid()->toString()]);

cookie 函数创建一个新的cookie实例

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

csrf_field()

csrf_field 函数生成一个 HTML hidden input 字段,其中包含 CSRF 令牌的值。例如,使用Blade 语法

1{{ csrf_field() }}

csrf_token()

csrf_token 函数检索当前 CSRF 令牌的值

1$token = csrf_token();

decrypt()

decrypt 函数解密给定的值。您可以将此函数用作 Crypt facade 的替代方案

1$password = decrypt($value);

dd()

dd 函数转储给定的变量并结束脚本的执行

1dd($value);
2 
3dd($value1, $value2, $value3, ...);

如果您不想停止脚本的执行,请改用 dump 函数。

dispatch()

dispatch 函数将给定的 job 推送到 Laravel job 队列

1dispatch(new App\Jobs\SendEmails);

dispatch_sync()

dispatch_sync 函数将给定的 job 推送到 sync 队列,以便立即处理

1dispatch_sync(new App\Jobs\SendEmails);

dump()

dump 函数转储给定的变量

1dump($value);
2 
3dump($value1, $value2, $value3, ...);

如果您想在转储变量后停止执行脚本,请改用 dd 函数。

encrypt()

encrypt 函数加密给定的值。您可以将此函数用作 Crypt facade 的替代方案

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

env()

env 函数检索 环境变量 的值或返回默认值

1$env = env('APP_ENV');
2 
3$env = env('APP_ENV', 'production');

如果您在部署过程中执行 config:cache 命令,则应确保仅从配置文件中调用 env 函数。一旦配置被缓存,.env 文件将不会被加载,所有对 env 函数的调用都将返回 null

event()

event 函数将给定的 事件 分派给其监听器

1event(new UserRegistered($user));

fake()

fake 函数从容器中解析 Faker 单例,这在模型工厂、数据库填充、测试和原型视图中创建虚假数据时非常有用

1@for($i = 0; $i < 10; $i++)
2 <dl>
3 <dt>Name</dt>
4 <dd>{{ fake()->name() }}</dd>
5 
6 <dt>Email</dt>
7 <dd>{{ fake()->unique()->safeEmail() }}</dd>
8 </dl>
9@endfor

默认情况下,fake 函数将使用 config/app.php 配置文件中的 app.faker_locale 配置选项。通常,此配置选项通过 APP_FAKER_LOCALE 环境变量设置。您也可以通过将其传递给 fake 函数来指定区域设置。每个区域设置将解析一个单独的单例

1fake('nl_NL')->name()

filled()

filled 函数确定给定的值是否不是“空白”

1filled(0);
2filled(true);
3filled(false);
4 
5// true
6 
7filled('');
8filled(' ');
9filled(null);
10filled(collect());
11 
12// false

对于 filled 的逆操作,请参阅 blank 方法。

info()

info 函数会将信息写入应用程序的 日志

1info('Some helpful information!');

上下文数据的数组也可以传递给该函数

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

literal()

literal 函数使用给定的命名参数作为属性创建一个新的 stdClass 实例

1$obj = literal(
2 name: 'Joe',
3 languages: ['PHP', 'Ruby'],
4);
5 
6$obj->name; // 'Joe'
7$obj->languages; // ['PHP', 'Ruby']

logger()

logger 函数可用于将 debug 级别的消息写入 日志

1logger('Debug message');

上下文数据的数组也可以传递给该函数

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

如果没有值传递给该函数,则将返回一个 logger 实例

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

method_field()

method_field 函数生成一个 HTML hidden input 字段,其中包含表单 HTTP 动词的伪造值。例如,使用 Blade 语法

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

now()

now 函数为当前时间创建一个新的 Illuminate\Support\Carbon 实例

1$now = now();

old()

old 函数检索闪存到会话中的旧输入

1$value = old('value');
2 
3$value = old('value', 'default');

由于作为 old 函数的第二个参数提供的“默认值”通常是 Eloquent 模型的属性,Laravel 允许您简单地将整个 Eloquent 模型作为 old 函数的第二个参数传递。这样做时,Laravel 将假定提供给 old 函数的第一个参数应该是被视为“默认值”的 Eloquent 属性的名称

1{{ old('name', $user->name) }}
2 
3// Is equivalent to...
4 
5{{ old('name', $user) }}

once()

once 函数执行给定的回调,并将结果缓存在内存中,持续到请求结束。后续使用相同回调对 once 函数的任何调用都将返回先前缓存的结果

1function random(): int
2{
3 return once(function () {
4 return random_int(1, 1000);
5 });
6}
7 
8random(); // 123
9random(); // 123 (cached result)
10random(); // 123 (cached result)

当从对象实例内部执行 once 函数时,缓存的结果将对该对象实例是唯一的

1<?php
2 
3class NumberService
4{
5 public function all(): array
6 {
7 return once(fn () => [1, 2, 3]);
8 }
9}
10 
11$service = new NumberService;
12 
13$service->all();
14$service->all(); // (cached result)
15 
16$secondService = new NumberService;
17 
18$secondService->all();
19$secondService->all(); // (cached result)

optional()

optional 函数接受任何参数,并允许您访问该对象的属性或调用方法。如果给定的对象为 null,则属性和方法将返回 null 而不是导致错误

1return optional($user->address)->street;
2 
3{!! old('name', optional($user)->name) !!}

optional 函数也接受闭包作为其第二个参数。如果作为第一个参数提供的值不为 null,则将调用该闭包

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

policy()

policy 方法检索给定类的 policy 实例

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

redirect()

redirect 函数返回 重定向 HTTP 响应,或者在不带参数调用时返回 redirector 实例

1return redirect($to = null, $status = 302, $headers = [], $https = null);
2 
3return redirect('/home');
4 
5return redirect()->route('route.name');

report()

report 函数将使用您的 异常处理程序 报告异常

1report($e);

report 函数也接受字符串作为参数。当向该函数提供字符串时,该函数将创建一个异常,并将给定的字符串作为其消息

1report('Something went wrong.');

report_if()

如果给定的条件为 truereport_if 函数将使用您的 异常处理程序 报告异常

1report_if($shouldReport, $e);
2 
3report_if($shouldReport, 'Something went wrong.');

report_unless()

如果给定的条件为 falsereport_unless 函数将使用您的 异常处理程序 报告异常

1report_unless($reportingDisabled, $e);
2 
3report_unless($reportingDisabled, 'Something went wrong.');

request()

request 函数返回当前的 request 实例,或从当前请求中获取输入字段的值

1$request = request();
2 
3$value = request('key', $default);

rescue()

rescue 函数执行给定的闭包,并捕获在其执行期间发生的任何异常。所有捕获的异常都将发送到您的 异常处理程序;但是,请求将继续处理

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

您也可以将第二个参数传递给 rescue 函数。此参数将是“默认”值,如果在执行闭包时发生异常,则应返回该值

1return rescue(function () {
2 return $this->method();
3}, false);
4 
5return rescue(function () {
6 return $this->method();
7}, function () {
8 return $this->failure();
9});

可以向 rescue 函数提供 report 参数,以确定是否应通过 report 函数报告异常

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

resolve()

resolve 函数使用 服务容器 将给定的类或接口名称解析为实例

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

response()

response 函数创建一个 response 实例或获取 response 工厂的实例

1return response('Hello World', 200, $headers);
2 
3return response()->json(['foo' => 'bar'], 200, $headers);

retry()

retry 函数尝试执行给定的回调,直到达到给定的最大尝试阈值。如果回调没有抛出异常,则将返回其返回值。如果回调抛出异常,它将自动重试。如果超过最大尝试次数,则将抛出异常

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

如果您想手动计算每次尝试之间休眠的毫秒数,您可以将闭包作为 retry 函数的第三个参数传递

1use Exception;
2 
3return retry(5, function () {
4 // ...
5}, function (int $attempt, Exception $exception) {
6 return $attempt * 100;
7});

为了方便起见,您可以提供一个数组作为 retry 函数的第一个参数。此数组将用于确定后续尝试之间休眠的毫秒数

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

要仅在特定条件下重试,您可以将闭包作为 retry 函数的第四个参数传递

1use Exception;
2 
3return retry(5, function () {
4 // ...
5}, 100, function (Exception $exception) {
6 return $exception instanceof RetryException;
7});

session()

session 函数可用于获取或设置 session

1$value = session('key');

您可以通过将键/值对数组传递给函数来设置值

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

如果没有值传递给该函数,则将返回会话存储

1$value = session()->get('key');
2 
3session()->put('key', $value);

tap()

tap 函数接受两个参数:任意 $value 和一个闭包。$value 将传递给闭包,然后由 tap 函数返回。闭包的返回值无关紧要

1$user = tap(User::first(), function (User $user) {
2 $user->name = 'taylor';
3 
4 $user->save();
5});

如果没有闭包传递给 tap 函数,您可以调用给定 $value 上的任何方法。您调用的方法的返回值将始终是 $value,而不管该方法在其定义中实际返回什么。例如,Eloquent update 方法通常返回一个整数。但是,我们可以通过链式调用 tap 函数的 update 方法调用来强制该方法返回模型本身

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

要向类添加 tap 方法,您可以将 Illuminate\Support\Traits\Tappable trait 添加到该类。此 trait 的 tap 方法仅接受一个参数 Closure。对象实例本身将传递给 Closure,然后由 tap 方法返回

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

throw_if()

如果给定的布尔表达式的计算结果为 truethrow_if 函数将抛出给定的异常

1throw_if(! Auth::user()->isAdmin(), AuthorizationException::class);
2 
3throw_if(
4 ! Auth::user()->isAdmin(),
5 AuthorizationException::class,
6 'You are not allowed to access this page.'
7);

throw_unless()

如果给定的布尔表达式的计算结果为 falsethrow_unless 函数将抛出给定的异常

1throw_unless(Auth::user()->isAdmin(), AuthorizationException::class);
2 
3throw_unless(
4 Auth::user()->isAdmin(),
5 AuthorizationException::class,
6 'You are not allowed to access this page.'
7);

today()

today 函数为当前日期创建一个新的 Illuminate\Support\Carbon 实例

1$today = today();

trait_uses_recursive()

trait_uses_recursive 函数返回 trait 使用的所有 trait

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

transform()

如果给定值不是 blanktransform 函数将在给定值上执行闭包,然后返回闭包的返回值

1$callback = function (int $value) {
2 return $value * 2;
3};
4 
5$result = transform(5, $callback);
6 
7// 10

默认值或闭包可以作为函数的第三个参数传递。如果给定值为空白,则将返回此值

1$result = transform(null, $callback, 'The value is blank');
2 
3// The value is blank

validator()

validator 函数使用给定的参数创建一个新的 validator 实例。您可以将其用作 Validator facade 的替代方案

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

value()

value 函数返回它被赋予的值。但是,如果您将闭包传递给该函数,则将执行该闭包并返回其返回值

1$result = value(true);
2 
3// true
4 
5$result = value(function () {
6 return false;
7});
8 
9// false

其他参数可以传递给 value 函数。如果第一个参数是闭包,则其他参数将作为参数传递给闭包,否则将被忽略

1$result = value(function (string $name) {
2 return $name;
3}, 'Taylor');
4 
5// 'Taylor'

view()

view 函数检索一个 view 实例

1return view('auth.login');

with()

with 函数返回它被赋予的值。如果将闭包作为函数的第二个参数传递,则将执行该闭包并返回其返回值

1$callback = function (mixed $value) {
2 return is_numeric($value) ? $value * 2 : 0;
3};
4 
5$result = with(5, $callback);
6 
7// 10
8 
9$result = with(null, $callback);
10 
11// 0
12 
13$result = with(5, null);
14 
15// 5

when()

如果给定的条件评估为 truewhen 函数将返回它被赋予的值。否则,将返回 null。如果将闭包作为函数的第二个参数传递,则将执行该闭包并返回其返回值

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

when 函数主要用于有条件地渲染 HTML 属性

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

其他工具

基准测试

有时您可能希望快速测试应用程序某些部分的性能。在这些情况下,您可以利用 Benchmark 支持类来测量给定回调完成所需的毫秒数

1<?php
2 
3use App\Models\User;
4use Illuminate\Support\Benchmark;
5 
6Benchmark::dd(fn () => User::find(1)); // 0.1 ms
7 
8Benchmark::dd([
9 'Scenario 1' => fn () => User::count(), // 0.5 ms
10 'Scenario 2' => fn () => User::all()->count(), // 20.0 ms
11]);

默认情况下,给定的回调将执行一次(一次迭代),并且它们的持续时间将显示在浏览器/控制台中。

要多次调用回调,您可以指定回调应作为该方法的第二个参数调用的迭代次数。当多次执行回调时,Benchmark 类将返回在所有迭代中执行回调所需的平均毫秒数

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

有时,您可能希望在基准测试回调执行的同时仍然获取回调返回的值。value 方法将返回一个元组,其中包含回调返回的值和执行回调所需的毫秒数

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

日期

Laravel 包含 Carbon,这是一个强大的日期和时间操作库。要创建新的 Carbon 实例,您可以调用 now 函数。此函数在您的 Laravel 应用程序中全局可用

1$now = now();

或者,您可以使用 Illuminate\Support\Carbon 类创建一个新的 Carbon 实例

1use Illuminate\Support\Carbon;
2 
3$now = Carbon::now();

有关 Carbon 及其功能的详细讨论,请查阅 官方 Carbon 文档

延迟函数

延迟函数目前处于 Beta 版,我们正在收集社区反馈。

虽然 Laravel 的 queued jobs 允许您将任务排队以进行后台处理,但有时您可能有一些简单的任务想要延迟,而无需配置或维护长时间运行的队列 worker。

延迟函数允许您延迟闭包的执行,直到 HTTP 响应已发送给用户之后,从而保持应用程序的快速响应。要延迟闭包的执行,只需将闭包传递给 Illuminate\Support\defer 函数

1use App\Services\Metrics;
2use Illuminate\Http\Request;
3use Illuminate\Support\Facades\Route;
4use function Illuminate\Support\defer;
5 
6Route::post('/orders', function (Request $request) {
7 // Create order...
8 
9 defer(fn () => Metrics::reportOrder($order));
10 
11 return $order;
12});

默认情况下,仅当从中调用 Illuminate\Support\defer 的 HTTP 响应、Artisan 命令或队列 job 成功完成时,才会执行延迟函数。这意味着如果请求导致 4xx5xx HTTP 响应,则不会执行延迟函数。如果您希望延迟函数始终执行,则可以将 always 方法链接到您的延迟函数

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

取消延迟函数

如果您需要在延迟函数执行之前取消它,则可以使用 forget 方法按名称取消该函数。要命名延迟函数,请向 Illuminate\Support\defer 函数提供第二个参数

1defer(fn () => Metrics::report(), 'reportMetrics');
2 
3defer()->forget('reportMetrics');

延迟函数兼容性

如果您从 Laravel 10.x 应用程序升级到 Laravel 11.x 并且应用程序的骨架仍然包含 app/Http/Kernel.php 文件,则应将 InvokeDeferredCallbacks 中间件添加到内核的 $middleware 属性的开头

1protected $middleware = [
2 \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
3 \App\Http\Middleware\TrustProxies::class,
4 // ...
5];

在测试中禁用延迟函数

编写测试时,禁用延迟函数可能很有用。您可以在测试中调用 withoutDefer 以指示 Laravel 立即调用所有延迟函数

1test('without defer', function () {
2 $this->withoutDefer();
3 
4 // ...
5});
1use Tests\TestCase;
2 
3class ExampleTest extends TestCase
4{
5 public function test_without_defer(): void
6 {
7 $this->withoutDefer();
8 
9 // ...
10 }
11}

如果您想在测试用例中的所有测试中禁用延迟函数,则可以从基本 TestCase 类上的 setUp 方法中调用 withoutDefer 方法

1<?php
2 
3namespace Tests;
4 
5use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
6 
7abstract class TestCase extends BaseTestCase
8{
9 protected function setUp(): void
10 {
11 parent::setUp();
12 
13 $this->withoutDefer();
14 }
15}

抽奖

Laravel 的 lottery 类可用于根据一组给定的赔率执行回调。当您只想对一部分传入请求执行代码时,这可能特别有用

1use Illuminate\Support\Lottery;
2 
3Lottery::odds(1, 20)
4 ->winner(fn () => $user->won())
5 ->loser(fn () => $user->lost())
6 ->choose();

您可以将 Laravel 的 lottery 类与其他 Laravel 功能结合使用。例如,您可能希望仅向异常处理程序报告一小部分慢查询。而且,由于 lottery 类是可调用的,我们可以将该类的实例传递到任何接受可调用的方法中

1use Carbon\CarbonInterval;
2use Illuminate\Support\Facades\DB;
3use Illuminate\Support\Lottery;
4 
5DB::whenQueryingForLongerThan(
6 CarbonInterval::seconds(2),
7 Lottery::odds(1, 100)->winner(fn () => report('Querying > 2 seconds.')),
8);

测试 Lottery

Laravel 提供了一些简单的方法,使您可以轻松测试应用程序的 lottery 调用

1// Lottery will always win...
2Lottery::alwaysWin();
3 
4// Lottery will always lose...
5Lottery::alwaysLose();
6 
7// Lottery will win then lose, and finally return to normal behavior...
8Lottery::fix([true, false]);
9 
10// Lottery will return to normal behavior...
11Lottery::determineResultsNormally();

管道

Laravel 的 Pipeline facade 提供了一种方便的方式,可以将给定的输入“管道传输”到一系列可调用类、闭包或可调用对象,使每个类都有机会检查或修改输入并调用管道中的下一个可调用对象

1use Closure;
2use App\Models\User;
3use Illuminate\Support\Facades\Pipeline;
4 
5$user = Pipeline::send($user)
6 ->through([
7 function (User $user, Closure $next) {
8 // ...
9 
10 return $next($user);
11 },
12 function (User $user, Closure $next) {
13 // ...
14 
15 return $next($user);
16 },
17 ])
18 ->then(fn (User $user) => $user);

如您所见,管道中的每个可调用类或闭包都提供了输入和一个 $next 闭包。调用 $next 闭包将调用管道中的下一个可调用对象。您可能已经注意到,这与 中间件 非常相似。

当管道中的最后一个可调用对象调用 $next 闭包时,将调用提供给 then 方法的可调用对象。通常,此可调用对象将仅返回给定的输入。

当然,如前所述,您不限于为管道提供闭包。您还可以提供可调用类。如果提供了类名,则将通过 Laravel 的 服务容器 实例化该类,从而允许将依赖项注入到可调用类中

1$user = Pipeline::send($user)
2 ->through([
3 GenerateProfilePhoto::class,
4 ActivateSubscription::class,
5 SendWelcomeEmail::class,
6 ])
7 ->then(fn (User $user) => $user);

睡眠

Laravel 的 Sleep 类是 PHP 原生 sleepusleep 函数的轻量级包装器,在提供更强可测试性的同时,还公开了一个对开发人员友好的 API,用于处理时间

1use Illuminate\Support\Sleep;
2 
3$waiting = true;
4 
5while ($waiting) {
6 Sleep::for(1)->second();
7 
8 $waiting = /* ... */;
9}

Sleep 类提供了多种方法,使您可以处理不同的时间单位

1// Return a value after sleeping...
2$result = Sleep::for(1)->second()->then(fn () => 1 + 1);
3 
4// Sleep while a given value is true...
5Sleep::for(1)->second()->while(fn () => shouldKeepSleeping());
6 
7// Pause execution for 90 seconds...
8Sleep::for(1.5)->minutes();
9 
10// Pause execution for 2 seconds...
11Sleep::for(2)->seconds();
12 
13// Pause execution for 500 milliseconds...
14Sleep::for(500)->milliseconds();
15 
16// Pause execution for 5,000 microseconds...
17Sleep::for(5000)->microseconds();
18 
19// Pause execution until a given time...
20Sleep::until(now()->addMinute());
21 
22// Alias of PHP's native "sleep" function...
23Sleep::sleep(2);
24 
25// Alias of PHP's native "usleep" function...
26Sleep::usleep(5000);

要轻松组合时间单位,您可以使用 and 方法

1Sleep::for(1)->second()->and(10)->milliseconds();

测试 Sleep

在测试使用 Sleep 类或 PHP 原生 sleep 函数的代码时,您的测试将暂停执行。正如您可能预期的那样,这会使您的测试套件明显变慢。例如,假设您正在测试以下代码

1$waiting = /* ... */;
2 
3$seconds = 1;
4 
5while ($waiting) {
6 Sleep::for($seconds++)->seconds();
7 
8 $waiting = /* ... */;
9}

通常,测试此代码将至少花费一秒钟。幸运的是,Sleep 类允许我们“伪造”睡眠,以便我们的测试套件保持快速

1it('waits until ready', function () {
2 Sleep::fake();
3 
4 // ...
5});
1public function test_it_waits_until_ready()
2{
3 Sleep::fake();
4 
5 // ...
6}

当伪造 Sleep 类时,实际的执行暂停将被绕过,从而导致更快的测试。

一旦 Sleep 类被伪造,就可以针对应该发生的预期“睡眠”进行断言。为了说明这一点,让我们假设我们正在测试的代码暂停执行三次,每次暂停增加一秒钟。使用 assertSequence 方法,我们可以断言我们的代码“睡眠”了适当的时间量,同时保持我们的测试快速

1it('checks if ready three times', function () {
2 Sleep::fake();
3 
4 // ...
5 
6 Sleep::assertSequence([
7 Sleep::for(1)->second(),
8 Sleep::for(2)->seconds(),
9 Sleep::for(3)->seconds(),
10 ]);
11}
1public function test_it_checks_if_ready_three_times()
2{
3 Sleep::fake();
4 
5 // ...
6 
7 Sleep::assertSequence([
8 Sleep::for(1)->second(),
9 Sleep::for(2)->seconds(),
10 Sleep::for(3)->seconds(),
11 ]);
12}

当然,Sleep 类提供了您在测试时可能使用的各种其他断言

1use Carbon\CarbonInterval as Duration;
2use Illuminate\Support\Sleep;
3 
4// Assert that sleep was called 3 times...
5Sleep::assertSleptTimes(3);
6 
7// Assert against the duration of sleep...
8Sleep::assertSlept(function (Duration $duration): bool {
9 return /* ... */;
10}, times: 1);
11 
12// Assert that the Sleep class was never invoked...
13Sleep::assertNeverSlept();
14 
15// Assert that, even if Sleep was called, no execution paused occurred...
16Sleep::assertInsomniac();

有时,在应用程序代码中发生伪造睡眠时执行操作可能很有用。为了实现这一点,您可以向 whenFakingSleep 方法提供回调。在以下示例中,我们使用 Laravel 的 时间操作助手 来立即将时间推进每次睡眠的持续时间

1use Carbon\CarbonInterval as Duration;
2 
3$this->freezeTime();
4 
5Sleep::fake();
6 
7Sleep::whenFakingSleep(function (Duration $duration) {
8 // Progress time when faking sleep...
9 $this->travel($duration->totalMilliseconds)->milliseconds();
10});

由于推进时间是一个常见的需求,因此 fake 方法接受 syncWithCarbon 参数,以便在测试中睡眠时使 Carbon 保持同步

1Sleep::fake(syncWithCarbon: true);
2 
3$start = now();
4 
5Sleep::for(1)->second();
6 
7$start->diffForHumans(); // 1 second ago

Laravel 在内部使用 Sleep 类来暂停执行。例如,retry 助手在睡眠时使用 Sleep 类,从而在使用该助手时提高可测试性。

超时

Laravel 的 Timebox 类确保给定的回调始终花费固定的执行时间,即使其实际执行完成得更快。这对于加密操作和用户身份验证检查特别有用,在这些情况下,攻击者可能会利用执行时间的变化来推断敏感信息。

如果执行时间超过固定持续时间,Timebox 不会产生任何影响。开发人员需要选择足够长的时间作为固定持续时间,以考虑最坏情况。

call 方法接受闭包和以微秒为单位的时间限制,然后执行闭包并等待直到达到时间限制

1use Illuminate\Support\Timebox;
2 
3(new Timebox)->call(function ($timebox) {
4 // ...
5}, microseconds: 10000);

如果在闭包内抛出异常,此类将遵守定义的延迟,并在延迟后重新抛出异常。

Laravel 是最有效率的方式来
构建、部署和监控软件。