laravelphp 中文文档      >

简介

Laravel 包含了多种全局的PHP 助手函数。这些函数许多被框架本身使用；然而，如果你觉得它们方便，你也可以在你自己的应用程序中自由使用它们。

可用方法

数组 & 对象

Arr::accessible
Arr::add
Arr::collapse
Arr::crossJoin
Arr::divide
Arr::dot
Arr::except
Arr::exists
Arr::first
Arr::flatten
Arr::forget
Arr::get
Arr::has
Arr::hasAny
Arr::isAssoc
Arr::isList
Arr::join
Arr::keyBy
Arr::last
Arr::map
Arr::mapSpread
Arr::mapWithKeys
Arr::only
Arr::pluck
Arr::prepend
Arr::prependKeysWith
Arr::pull
Arr::query
Arr::random
Arr::set
Arr::shuffle
Arr::sort
Arr::sortDesc
Arr::sortRecursive
Arr::sortRecursiveDesc
Arr::take
Arr::toCssClasses
Arr::toCssStyles
Arr::undot
Arr::where
Arr::whereNotNull
Arr::wrap
data_fill
data_get
data_set
data_forget
head
last

数字

Number::abbreviate
Number::clamp
Number::currency
Number::fileSize
Number::forHumans
Number::format
Number::ordinal
Number::percentage
Number::spell
Number::useLocale
Number::withLocale

路径

app_path
base_path
config_path
database_path
lang_path
mix
public_path
resource_path
storage_path

URLs

action
asset
route
secure_asset
secure_url
to_route
url

杂项

abort
abort_if
abort_unless
app
auth
back
bcrypt
blank
broadcast
cache
class_uses_recursive
collect
config
context
cookie
csrf_field
csrf_token
decrypt
dd
dispatch
dispatch_sync
dump
encrypt
env
event
fake
filled
info
literal
logger
method_field
now
old
once
optional
policy
redirect
report
report_if
report_unless
request
rescue
resolve
response
retry
session
tap
throw_if
throw_unless
today
trait_uses_recursive
transform
validator
value
view
with

数组 & 对象

php Arr::accessible()
php Arr::accessible 方法判断给定值是否可作为数组访问：

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

php Arr::add()
如果给定的键名在数组中不存在键值或该键值设置为 php null ，那么 php Arr::add 方法将会把给定的键值对添加到数组中：

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

php Arr::collapse()
php Arr::collapse 方法将多个数组合并为一个数组：

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

php Arr::crossJoin()
php Arr::crossJoin 方法交叉连接给定的数组，返回具有所有可能排列的笛卡尔乘积：

  1. use Illuminate\Support\Arr;
  3. $matrix = Arr::crossJoin([1, 2], ['a', 'b']);
  5. /*
  6.     [
  7.         [1, 'a'],
  8.         [1, 'b'],
  9.         [2, 'a'],
  10.         [2, 'b'],
  11.     ]
  12. */
  14. $matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);
  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. */

php Arr::divide()
php Arr::divide 方法返回一个二维数组，一个值包含原数组的键，另一个值包含原数组的值：

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

php Arr::dot()
php Arr::dot 方法将多维数组中所有的键平铺到一维数组中，新数组使用「.」符号表示层级包含关系：

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

php Arr::except()
php Arr::except 方法从数组中删除指定的键值对：

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

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

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

php Arr::first()
php Arr::first 方法返回数组中满足指定条件的第一个元素：

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

可将默认值作为第三个参数传递给该方法，如果数组中没有值满足指定条件，则返回该默认值：

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

php Arr::flatten()
php Arr::flatten 方法将多维数组中数组的值取出平铺为一维数组：

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

php Arr::forget()
php Arr::forget 方法使用「.」符号从深度嵌套的数组中删除给定的键值对：

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

php Arr::get()
php Arr::get 方法使用「.」符号从深度嵌套的数组中根据指定键检索值：

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

php Arr::get 方法也可以接受一个默认值，如果数组中不存在指定的键，则返回默认值：

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

