آموزش توابع کمکی (Helper Functions) در لاراول

توابع کمکی (Helper Functions)

1. مقدمه
2. شرح توابع کمکی

مقدمه

Laravel تعداد زیادی از توابع کمکی زبان PHP را پیش فرض شامل می شود. اگرچه بسیاری از این توابع توسط خود Framework مورد استفاده قرار می گیرند، با این حال شما نیز می توانید در صورت لزوم از آن ها در برنامه های کاربردی خود استفاده نمایید.

شرح توابع کمکی

توابع کمکی که با آرایه کار می کنند

متد array_add()

تابع array add جفت کلید / مقدار ارسالی را به شرطی که کلید مورد نظر از قبل در آرایه موجود نباشد، به داخل آن اضافه می کند (به آرایه الحاق می کند):

$array = array_add(['name' => 'Desk'], 'price', 100);
// ['name' =>'Desk', 'price' =>100]

متد 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()

این تابع دو آرایه در خروجی برمی گرداند که یکی حاوی فقط کلیدها و دیگری آرایه ای دربردارنده ی مقادیری از آرایه ی اصلی می باشد (آرایه را به دو بخش تقسیم کرده و کلیدها / مقادیر را هر یک در آرایه ی برمی گرداند):

list($keys, $values) = array_divide(['name' => 'Desk']);
// $keys: ['name']
// $values: ['Desk']

متد 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 = [100, 200, 300];
$value = array_first($array, function ($key, $value) {
   return $value >= 150;
});
// 200

همچنین می توان یک مقدار پیش فرض به عنوان آرگومان سوم به این تابع ارسال کرد. در صورتی که هیچ یک از مقادیر آرایه با شرط تعیین شده منطبق نباشد، آنگاه مقدار پیش فرض برگردانده می شود:

$value = array_first($array, $callback, $default);
$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()

با بهره گیری از عملگر نقطه بررسی می کند آیا آیتم مورد نظر در آرایه وجود دارد یا خیر. در صورت وجود آیتم، مقدار true را برمی گرداند:

$array = ['products' => ['desk' => ['price' => 100]]];
$hasDesk = array_has($array, 'products.desk');
// true

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' =&g
t; '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 = ['products' => ['desk' => ['price' => 100]]];
array_set($array, 'products.desk.price', 200);
// ['products' =>['desk' =>['price' =>200]]]

array_sort()

تابع array_sort() آرایه را بر اساس خروجی تابع Closure مرتب سازی می کند:

$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 به صورت بازگشتی (recursive) مرتب سازی کند:

$array = [
   [
       'Roman',
       'Taylor',
       'Li',
   ],
   [
       'PHP',
       'Ruby',
       'JavaScript',
   ],
];
$array = array_sort_recursive($array);
/*
   [
       [
           'Li',
           'Roman',
           'Taylor',
       ],
       [
           'JavaScript',
           'PHP',
           'Ruby',
       ]
   ];
*/

array_where()

array where آرایه ی مورد نظر را بر اساس تابع Closure که به عنوان آرگومان دوم به آن پاس داده می شود، فیلتر می کند:

$array = [100, '200', 300, '400', 500];
$array = array_where($array, function ($key, $value) {
   return is_string($value);
});
// [1 =>200, 3 =>400]

متد head()

این تابع تنها اولین المان موجود در آرایه را به عنوان خروجی برمی گرداند:

$array = [100, 200, 300];
$first = head($array);
// 100

متد last()

تابع last آخرین المان در آرایه را به عنوان خروجی برمی گرداند:

$array = [100, 200, 300];
$last = last($array);
// 300

توابعی کار با path ها

تابع app_path()

این متد مسیر کامل به دایرکتوری app را در خروجی برمی گرداند:

                    $path = app_path();

شما همچنین می توانید با استفاده از app_path یک مسیر کامل برای فایل مورد نظر نسبت به دایرکتوری اپلیکیشن ایجاد کنید:

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

base_path()

این تابع مسیر کامل root پروژه (مکانی که پروژه در آن نصب شده) را به عنوان خروجی برمی گرداند:

                    $path = base_path();

می توانید با استفاده از تابع base path یک مسیر کامل برای فایل مورد نظر نسبت به دایرکتوری اپلیکیشن ایجاد نمایید:

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

تابع config_path()

تابع config_path مسیر کامل به دایرکتوری config (تنظیمات) اپلیکیشن را در خروجی برمی گرداند:

                    $path = config_path();

database_path()

تابع database path مسیر کامل به دایرکتوری database اپلیکیشن را برمی گرداند:

                    $path = database_path();

تابع elixir()

مسیر فایل Elixir ورژن سازی شده را به عنوان خروجی برمی گرداند:

                    elixir($file);

تابع public_path()

تابع public_path() مسیر کامل به دایرکتوری public را برمی گرداند:

                    $path = public_path();

storage_path()

مسیر کامل به دایرکتوری storage را در خروجی برمی گرداند:

                    $path = storage_path();

