輔助函數 · Laravel 5.4 完全開發手冊

* * * * * [TOC] ## 簡介 Laravel 包含有各種各樣的 PHP 輔助函數，許多都是在 Laravel 自身框架中使用到。如果你覺得實用，也可以在你自己的應用中使用它們。 ## 可用方法 ### 數組 [array_add](#array_add_108) [array_collapse](#array_collapse_118) [array_divide](#array_divide_128) [array_dot](#array_dot_140) [array_except](#array_except_150) [array_first](#array_first_162) [array_flatten](#array_flatten_182) [array_forget](#array_forget_194) [array_get](#array_get_206) [array_has](#array_has_224) [array_last](#array_last_240) [array_only](#array_only_254) [array_pluck](#array_pluck_266) [array_prepend](#array_prepend_289) [array_pull](#array_pull_301) [array_set](#array_set_315) [array_sort](#array_sort_327) [array_sort_recursive](#array_sort_recursive_349) [array_where](#array_where_385) [head](#head_399) [last](#last_411) ### 路徑 [app_path](#app_path_425) [base_path](#base_path_435) [config_path](#config_path_445) [database_path](#database_path_453) [mix](#mix_461) [public_path](#public_path_469) [resource_path](#resource_path_477) [storage_path](#storage_path_487) ### 字符串 [camel_case](#camel_case_499) [class_basename](#class_basename_509) [e](#e_519) [ends_with](#ends_with_529) [snake_case](#snake_case_539) [str_limit](#str_limit_549) [starts_with](#starts_with_559) [str_contains](#str_contains_569) [str_finish](#str_finish_587) [str_is](#str_is_597) [str_plural](#str_plural_611) [str_random](#str_random_637) [str_singular](#str_singular_645) [str_slug](#str_slug_655) [studly_case](#studly_case_665) [title_case](#title_case_675) [trans](#trans_685) [trans_choice](#trans_choice_693) ### URLs [action](#action_703) [asset](#asset_717) [secure_asset](#secure_asset_725) [route](#route_733) [secure_url](#secure_url_747) [url](#url_757) ### 其他 [abort](#abort_777) [abort_if](#abort_if_791) [abort_unless](#abort_unless_799) [auth](#auth_807) [back](#back_815) [bcrypt](#bcrypt_823) [cache](#cache_831) [collect](#collect_849) [config](#config_857) [csrf_field](#csrf_field_873) [csrf_token](#csrf_token_881) [dd](#dd_889) [dispatch](#dispatch_905) [env](#env_913) [event](#event_924) [factory](#factory_932) [info](#info_940) [logger](#logger_954) [method_field](#method_field_974) [old](#old_984) [redirect](#redirect_994) [request](#request_1004) [response](#response_1014) [retry](#retry_1024) [session](#session_1034) [value](#value_1056) [view](#view_1064) ## 方法列表 ## 數組 #### `array_add()` 如果給定的鍵不存在與數組中，`array_add`?就會把給定的鍵值對添加到數組中： ~~~ $array = array_add(['name' => 'Desk'], 'price', 100); // ['name' => 'Desk', 'price' => 100] ~~~ #### `array_collapse()` `array_collapse`?函數把數組里的每一個數組合并成單個數組： ~~~ $array = array_collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]); // [1, 2, 3, 4, 5, 6, 7, 8, 9] ~~~ #### `array_divide()` `array_divide`?函數返回兩個數組，一個包含原本數組的鍵，另一個包含原本數組的值： ~~~ list($keys, $values) = array_divide(['name' => 'Desk']); // $keys: ['name'] // $values: ['Desk'] ~~~ #### `array_dot()` `array_dot`?函數把多維數組壓制成一維數組，并用「點」式語法表示深度： ~~~ $array = array_dot(['foo' => ['bar' => 'baz']]); // ['foo.bar' => 'baz']; ~~~ #### `array_except()` `array_except`?函數從數組移除指定的鍵值對： ~~~ $array = ['name' => 'Desk', 'price' => 100]; $array = array_except($array, ['price']); // ['name' => 'Desk'] ~~~ #### `array_first()` `array_first`?函數返回數組中第一個通過指定測試的元素： ~~~ $array = [100, 200, 300]; $value = array_first($array, function ($value, $key) { return $value >= 150; }); // 200 ~~~ 可傳遞第三個參數作為默認值。當沒有元素通過測試時，將會返回該默認值： ~~~ $value = array_first($array, $callback, $default); ~~~ #### `array_flatten()` `array_flatten`?函數將多維數組壓制成一維數組： ~~~ $array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']]; $array = array_flatten($array); // ['Joe', 'PHP', 'Ruby']; ~~~ #### `array_forget()` `array_forget`?函數以「點」式語法從深度嵌套的數組中移除指定的鍵值對： ~~~ $array = ['products' => ['desk' => ['price' => 100]]]; array_forget($array, 'products.desk'); // ['products' => []] ~~~ #### `array_get()` `array_get`?函數使用「點」式語法從深度嵌套的數組中獲取指定的值： ~~~ $array = ['products' => ['desk' => ['price' => 100]]]; $value = array_get($array, 'products.desk'); // ['price' => 100] ~~~ `array_get`?函數同樣也接受默認值，如果指定的鍵找不到時，則返回該默認值： ~~~ $value = array_get($array, 'names.john', 'default'); ~~~ #### `array_has()` `array_has`?函數使用「點」式語法檢查指定的項目是否存在于數組中： ~~~ $array = ['product' => ['name' => 'desk', 'price' => 100]]; $hasItem = array_has($array, 'product.name'); // true $hasItems = array_has($array, ['product.price', 'product.discount']); // false ~~~ #### `array_last()` `array_last`?函數返回數組中最后一個通過指定測試的元素： ~~~ $array = [100, 200, 300, 110]; $value = array_last($array, function ($value, $key) { return $value >= 150; }); // 300 ~~~ #### `array_only()` `array_only`?函數從數組返回指定的鍵值對： ~~~ $array = ['name' => 'Desk', 'price' => 100, 'orders' => 10]; $array = array_only($array, ['name', 'price']); // ['name' => 'Desk', 'price' => 100] ~~~ #### `array_pluck()` `array_pluck`?函數從數組拉出一列指定的鍵值對： ~~~ $array = [ ['developer' => ['id' => 1, 'name' => 'Taylor']], ['developer' => ['id' => 2, 'name' => 'Abigail']], ]; $array = array_pluck($array, 'developer.name'); // ['Taylor', 'Abigail']; ~~~ 你也可以指定要以什么作為結果列的鍵名： ~~~ $array = array_pluck($array, 'developer.name', 'developer.id'); // [1 => 'Taylor', 2 => 'Abigail']; ~~~ #### `array_prepend()` `array_prepend`?函數將元素加到數組的頭部： ~~~ $array = ['one', 'two', 'three', 'four']; $array = array_prepend($array, 'zero'); // $array: ['zero', 'one', 'two', 'three', 'four'] ~~~ #### `array_pull()` `array_pull`?函數從數組移除指定鍵值對并返回該鍵值對： ~~~ $array = ['name' => 'Desk', 'price' => 100]; $name = array_pull($array, 'name'); // $name: Desk // $array: ['price' => 100] ~~~ #### `array_set()` `array_set`?函數使用「點」式語法在深度嵌套的數組中寫入值： ~~~ $array = ['products' => ['desk' => ['price' => 100]]]; array_set($array, 'products.desk.price', 200); // ['products' => ['desk' => ['price' => 200]]] ~~~ #### `array_sort()` `array_sort`?函數根據指定閉包的結果排序數組： ~~~ $array = [ ['name' => 'Desk'], ['name' => 'Chair'], ]; $array = array_values(array_sort($array, function ($value) { return $value['name']; })); /* [ ['name' => 'Chair'], ['name' => 'Desk'], ] */ ~~~ #### `array_sort_recursive()` `array_sort_recursive`?函數使用 sort 函數遞歸排序數組： ~~~ $array = [ [ 'Roman', 'Taylor', 'Li', ], [ 'PHP', 'Ruby', 'JavaScript', ], ]; $array = array_sort_recursive($array); /* [ [ 'Li', 'Roman', 'Taylor', ], [ 'JavaScript', 'PHP', 'Ruby', ] ]; */ ~~~ #### `array_where()` `array_where`?函數使用指定的閉包過濾數組： ~~~ $array = [100, '200', 300, '400', 500]; $array = array_where($array, function ($value, $key) { return is_string($value); }); // [1 => 200, 3 => 400] ~~~ #### `head()` `head`?函數返回指定數組的第一個元素： ~~~ $array = [100, 200, 300]; $first = head($array); // 100 ~~~ #### `last()` `last`?函數返回指定數組的最后一個元素： ~~~ $array = [100, 200, 300]; $last = last($array); // 300 ~~~ ## 路徑 #### `app_path()` `app_path`?函數返回?`app`?文件夾的完整路徑。你也可以使用?`app_path`?函數生成針對指定文件相對于 app 目錄的完整路徑： ~~~ $path = app_path(); $path = app_path('Http/Controllers/Controller.php'); ~~~ #### `base_path()` `base_path`?函數返回項目根目錄的完整路徑。你也可以使用?`base_path`?函數生成針對指定文件相對于項目根目錄的完整路徑： ~~~ $path = base_path(); $path = base_path('vendor/bin'); ~~~ #### `config_path()` `config_path`?函數返回?`config`?目錄的完整路徑： ~~~ $path = config_path(); ~~~ #### `database_path()` `database_path`?函數返回?`database`?目錄的完整路徑： ~~~ $path = database_path(); ~~~ #### `mix()` `mix`?函數獲取帶有版本號的?[mix](https://laravel-china.org/docs/laravel/5.4/mix)?文件: ~~~ mix($file); ~~~ #### `public_path()` `public_path`?函數返回?`public`?目錄的完整路徑： ~~~ $path = public_path(); ~~~ #### `resource_path()` `resource_path`?函數返回?`resources`?目錄的完整路徑。你也可以使用?`resource_path`?函數生成針對指定文件相對于?`resources`?目錄的完整路徑： ~~~ $path = resource_path(); $path = resource_path('assets/sass/app.scss'); ~~~ #### `storage_path()` `storage_path`?函數返回?`storage`?目錄的完整路徑。你也可以使用?`storage_path`?函數生成針對指定文件相對于?`storage`?目錄的完整路徑： ~~~ $path = storage_path(); $path = storage_path('app/file.txt'); ~~~ ## 字符串 #### `camel_case()` `camel_case`?函數將指定的字符串轉換成?`駝峰式命名`： ~~~ $camel = camel_case('foo_bar'); // fooBar ~~~ #### `class_basename()` `class_basename`?函數返回不包含命名空間的類名稱： ~~~ $class = class_basename('Foo\Bar\Baz'); // Baz ~~~ #### `e()` `e`?函數對指定字符串進行?`htmlentities`： ~~~ echo e('<html>foo</html>'); // <html>foo</html> ~~~ #### `ends_with()` `ends_with`?函數判斷指定字符串結尾是否為指定內容： ~~~ $value = ends_with('This is my name', 'name'); // true ~~~ #### `snake_case()` `snake_case`?函數將指定的字符串轉換成?`蛇形命名`?： ~~~ $snake = snake_case('fooBar'); // foo_bar ~~~ #### `str_limit()` `str_limit`?函數限制字符串的字符個數，該函數接受一個字符串作為第一個參數，第二個參數為允許的最大字符個數： ~~~ $value = str_limit('The PHP framework for web artisans.', 7); // The PHP... ~~~ #### `starts_with()` `starts_with`?函數判斷字符串開頭是否為指定內容： ~~~ $value = starts_with('This is my name', 'This'); // true ~~~ #### `str_contains()` `str_contains`?函數判斷字符串是否包含有指定內容： ~~~ $value = str_contains('This is my name', 'my'); // true ~~~ 你也可以傳遞數組，來判斷字符串是否包任意指定內容: ~~~ $value = str_contains('This is my name', ['my', 'foo']); // true ~~~ #### `str_finish()` `str_finish`?函數添加指定內容到字符串末尾： ~~~ $string = str_finish('this/string', '/'); // this/string/ ~~~ #### `str_is()` `str_is`?函數判斷指定的字符串是否匹配指定的格式，星號可作為通配符使用： ~~~ $value = str_is('foo*', 'foobar'); // true $value = str_is('baz*', 'foobar'); // false ~~~ #### `str_plural()` `str_plural`?函數把字符串轉換成復數形式。該函數目前只支持英文： ~~~ $plural = str_plural('car'); // cars $plural = str_plural('child'); // children ~~~ 你可以傳入一個整數作為第二個參數，來獲取字符串的單數或復數形式： ~~~ $plural = str_plural('child', 2); // children $plural = str_plural('child', 1); // child ~~~ #### `str_random()` `str_random`?函數生成指定長度的隨機字符串。該函數使用了 PHP 自帶的?`random_bytes`?函數： ~~~ $string = str_random(40); ~~~ #### `str_singular()` `str_singular`?函數把字符串轉換成單數形式。該函數目前只支持英文： ~~~ $singular = str_singular('cars'); // car ~~~ #### `str_slug()` `str_slug`?函數根據指定字符串生成 URL 友好的「slug」： ~~~ $title = str_slug('Laravel 5 Framework', '-'); // laravel-5-framework ~~~ #### `studly_case()` `studly_case`?函數把指定字符串轉換成?`首字母大寫`： ~~~ $value = studly_case('foo_bar'); // FooBar ~~~ #### `title_case()` `title_case`?函數把指定字符串轉換成?`每個單詞首字母大寫`： ~~~ $title = title_case('a nice title uses the correct case'); // A Nice Title Uses The Correct Case ~~~ #### `trans()` `trans`?函數根據你的?[本地化文件](https://laravel-china.org/docs/laravel/5.4/localization)?翻譯指定的語句： ~~~ echo trans('validation.required'): ~~~ #### `trans_choice()` `trans_choice`?函數根據給定數量來決定翻譯指定語句是復數形式還是單數形式： ~~~ $value = trans_choice('foo.bar', $count); ~~~ ## URLs #### `action()` `action`?函數根據指定控制器的方法生成 URL，你不需要傳入該控制器的完整命名空間。只需要傳入相對于?`App\Http\Controllers`?命名空間的控制器類名： ~~~ $url = action('HomeController@getIndex'); ~~~ 如果該方法接受路由參數，可以作為第二個參數傳入： ~~~ $url = action('UserController@profile', ['id' => 1]); ~~~ #### `asset()` 根據當前請求的協議（HTTP 或 HTTPS）生成資源文件的 URL： ~~~ $url = asset('img/photo.jpg'); ~~~ #### `secure_asset()` 使用 HTTPS 協議生成資源文件的 URL： ~~~ echo secure_asset('foo/bar.zip', $title, $attributes = []); ~~~ #### `route()` `route`?函數生成指定路由名稱的 URL： ~~~ $url = route('routeName'); ~~~ 如果該路由接受參數，可以作為第二個參數傳入： ~~~ $url = route('routeName', ['id' => 1]); ~~~ #### `secure_url()` `secure_url`?數使用 HTTPS 協議生成指定路徑的完整 URL： ~~~ echo secure_url('user/profile'); echo secure_url('user/profile', [1]); ~~~ #### `url()` `url`?函數生成指定路徑的完整 URL： ~~~ echo url('user/profile'); echo url('user/profile', [1]); ~~~ 如果沒有提供路徑參數，將會返回一個?`Illuminate\Routing\UrlGenerator`?實例： ~~~ echo url()->current(); echo url()->full(); echo url()->previous(); ~~~ ## 其他 #### `abort()` `abort`?函數拋出一個將被異常處理句柄渲染的 HTTP 異常： ~~~ abort(401); ~~~ 你也可以傳入異常的響應消息： ~~~ abort(401, 'Unauthorized.'); ~~~ #### `abort_if()` `abort_if`?函數如果指定的布爾表達式值為?`true`?則拋出一個 HTTP 異常： ~~~ abort_if(! Auth::user()->isAdmin(), 403); ~~~ #### `abort_unless()` `abort_unless`?函數如果指定的布爾表達式值為?`false`?則拋出一個 HTTP 異常： ~~~ abort_unless(Auth::user()->isAdmin(), 403); ~~~ #### `auth()` `auth`?函數返回一個 authenticator 實例，可以使用它來代替 Auth facade： ~~~ $user = auth()->user(); ~~~ #### `back()` `back()`?函數生成一個重定向響應讓用戶返回到之前的位置： ~~~ return back(); ~~~ #### `bcrypt()` `bcrypt`?函數使用 Bcrypt 算法哈希指定的數值。你可以使用它代替?`Hash`?facade： ~~~ $password = bcrypt('my-secret-password'); ~~~ #### `cache()` `cache`?函數嘗試從緩存獲取給定?`key`?的值。如果?`key`?不存在則返回默認值： ~~~ $value = cache('key'); $value = cache('key', 'default'); ~~~ 同時，你也可以傳遞鍵值對來設置緩存，第二個參數可以指定緩存的過期時間，單位分鐘： ~~~ cache(['key' => 'value'], 5); cache(['key' => 'value'], Carbon::now()->addSeconds(10)); ~~~ #### `collect()` `collect`?函數根據指定的數組生成?[集合](https://laravel-china.org/docs/laravel/5.4/collections)?實例： ~~~ $collection = collect(['taylor', 'abigail']); ~~~ #### `config()` `config`?函數用于獲取配置信息的值，配置信息的值可通過「點」式語法訪問，其中包含要訪問的文件名以及選項名。可傳遞一個默認值作為第二參數，當配置信息不存在時，則返回該默認值： ~~~ $value = config('app.timezone'); $value = config('app.timezone', $default); ~~~ `config`?輔助函數也可以在運行期間，根據指定的鍵值對設置指定的配置信息： ~~~ config(['app.debug' => true]); ~~~ #### `csrf_field()` `csrf_field`?函數生成包含 CSRF 令牌內容的 HTML 表單隱藏字段。例如，使用?[Blade 語法](https://laravel-china.org/docs/laravel/5.4/blade)： ~~~ {{ csrf_field() }} ~~~ #### `csrf_token()` `csrf_token`?函數獲取當前 CSRF 令牌的內容： ~~~ $token = csrf_token(); ~~~ #### `dd()` `dd`?函數輸出指定變量的值并終止腳本運行： ~~~ dd($value); dd($value1, $value2, $value3, ...); ~~~ 如果你不想終止腳本運行，使用?`dump`?函數代替： ~~~ dump($value); ~~~ #### `dispatch()` `dispatch`?函數把一個新任務推送到 Laravel 的?[任務隊列](https://laravel-china.org/docs/laravel/5.4/queues)中： ~~~ dispatch(new App\Jobs\SendEmails); ~~~ #### `env()` `env`?函數獲取環境變量值或返回默認值： ~~~ $env = env('APP_ENV'); // Return a default value if the variable doesn't exist... $env = env('APP_ENV', 'production'); ~~~ #### `event()` `event`?函數派發指定的?[事件](https://laravel-china.org/docs/laravel/5.4/events)?到所屬的偵聽器： ~~~ event(new UserRegistered($user)); ~~~ #### `factory()` `factory`?函數根據指定類、名稱以及數量生成模型工廠構造器（model factory builder）。可用于?[測試](https://laravel-china.org/docs/laravel/5.4/database-testing#writing-factories)?或?[數據填充](https://laravel-china.org/docs/laravel/5.4/seeding#using-model-factories)： ~~~ $user = factory(App\User::class)->make(); ~~~ #### `info()` `info`?函數以?`info`?級別寫入日志: ~~~ info('Some helpful information!'); ~~~ 包含上下文數據的數組可以通過第二個參數傳遞給函數： ~~~ info('User login attempt failed.', ['id' => $user->id]); ~~~ #### `logger()` `logger`?函數以?`debug`?級別寫入日志: ~~~ logger('Debug message'); ~~~ 同時支持傳入數組作為參數： ~~~ logger('User has logged in.', ['id' => $user->id]); ~~~ 如果沒有傳入參數，則會返回一個?[日志](https://laravel-china.org/docs/laravel/5.4/errors#logging)?的實例： ~~~ logger()->error('You are not allowed here.'); ~~~ #### `method_field()` `method_field`?函數生成模擬各種 HTTP 動作請求的 HTML 表單隱藏字段。例如，使用?[Blade 語法](https://laravel-china.org/docs/laravel/5.4/blade)： ~~~ <form method="POST"> {{ method_field('DELETE') }} </form> ~~~ #### `old()` `old`?函數?[獲取](https://laravel-china.org/docs/laravel/5.4/requests#retrieving-input)?session 內一次性的歷史輸入值： ~~~ $value = old('value'); $value = old('value', 'default'); ~~~ #### `redirect()` `redirect`?函數返回一個 HTTP 重定向響應，如果調用時沒有傳入參數則返回 redirector 實例： ~~~ return redirect('/home'); return redirect()->route('route.name'); ~~~ #### `request()` `request`?函數返回當前?[請求](https://laravel-china.org/docs/laravel/5.4/requests)?實例或獲取輸入的項目： ~~~ $request = request(); $value = request('key', $default = null) ~~~ #### `response()` `response`?函數創建一個?[響應](https://laravel-china.org/docs/laravel/5.4/responses)?實例或獲取一個 response 工廠實例： ~~~ return response('Hello World', 200, $headers); return response()->json(['foo' => 'bar'], 200, $headers); ~~~ #### `retry()` `retry`?函數將會重復調用給定的回調函數，最多調用指定的次數。如果回調函數沒有拋出異常并且有值返回，則?`retry`?函數返回該值。如果回調函數拋出異常，`retry`?函數將攔截異常并自動再次調用回調函數，直到調用給定的次數。如果重試次數超出給定次數，攔截的異常將會拋出： ~~~ return retry(5, function () { // Attempt 5 times while resting 100ms in between attempts... }, 100); ~~~ #### `session()` `session`?函數可用于獲取或設置單個 session 項： ~~~ $value = session('key'); ~~~ 你可以通過傳遞鍵值對數組給該函數設置 session 項： ~~~ session(['chairs' => 7, 'instruments' => 3]); ~~~ 該函數在沒有傳遞參數時，將返回 session 實例： ~~~ $value = session()->get('key'); session()->put('key', $value); ~~~ #### `value()` `value`?函數返回指定數值。而當你傳遞一個?`閉包`?給該函數時，該?`閉包`?將被運行并返回該?`閉包`?的運行結果： ~~~ $value = value(function() { return 'bar'; }); ~~~ #### `view()` `view`?函數獲取?[視圖](https://laravel-china.org/docs/laravel/5.4/views)?實例： ~~~ return view('auth.login'); ~~~