php Arr::has()
php Arr::has 方法使用「.」符号判断数组中是否存在指定的一个或多个键：

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

php Arr::hasAny()
php Arr::hasAny 方法使用「.」符号判断给定集合中的任一值是否存在于数组中：

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

php Arr::isAssoc()
如果给定数组是关联数组，则 php Arr::isAssoc 方法返回 php true，如果该数组没有以零开头的顺序数字键，则将其视为「关联」数组：

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

php Arr::isList()
如果给定数组的键是从零开始的连续整数，则 php Arr::isList 方法返回 php true：

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

php Arr::join()
php Arr::join() 方法将给定数组的所有值通过给定字符串连接起来。使用此方法的第二个参数，你还可以为数组中的最后一个元素指定连接的字符串：

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

php Arr::keyBy()
php Arr::keyBy() 方法通过给定键名的值对该数组进行重组。如果数组中存在多个相同的值，则只有最后一个值会出现在新数组中：

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

php Arr::last()
php Arr::last 方法返回数组中满足指定条件的最后一个元素：

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

将默认值作为第三个参数传递给该方法，如果没有值满足条件，则返回该默认值：

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

php Arr::map()
php Arr::map 方法用来遍历数组，并将每个值和键传递给给定的回调。数组值由回调返回的值替换：

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

php Arr::mapSpread()
php Arr::mapSpread 方法遍历数组，将每个嵌套项值传递到给定的闭包。闭包可以自由修改项并返回它，从而形成一个新的修改后的项数组：

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

php Arr::mapWithKeys()
php Arr::mapWithKeys 方法遍历数组并将每个值传递给给定的回调。回调应返回包含单个键值对的关联数组：

  1. use Illuminate\Support\Arr;
  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. ];
  16. $mapped = Arr::mapWithKeys($array, function (array $item, int $key) {
  17.     return [$item['email'] => $item['name']];
  18. });
  20. /*
  21.     [
  22.         '[email protected]' => 'John',
  23.         '[email protected]' => 'Jane',
  24.     ]
  25. */

php Arr::only()
php Arr::only 方法仅从给定数组中返回指定的键值对：

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

php Arr::pluck()
php Arr::pluck 方法从数组中提取给定键的所有值：

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

你也可以指定结果的键:

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

php Arr::prepend()
php Arr::prepend 方法会将一个元素推到数组的开头：

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

你也可以指定插入值的键：

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

php Arr::prependKeysWith()
php Arr::prependKeysWith 方法用给定前缀预置关联数组的所有键名：

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

php Arr::pull()
php Arr::pull 方法返回并移除数组中的一个键值对：

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

也可以将默认值作为方法的第三个参数传递。如果键不存在，将返回这个值：

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

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

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

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

  1. use Illuminate\Support\Arr;
  3. $array = [1, 2, 3, 4, 5];
  5. $random = Arr::random($array);
  7. // 4 - (随机获取)

你也可以指定作为可选第二个参数返回的项数。注意，即使只需要一个项，提供这个参数也将返回一个数组：

  1. use Illuminate\Support\Arr;
  3. $items = Arr::random($array, 2);
  5. // [2, 5] - (随机获取)

php Arr::set()
php Arr::set 方法使用「.」符号在多维数组中设置指定键的值：

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

php Arr::shuffle()
php Arr::shuffle 方法将数组中值进行随机排序：

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

php Arr::sort()
php Arr::sort 方法根据给定数组的值进行升序排序：

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

你还可以根据给定回调方法的返回结果对数组进行排序：

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

php Arr::sortDesc()
php Arr::sortDesc 方法根据给定数组的值进行降序排序：

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

你还可以根据给定回调方法的返回结果对数组进行排序：

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

php Arr::sortRecursive()
php Arr::sortRecursive 方法对给定数组进行递归排序，使用 php sort 方法对数字索引子数组进行按值升序排序，使用 php ksort 方法对关联子数组进行按键升序排序：

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

