Laravel 5.5 辅助函数文档更新内容

骏妞儿今天翻译了一遍 Laravel 5.5 的辅助函数文档，把新增的函数整理一下广而告之 :point_down:

`array_random()`

该函数从数组中返回一个随机值：

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

$random = array_random($array);

// 4 - (随机获取)

你也可以指定要返回的随机数的数量作为第二个可选参数。一旦你指定了第二个参数，即使数量为 1，这个函数也会返回一个数组：

$items = array_random($array, 2);

// [2, 5] - (随机获取)

`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 = ['products' => ['desk' => ['price' => 100]]];

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

// 100

该函数还接受默认值作为第三个参数，如果找不到指定的键，将返回该值：

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

// 0

`__()`

该函数使用你的本地化文件来翻译给定的翻译字符串或翻译键：

echo __('Welcome to our application');

echo __('messages.welcome');

如果指定的翻译字符串或键不存在，则 __ 函数会简单地返回给定的值。所以，按照上面的例子，如果翻译键 messages.welcome 不存在，__ 方法会将其直接返回。

`preg_replace_array()`

该函数使用数组顺序替换字符串中的给定模式：

$string = '活动将在 :start 和 :end 之间进行';

$replaced = preg_replace_array('/:[a-z_]+/', ['8:30', '9:00'], $string);

// 活动将在 8:30 至 9:00 之间进行

`str_before()`

该函数返回字符串中给定值之前的所有内容：

$slice = str_before('This is my name', 'my name');

// 'This is '

`str_replace_array()`

该函数使用数组顺序替换字符串中的给定值：

$string = 'The event will take place between ? and ?';

$replaced = str_replace_array('?', ['8:30', '9:00'], $string);

// The event will take place between 8:30 and 9:00

`str_replace_first()`

该函数替换字符串中给定值的第一个匹配项：

$replaced = str_replace_first('the', 'a', 'the quick brown fox jumps over the lazy dog');

// a quick brown fox jumps over the lazy dog

`str_replace_last()`

该函数替换字符串中最后一次出现的给定值：

$replaced = str_replace_last('the', 'a', 'the quick brown fox jumps over the lazy dog');

// the quick brown fox jumps over a lazy dog

`str_start()`

该函数将给定值的单个实例添加到字符串（如果它尚未以值开始）：

$adjusted = str_start('this/string', '/');

// /this/string

$adjusted = str_start('/this/string/', '/');

// /this/string

`app()`

该函数返回服务容器实例

$container = app();

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

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

`broadcast()`

该函数将广播给定的事件到它的监听器：

broadcast(new UserRegistered($user));

`blank()`

该函数判断给定的值是否为「空」：

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

// true

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

// false

`class_uses_recursive()`

该函数返回一个类使用的所有 traits，包括任何子类使用的 traits：

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

`cookie()`

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

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

`decrypt()`

该函数使用 Laravel 的 encryption 来解密给定的值：

$decrypted = decrypt($encrypted_value);

`dispatch_now()`

该函数立即运行给定的任务，并从其 handle 方法返回值：

$result = dispatch_now(new App\Jobs\SendEmails);

`dump()`

该函数打印给定的变量：

dump($value);

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

`encrypt()`

该函数使用 Laravel 的 encryption 对给定的值进行加密：

$encrypted = encrypt($unencrypted_value);

`filled()`

该函数判断给定的值是否不为「空」：

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

// true

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

// false

`now()`

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

$now = now();

`optional()`

该函数可以接受任何参数，并且允许你访问该对象的属性或者调用方法。如果给定的对象是 null ，那么属性和方法会简单地返回 null 而不是产生一个错误：

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

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

`policy()`

该方法为给定的类获取一个策略实例：

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

`report()`

该函数将使用异常处理程序的 report 方法抛出异常：

report($e);

`rescue()`

该函数执行给定的闭包并捕获执行期间发生的任何异常。所有被捕获的异常将被发送到你的异常处理程序的 report 方法。要注意的是，该请求将继续处理：

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

你也可以将第二个参数传递给 rescue 方法。如果在执行闭包时发生异常，这个参数将是应该返回的默认值：

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

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

`resolve()`

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

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

`tap()`

该函数接受两个参数：一个任意的 $value 和一个闭包。$value 将被传递给闭包，然后由 tap 函数返回。不需要在闭包中使用 return 返回值。

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

    $user->save();
});

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

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

`today()`

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

$today = today();

`throw_if()`

如果给定的布尔表达式计算结果为 true，throw_if 函数抛出给定的异常：

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

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

`throw_unless()`

如果给定的布尔表达式计算结果为 false，则 throw_unless函数会抛出给定的异常：

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

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

`trait_uses_recursive()`

该函数返回一个类使用的所有 trait：

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

`transform()`

如果给定的值不为空，那么 transform 函数对给定的值执行闭包并返回其结果：

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

$result = transform(5, $callback);

// 10

默认值或闭包也可以作为方法的第三个参数传递。如果给定值为空白，则返回该值：

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

// The value is blank

`validator()`

该函数用给定的参数创建一个新的验证器实例。为方便起见，你可以使用它来代替 Validator facade ：

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

`with()`

该函数会返回给定的值。如果传入一个闭包作为该函数的第二个参数，会返回闭包执行的结果：

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

$result = with(5, $callback);

// 10

$result = with(null, $callback);

// 0

$result = with(5, null);

// 5