همچنین می توانید تابع storage_path را به منظور تولید یک مسیر کامل به فایل مورد نظر نسبت به دایرکتوری storage بکار ببرید:

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

توابع کار با رشته ها

متد camel_case()

این تابع کاراکترهای رشته ی مورد نظر را با فرمت camelcase نمایش می دهد:

$camel = camel_case('foo_bar');
// fooBar

تابع class_basename()

اسم کلاس را بدون namespace آن برمی گرداند:

$class = class_basename('Foo\Bar\Baz');
// Baz

e()

htmlentities را بر روی رشته ی مورد نظر اجرا می کند (htmlentities تمامی کاراکترها را به موجودیت های html تبدیل می کند. این تابع را به منظور وارد شدن داده به صورت امن بکار می برند):

                    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

تعداد کاراکترهای موجود در یک رشته را محدود می سازد. این تابع یک رشته به عنوان آرگومان اول و حداکثر تعداد کاراکترهایی که بایستی در رشته ی خروجی لحاظ شود را به عنوان آرگومان دوم دریافت می کند:

$value = str_limit('The PHP framework for web artisans.', 7);
// The PHP...

تابع starts_with()

این تابع بررسی می کند آیا رشته ی ارسالی به عنوان آرگومان اول با مقدار مشخص شده (به عنوان آرگومان دوم) آغاز می شود یا خیر:

$value = starts_with('This is my name', 'This');
// true

تابع str_contains()

این تابع بررسی می کند آیا رشته ی مورد نظر مقدار ارسالی به عنوان آرگومان دوم را در داخل خود دارد یا خیر:

$value = str_contains('This is my name', 'my');
// true

str_finish()

این تابع یک نمونه از مقدار معینی را یکبار به انتهای رشته ضمیمه می کند:

$string = str_finish('this/string', '/');
// this/string/

str_is()

این تابع بررسی می کند آیا رشته ی ارائه شده با الگوی خاصی همخوانی و تطابق دارد یا خیر. می توان * را به عنوان پارامتر wildcard به نشانه ی "هر" به تابع ارسال کرد:

$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() یک رشته ی تصادفی با طول معین به عنوان خروجی تولید می کند:

                    $string = str_random(40);

str_singular()

این تابع یک رشته را به فرم مفرد آن تبدیل می کند. در حال حاضر تنها برای زبان انگلیسی قابل استفاده می باشد:

$singular = str_singular('cars');
// car

str_slug()

این تابع یک از رشته ی ارسالی به عنوان پارامتر ورودی یک slug خوانا و بهینه برای URL ایجاد می کند:

$title = str_slug('Laravel 5 Framework', '-');
// laravel-5-framework

studly case()

این تابع یک رشته ی متنی را به فرمت StudlyCase تبدیل می کند (حروف اول هر کلمه را بزرگ می کند):

$value = studly_case('foo_bar');
// FooBar

trans()

این تابع یک متن را با توجه به زبان کشور و محلی شما (بر اساس قابلیت محلی سازی localization) ترجمه می کند:

                    echo trans('validation.required'):

تابع trans_choice()

این تابع متن ورودی به زبان معین را با در نظر گرفتن تعداد کلمات تعیین شده ترجمه می کند:

                    $value = trans_choice('foo.bar', $count);

توابع کار با URL ها

action()

این تابع یک URL برای action کنترلر مورد نظر ایجاد می کند. لازم نیست namespace کنترلر را به طور کامل پاس دهید، بلکه کافی است اسم کلاس را نسبت به فضای نام App\Http\Controllers به عنوان پارامتر به action ارسال نمایید:

                    $url = action('HomeController@getIndex');

در صورتی که متد مورد نظر پارامتر route نیز دریافت می کند، می توانید آن را به عنوان آرگومان دوم به متد پاس دهید:

                    $url = action('HomeController@getIndex');

asset()

با استفاده از درخواست جاری (HTTP یا HTTPS) یک URL برای asset (منابعی همچون عکس ها) ایجاد می کند:

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

متد secure_asset()

یک URL به وسیله ی HTTPS برای asset (منابع) مورد نظر ایجاد می کند:

                    echo secure_asset('foo/bar.zip', $title, $attributes = []);

route()

تابع route یک URL برای route مشخص شده ایجاد می کند:

                    $url = route('routeName');

در صورتی که route پارامتر می پذیرد، می توانید آن را به عنوان آرگومان دوم ارسال کنید:

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

تابع url()

یک URL کامل برای مسیر مشخص شده ایجاد می کند:

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

در صورتی که هیچ مسیری به عنوان آرگومان ارائه نشد، یک نمونه ازIlluminate\Routing\UrlGenerator را به عنوان خروجی بر می گرداند:

echo url()->current();
echo url()->full();
echo url()->previous();

توابع متفرقه

متد auth()

تابع auth() یک نمونه از authenticator را به عنوان خروجی برمی گرداند. می توانید این متد را جایگزین Auth facade نمایید:

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