如果你希望结果降序排序，你可以使用 php Arr::sortRecursiveDesc 方法。

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

php Arr::take()
php Arr::take 方法返回一个新数组，其中包含指定数量的项：

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

你也可以传递一个负整数，以从数组的末尾取出指定数量的项：

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

php Arr::toCssClasses()
php Arr::toCssClasses 方法有条件地编译 CSS 类字符串。该方法接受一个键值数组，其中数组键包含你希望添加的类，而值是一个布尔表达式。如果数组元素有数字键，它将始终包括在渲染的类列表中：

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

php Arr::toCssStyles()
php Arr::toCssStyles 方法有条件地编译 CSS 样式字符串。该方法接受一个键值数组，其中数组键包含你希望添加的类，而值是一个布尔表达式。如果数组元素有数字键，它将始终包括在渲染的类列表中：

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

这个方法实现了 Laravel 的功能，允许与 Blade 组件的属性包合并类以及 php @class Blade 指令。

php Arr::undot()
php Arr::undot 方法使用「.」符号将一维数组扩展为多维数组：

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

php Arr::where()
php Arr::where 方法使用给定的回调函数返回的结果过滤数组：

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

php Arr::whereNotNull()
php Arr::whereNotNull 方法将从给定数组中删除所有 php null 值：

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

php Arr::wrap()
php Arr::wrap 方法可以将给定值转换为一个数组，如果给定的值已经是一个数组，它将原样返回：

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

如果给定值是 php null ，将返回一个空数组：

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

php data_fill()
php data_fill 函数使用「.」符号给多维数组或对象设置缺少的值：

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

也可以接收 「*」 作为通配符，设置相应缺少的值：

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

php data_get()
php data_get 函数使用 「.」 符号从多维数组或对象中根据指定键检索值

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

php data_get 函数也接受一个默认值，如果没有找到指定的键，将返回默认值：

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

该函数还接受「*」作为通配符，来指向数组或对象的任何键：

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

可以使用 php {first} 和 php {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. ];
  8. data_get($flight, 'segments.{first}.arrival');
  10. // 15:00

php data_set()
php data_set 函数使用「.」符号从多维数组或对象中根据指定键设置值：

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

此函数也接受使用「*」作为通配符，并相应地在目标上设置值：

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

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

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

php data_forget()
php data_forget 函数使用「.」符号从嵌套数组或对象中移除值：

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

此函数也接受使用「*」 作为通配符，并相应地在目标上移除值：

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

php head()
php head 函数返回给定数组中的第一个元素：

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

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

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

数字

php Number::abbreviate()
php Number::abbreviate 方法返回所提供数值的人类可读格式，并用缩写表示单位：

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

php Number::clamp()
php Number::clamp 方法确保给定数字保持在指定范围内。如果数字低于最小值，则返回最小值。如果数字高于最大值，则返回最大值：

  1. use Illuminate\Support\Number;
  3. $number = Number::clamp(105, min: 10, max: 100);
  5. // 100
  7. $number = Number::clamp(5, min: 10, max: 100);
  9. // 10
  11. $number = Number::clamp(10, min: 10, max: 100);
  13. // 10
  15. $number = Number::clamp(20, min: 10, max: 100);
  17. // 20

php Number::currency()
php Number::currency 方法将给定值作为字符串返回货币表示：

  1. use Illuminate\Support\Number;
  3. $currency = Number::currency(1000);
  5. // $1,000
  7. $currency = Number::currency(1000, in: 'EUR');
  9. // €1,000
  11. $currency = Number::currency(1000, in: 'EUR', locale: 'de');
  13. // 1.000 €

php Number::fileSize()
php Number::fileSize 方法将给定字节值作为字符串返回文件大小表示：

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

php Number::forHumans()
php Number::forHumans 方法返回所提供数值的人类可读格式：

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

php Number::format()
php Number::format 方法将给定数字格式化为特定区域的字符串：

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

php Number::ordinal()
php Number::ordinal 方法返回数字的序数表示：

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

php Number::percentage()
php Number::percentage 方法将给定值作为字符串返回百分比表示：

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

php Number::spell()
php Number::spell 方法将给定数字转换为字词字符串：

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

php after 参数允许你指定在哪个值之后所有数字都应该拼写出来：

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

php until 参数允许你指定在哪个值之前所有数字都应该拼写出来：

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

php Number::useLocale()
php Number::useLocale 方法全局设置默认数字区域设置，这影响了 php Number 类方法后续调用时数字和货币的格式化方式：

  1. use Illuminate\Support\Number;
  3. /**
  4.  * 启动任何应用服务
  5.  */
  6. public function boot(): void
  7. {
  8.     Number::useLocale('de');
  9. }

php Number::withLocale()
php Number::withLocale 方法在指定区域设置中执行给定闭包，然后在回调执行后恢复原始区域设置：

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

路径

php app_path()
php app_path 函数返回应用程序的 php app 目录的完整路径。你也可以使用 php app_path 函数生成相对于应用程序目录的文件的完整路径：

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

php base_path()
php base_path 函数返回应用程序的根目录的完整路径。你还可以使用 php base_path 函数生成相对于项目根目录的给定文件的完整路径：

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

php config_path()
php config_path 函数返回应用程序的 php config 目录的完整路径。你也可以使用 php config_path 函数生成应用程序配置目录中给定文件的完整路径：

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

php database_path()
php database_path 函数返回应用程序的 php database 目录的完整路径。你还可以使用 php database_path 函数生成数据库目录中给定文件的完整路径：

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

php lang_path()
php lang_path 函数返回应用程序的 php lang 目录的完整路径。你也可以使用 php lang_path 函数生成目录中给定文件的完整路径：

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


注意
默认情况下，Laravel 应用程序骨架不包括 php lang 目录。如果你希望自定义 Laravel 的语言文件，则可以通过 php lang:publish Artisan 命令发布它们。

php mix()
php mix 函数返回到 版本化的 Mix 文件 的路径：

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

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

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

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

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

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

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

URLs

php action()
php action 函数为给定的控制器操作生成 URL：

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

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

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

php asset()
php asset 函数使用请求的当前方案（HTTP 或 HTTPS）生成 URL：

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

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

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

php route()
php route 函数为给定的 命名路由生成 URL：

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

如果路由接受参数，你可以将它们作为函数的第二个参数传递：

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

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

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

php secure_asset()
php secure_asset 函数使用 HTTPS 生成资源的 URL：

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

php secure_url()
php secure_url 函数生成到给定路径的完全限定 HTTPS URL。额外的 URL 段可以作为函数的第二个参数传递：

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

php to_route()
php to_route 函数生成给定 命名路由 的 重定向 HTTP 响应：

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

如果需要，你可以将应该分配给重定向的 HTTP 状态码和任何其他响应头作为 php to_route 方法的第三和第四个参数传递：

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

php url()
php url 函数生成到给定路径的完全限定 URL：

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

如果没有提供路径，将返回一个 php Illuminate\Routing\UrlGenerator 实例：

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

杂项

php abort()
php abort 函数抛出 HTTP 异常，该异常将由 异常处理器渲染：

  1. abort(403);

你也可以提供异常的消息和应该发送到浏览器的自定义 HTTP 响应头：

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

php abort_if()
如果给定的布尔表达式评估为 php true 则 php abort_if 函数抛出 HTTP 异常：

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

和 php abort 方法类似，你也可以将异常的响应文本作为第三个参数提供，并将自定义响应头的数组作为第四个参数传递给函数。

php abort_unless()
如果给定的布尔表达式评估为 php false 则 php abort_unless 函数抛出 HTTP 异常：

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

和 php abort 方法类似，你也可以将异常的响应文本作为第三个参数提供，并将自定义响应头的数组作为第四个参数传递给函数。

php app()
php app 函数返回 服务容器 实例：

  1. $container = app();