متد back()

این تابع یک پاسخ redirect به مکان قبلی کاربر ایجاد می کند (کاربر را به صفحه ی قبلی ارجاع می دهد):

                    return back();

متد bcrypt()

تابع bcrypt مقدار ارائه شده را به روش Bcrypt رمزنگاری (hash) می کند. می توان این تابع کمکی را بجای Hash facade استفاده نمود:

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

تابع collect()

تابع collect یک نمونه از کلاس collection از آیتم های پاس داده شده در قالب آرایه (به این متد) ایجاد می کند:

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

config()

این تابع مقدار یک متغیر configuration را بازیابی می کند. می توان با استفاده از عملگر نقطه به مقادیر configuration دسترسی داشت. برای این منظور اسم فایل، سپس عملگر نقطه و به دنبال آن آپشنی که مایلید به آن دسترسی داشته باشید را تایپ کنید. در صورتی که آپشن configurationمورد نظر وجود نداشته باشد، می توان یک مقدار پیش فرض را به عنوان آرگومان دوم تعیین کرده و به عنوان خروجی برگرداند:

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

تابع کمکی config را همچنین می توان برای مقداردهی متغیرهای config در زمان اجرا (runtime) با ارسال آرایه ای از جفت های کلید / مقدار، بکار برد:

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

تابع crsf_field()

این تابع یک فیلد ورودی HTML از نوع hidden حاوی مقدار توکن CSRF ایجاد می کند. برای مثال با دستور نگارشی و سینتکس Blade:

                    {{ csrf_field() }}

csrf_token()

این تابع مقدار توکن CSRF جاری را برمی گرداند:

                    $token = csrf_token();

تابع dd()

این تابع متغیر ارسالی به عنوان آرگومان را dump کرده (اطلاعات همچون نوع داده ای و مقدار متغیر را چاپ کرده) و اجرای اسکریپت را پایان می دهد:

                    dd($value);

اگر نمی خواهید اجرای اسکریپت متوقف شود، می توانید بجای متد ذکر شده تابع dump را صدا بزنید:

                    dump($value);

تابع dispatch()

یک job (عملیات) جدید را به صف زمان بندی و اجرای عملیات (queue job) لاراول اضافه می کند:

                    dispatch(new App\Jobs\SendEmails);

v

این تابع مقدار متغیر محیطی (environment variable) را بازیابی کرده و یا در صورت نبود آن، یک مقدار پیش فرض را در خروجی برمی گرداند:

$env = env('APP_ENV');
// Return a default value if the variable doesn't exist...
$env = env('APP_ENV', 'production');

event()

این تابع event مورد نظر را به listener آن ارسال می کند:

                    event(new UserRegistered($user));

factory()

این متد یک model factory builder برای کلاس، اسم و مقدار مورد نظر ایجاد می کند (model factory امکانی است که به شما اجازه ی ساخت مدل های ساختگی را می دهد). متد نام برده بیشتر در زمان تست و مشخص کردن نقطه ی شروع و مقداردهی اولیه (seeding) کاربر دارد (factoryاساسا یک شی است که توسط آن اشیا از انواع مختلف ایجاد می شود):

                    $user = factory(App\User::class)->make();

متد method field()

تابع ذکر شده یک فیلد ورودی HTML از نوع hidden حاوی مقدار جعل شده متد درخواست HTTP فرم ایجاد می کند. نمونه با استفاده از سینتکسBlade:

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

old()

مقدار ورودی قبلی که در session ذخیره شده بود را بازیابی می کند:

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

متد redirect()

یک نمونه از redirector را برای انجام عملیات redirect به عنوان خروجی برمی گرداند:

                    return redirect('/home');

request()

نمونه ی request جاری را برگردانده یا یک آیتم ورودی می گیرد:

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

response()

این تابع یک نمونه response ایجاد کرده یا یک نمونه از response factory دریافت می کند:

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

session()

تابع session جهت بازیابی یک مقدار session یا تنظیم آن بکار می رود:

                    $value = session('key');

می توانید مقادیر را با ارسال آرایه ای از جفت های کلید / مقدار به عنوان آرگومان به تابع تنظیم کنید:

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

در صورتی که هیچ مقداری به تابع ارسال نشود، session store در خروجی بازیابی می شود:

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

تابع value()

صرفا مقداری که به آن داده شده را برمی گرداند. اگر یک تابع Closure به این متد ارسال کنید، اول closure اجرا می شود و سپس نتیجه ی آن به عنوان خروجی تابع اصلی برگردانده می شود:

                    $value = value(function() { return 'bar'; });

view()

این تابع یک نمونه از view را برمی گرداند:

                    return view('auth.login');

تابع with()

مقداری که به آن داده شده را برمی گرداند. این تابع بیشتر در فراخوانی زنجیره ای متدها کاربرد دارد و خارج از آن قابل استفاده نمی باشد:

                    $value = with(new Foo)->work();