你可以传递一个类或接口名称来从容器中解析它：

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

php auth()
php auth 函数返回一个 认证器 实例。你可以使用它来替代 php Auth facade：

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

如果需要，你可以指定你想要访问的哪一个守卫实例：

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

php back()
php back 函数生成 重定向 HTTP 响应 到用户的上一个位置：

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

php bcrypt()
php bcrypt 函数使用 Bcrypt 哈希 给定的值。你可以使用这个函数替代 php Hash facade ：

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

php blank()
php blank 函数确定给定值是否为「空白」：

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

对于 php blank 的反转，请参阅 php filled 方法。

php broadcast()
php broadcast 函数 广播 给定的 事件 到其它监听器：

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

php cache()
php cache 函数可用于从 缓存 中获取值。 如果缓存中不存在给定的键，将返回一个可选的默认值：

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

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

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

php class_uses_recursive()
php class_uses_recursive 函数返回一个类使用的所有特征，包括其所有父类使用的特征：

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

php collect()
php collect 函数根据给定值创建一个 集合 实例：

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

php config()
php config 函数获取 配置 变量的值。 可以使用「.」语法访问配置值，其中包括文件名和你希望访问的选项。 如果配置选项不存在，可以指定默认值并返回：

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

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

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

php context()
php context 函数从 当前上下文 中获取值。默认值可以指定，并且如果上下文键不存在则返回它

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

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

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

php cookie()
php cookie 函数创建一个新的 cookie 实例：

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

php csrf_field()
php csrf_field 函数生成一个 HTML php hidden 输入字段，包含 CSRF 令牌的值。例如，使用 Blade 语法：

  1. {{ csrf_field() }}

php csrf_token()
php csrf_token 函数检索当前 CSRF 令牌的值：

  1. $token = csrf_token();

php decrypt()
php decrypt 函数 解密 给定值。你可以使用这个函数替代 php Crypt facade：

  1. $password = decrypt($value);

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

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

如果你不想在转储变量后中止脚本的执行，请使用 php dump 函数。

php dispatch()
php dispatch 函数将给定的 任务 推送到 Laravel 任务队列：

  1. dispatch(new App\Jobs\SendEmails);

php dispatch_sync()
php dispatch_sync 函数将给定的任务推送到 同步 队列，以便立即处理：

  1. dispatch_sync(new App\Jobs\SendEmails);

php dump()
php dump 函数转储给定变量：

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

如果你想在转储变量后停止执行脚本，请使用 php dd 函数。

php encrypt()
php encrypt 函数 加密 给定值。你可以使用这个函数替代 php Crypt facade ：

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

php env()
php env 函数检索一个 环境变量 的值或返回一个默认值：

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


注意
如果你在部署过程中执行了 php config:cache 命令，请确保你只在配置文件中调用 php env 函数。一旦配置被缓存，php .env 文件不会被加载，并且所有调用 php env 函数的地方都会返回 php null。

php event()
php event 函数将给定的 事件 分发到它的监听器：

  1. event(new UserRegistered($user));

php fake()
php fake 函数从容器中解析一个 Faker 单例，这在创建模型工厂、数据库种子数据、测试以及原型视图中的假数据时非常有用：

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

默认情况下，php fake 函数将使用 php config/app.php 配置中的 php app.faker_locale 配置选项。通常，这个配置项是通过 php APP_FAKER_LOCALE 环境变量设置的。你也可以通过将语言环境传递给 php fake 函数来指定语言环境。每个 语言环境都会解析一个单独的单例

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

php filled()
php filled 函数用于判断给定值是否不是「空白」：

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

对于 php filled 的反转，请参阅 php blank 方法。

php info()
php info 函数将信息写入应用程序的 日志：

  1. info('Some helpful information!');

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

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

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

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

php logger()
php logger 函数可用于向 日志 写入 php debug 级别的信息：

  1. logger('Debug message');

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

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

如果没有传递值给函数，将返回 logger 实例：

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

php method_field()
php method_field 函数生成一个 HTML php hidden 输入字段，其中包含表单 HTTP 动词的伪造值。例如，使用 Blade 语法：

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

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

  1. $now = now();

php old()
php old 函数 检索 被闪存到 session 中的 旧输入值：

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

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

  1. {{ old('name', $user->name) }}
  3. // 等价于...
  5. {{ old('name', $user) }}

php once()
php once 函数执行给定回调并在请求期间将结果缓存在内存中。任何后续使用相同回调的 php once 函数的调用将返回之前缓存的结果：

  1. function random(): int
  2. {
  3.     return once(function () {
  4.         return random_int(1, 1000);
  5.     });
  6. }
  8. random(); // 123
  9. random(); // 123 (缓存的结果)
  10. random(); // 123 (缓存的结果)

当 php once 函数在对象实例内部执行时，缓存结果将唯一于该对象实例：

  1. <?php
  3. class NumberService
  4. {
  5.     public function all(): array
  6.     {
  7.         return once(fn () => [1, 2, 3]);
  8.     }
  9. }
  11. $service = new NumberService;
  13. $service->all();
  14. $service->all(); // (缓存的结果)
  16. $secondService = new NumberService;
  18. $secondService->all();
  19. $secondService->all(); // (缓存的结果)

php optional()
php optional 函数接受任意参数并允许你访问该对象上的属性或调用方法。如果给定的对象是 php null，属性和方法将返回 php null 而非引起错误：

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

php optional 函数还接受闭包作为其第二个参数。如果第一个参数提供的值不是 null，则将调用闭包：

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

php policy()
php policy 方法检索给定类的 policy 实例：

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

php redirect()
php redirect 函数返回 重定向 HTTP 响应，如果没有参数调用它，则返回重定向器实例：

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

php report()
php report 函数将使用你的 异常处理程序 报告异常：

  1. report($e);

php report 函数也接受字符串作为参数。当给函数传递字符串时，该函数将创建一个以给定字符串为消息的异常：

  1. report('Something went wrong.');

php report_if()
如果给定条件为 php true，php report_if 函数将使用你的 异常处理程序 报告异常：

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

php report_unless()
如果给定条件为 php false，php report_unless 函数将使用你的 异常处理程序 报告异常：

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

php request()
php request 函数返回当前 请求 实例或从当前请求获取输入字段的值：

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

php rescue()
php rescue 函数执行给定闭包并捕获执行期间发生的任何异常。所有捕获的异常都将发送到 异常处理程序；但是，请求将继续处理：

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

你可以向 php rescue 函数传递第二个参数。此参数将是在执行闭包时发生异常应返回的「默认」值：

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

可以提供 php report 参数给 php rescue 函数来决定是否通过 php report 函数报告异常：

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

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

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

php response()
php response 函数创建一个 响应 实例或获取响应工厂的实例：

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

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

  1. return retry(5, function () {
  2.     // 尝试 5 次，每次尝试之间休息 100ms...
  3. }, 100);

如果你希望手动计算尝试之间睡眠的毫秒数，你可以将闭包作为第三个参数传递给 php retry 函数：

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

方便起见，你可以将数组作为 php retry 函数的第一个参数提供。该数组将用于确定后续尝试之间的毫秒数：

  1. return retry([100, 200], function () {
  2.     //  第一次重试睡眠 100ms，第二次重试睡眠 200ms...
  3. });

要仅在特定条件下重试，你可以将闭包作为 php retry 函数的第四个参数：

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

php session()
php session 函数可用于获取或设置 session 值：

  1. $value = session('key');

你可以通过向函数传递键 / 值对数组来设置值：

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

如果没有传递值给函数，会话存储将被返回：

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

php tap()
php tap 函数接受两个参数：任意的 php $value 和闭包。php $value 将被传递给闭包，然后由 php tap 函数返回。 闭包的返回值是无关紧要的：

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

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

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

要向类添加 php tap 方法，你可以为类添加 php Illuminate\Support\Traits\Tappable trait。这个 trait 的 php tap 方法接受闭包作为其唯一的参数。对象实例本身将被传递给闭包，然后通过 php tap 方法返回：

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

php throw_if()
如果给定的布尔表达式评估为 php true，则 php throw_if 函数抛出给定的异常：

  1. throw_if(! Auth::user()->isAdmin(), AuthorizationException::class);
  3. throw_if(
  4.     ! Auth::user()->isAdmin(),
  5.     AuthorizationException::class,
  6.     '你不允许访问此页面。'
  7. );

php throw_unless()
如果给定的布尔表达式评估为 php false，则 php throw_unless 函数抛出给定的异常：

  1. throw_unless(Auth::user()->isAdmin(), AuthorizationException::class);
  3. throw_unless(
  4.     Auth::user()->isAdmin(),
  5.     AuthorizationException::class,
  6.     '你不允许访问此页面。'
  7. );

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

  1. $today = today();

php trait_uses_recursive()
php trait_uses_recursive 函数返回特征使用的所有 trait：

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

php transform()
php transform 函数在给定值不是 blank 的情况下对其执行闭包，然后返回闭包的返回值：

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

第三个参数可以传递默认值或闭包给函数。如果给定值是 空，将返回该值：

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

php validator()
php validator 函数使用给定的参数创建一个新的 validator 实例。你可以用它替代 php Validator facade：

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

php value()
php value 函数返回它所接收到的值。但是，如果你传递一个闭包给该函数，闭包将被执行，并且其返回的值将被返回：

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

可以向 php value 函数传递额外的参数。如果第一个参数是闭包，则额外的参数将作为参数传递给闭包，否则它们将被忽略：

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

php view()
php view 函数检索一个 视图 实例：

  1. return view('auth.login');

php with()
with 函数返回它被赋予的值。如果闭包作为该函数的第二个参数传递，则会执行闭包并返回其返回值：

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

其他实用工具

基准测试

有时你可能希望快速测试应用程序的某些部分的性能。在这些场合，你可以使用 php Benchmark 支持类来测量完成给定回调所需的毫秒数：

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

默认情况下，给定的回调将被执行一次（一次迭代），其持续时间将在浏览器 / 控制台中显示。

要多次调用回调，你可以指定回调应该被调用的迭代次数作为方法的第二个参数。当多次执行回调时，php Benchmark 类将返回执行回调所需的平均毫秒数：

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

有时，你可能想要在测试回调的执行时仍然获得回调返回的值。php value 方法将返回一个包含回调返回值和执行回调所花费毫秒数的元组：

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

日期

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

  1. $now = now();

或者，你可以使用 php Illuminate\Support\Carbon 类来创建一个新的 php Carbon 实例：

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

有关 Carbon 及其功能的详尽讨论，请查阅 Carbon 官方文档。

抽奖

Laravel 的 lottery 类可以根据一组给定的赔率执行回调。当你只想为你的传入请求的一部分执行代码时，这特别有用：

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

你可以将 Laravel 的抽奖类与其他 Laravel 功能结合使用。例如，你可能希望只向你的异常处理程序报告慢查询的一小部分。由于抽奖类是可调用的，我们可以将该类的实例传递给任何接受可调用对象的方法：

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

测试抽奖
Laravel 提供了一些简单的方法，让你可以轻松测试应用程序的抽奖调用：

  1. // 抽奖将总是赢...
  2. Lottery::alwaysWin();
  4. // 抽奖将总是输...
  5. Lottery::alwaysLose();
  7. // 抽奖将先赢然后输，最后恢复正常行为...
  8. Lottery::fix([true, false]);
  10. // 抽奖将恢复正常行为...
  11. Lottery::determineResultsNormally();

管道

Laravel 的 php Pipeline facade 提供了一种便捷的方式来通过一系列可调用类、闭包或可调用对象「管道化」给定输入，让每个类都有机会检查或修改输入并调用管道中的下一个可调用对象：

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

如你所见，管道中的每个可调用类或闭包都被赋予输入和一个 php $next 闭包。调用 php $next 闭包将调用管道中的下一个可调用对象。你可能已经注意到，这与 中间件 非常相似。

当管道中的最后一个可调用对象调用 php $next 闭包时，php 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 的 php Sleep 类是围绕 PHP 原生 php sleep 和 php usleep 函数的轻量级封装，提供更高的可测试性，同时也为处理时间提供了一个对开发者友好的 API：

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

php Sleep 类提供了各种方法，允许你使用不同的时间单位：

  1. // 暂停执行 90 秒...
  2. Sleep::for(1.5)->minutes();
  4. // 暂停执行 2 秒...
  5. Sleep::for(2)->seconds();
  7. // 暂停执行 500 毫秒...
  8. Sleep::for(500)->milliseconds();
  10. // 暂停执行 5,000 微秒...
  11. Sleep::for(5000)->microseconds();
  13. // 暂停执行到给定的时间...
  14. Sleep::until(now()->addMinute());
  16. // PHP 原生「sleep」函数的别名...
  17. Sleep::sleep(2);
  19. // PHP 原生「usleep」函数的别名...
  20. Sleep::usleep(5000);

为了方便组合时间单位，你可以使用 php and 方法：

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

测试睡眠
当在测试中利用 php Sleep 类或 PHP 原生的 sleep 函数时，你的测试将暂停执行。可以想象，这会使你的测试套件显著变慢。例如，假设你正在测试以下代码：

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

通常，测试这段代码至少会花费一秒钟。幸运的是，php Sleep 类允许我们「伪造」睡眠，使我们的测试套件保持快速：

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

当伪造了 php Sleep 类时，实际的执行暂停被绕过，导致测试显著加快。

一旦 php Sleep 类被伪造，就可以对在应用程序代码中应该发生的预期「睡眠」进行断言。为了说明这一点，让我们假设我们正在测试的代码会三次暂停执行，每次暂停的时间都会增加一秒。使用 php assertSequence 方法，我们可以断言在保持测试速度的同时代码「睡眠」了适当时间：

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

当然，php Sleep 类提供了许多其他的断言，你可以在测试时使用：

  1. use Carbon\CarbonInterval as Duration;
  2. use Illuminate\Support\Sleep;
  4. // 断言调用 sleep 函数 3 次...
  5. Sleep::assertSleptTimes(3);
  7. // 针对睡眠持续时间的断言...
  8. Sleep::assertSlept(function (Duration $duration): bool {
  9.     return /* ... */;
  10. }, times: 1);
  12. // 断言 Sleep 类从未被调用...
  13. Sleep::assertNeverSlept();
  15. // 断言，即使 Sleep 被调用，也不会发生执行暂停...
  16. Sleep::assertInsomniac();

有时在应用程序代码中伪造睡眠发生时执行某个操作可能会很有用。要做到这一点，你可以提供一个回调给 php whenFakingSleep 方法。在下面的例子中，我们使用 Laravel 的时间操作帮助函数来即时进入每次睡眠的时间：

  1. use Carbon\CarbonInterval as Duration;
  3. $this->freezeTime();
  5. Sleep::fake();
  7. Sleep::whenFakingSleep(function (Duration $duration) {
  8.     // 进行时间进展，当伪造睡眠时...
  9.     $this->travel($duration->totalMilliseconds)->milliseconds();
  10. });

因为进入时间是一个常见需求，php fake 方法接受 php syncWithCarbon 参数，在睡眠测试中保持 Carbon 同步：

  1. Sleep::fake(syncWithCarbon: true);
  3. $start = now();
  5. Sleep::for(1)->second();
  7. $start->diffForHumans(); // 1 秒前

Laravel 在其内部使用 php Sleep 类，每当要暂停执行时。例如，php retry 帮助器使用 php Sleep 类进行睡眠，从而提高在使用该帮助器时的可测试性。