الدوال المساعدة (Helpers) في Laravel

مقدمة

يتضمن Laravel عددًا من دوال PHP المساعدة. تُستعمل العديد من هذه الدوال من قبل Laravel لكن بامكانك استعمالها في تطبيقك اذا احتجتهم.

قائمة التوابع

المصفوفات والكائنات

()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

تعيد الدالة مصفوفتين، واحدة تحتوي المفاتيح وأخرى تحتوي القيم من المصفوفة الممرّرة:

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

// $keys: ['name']

// $values: ['Desk']

()array_dot

تسطّح الدالة مصفوفة متعددة الأبعاد لمصفوفة ببعد واحد تستعمل رمز النقطة لبيان العمق:

$array = ['products' => ['desk' => ['price' => 100]]];

$flattened = array_dot($array);

// ['products.desk.price' => 100]

()array_except

تحذف الدالة الثنائي مفتاح\قيمة الممرّر من المصفوفة:

$array = ['name' => 'Desk', 'price' => 100];

$filtered = array_except($array, ['price']);

// ['name' => 'Desk']

()array_first

تعيد الدالة العنصر الأول من المصفوفة الممرّرة الذي يستجيب لشرط صحّة:

$array = [100, 200, 300];

$first = array_first($array, function ($value, $key) {
   return $value >= 150;
});

// 200

يمكن تمرير قيمة افتراضية كمعامل ثالث. تُعاد القيمة الافتراضية في حال لم يستجب أي عنصر لشرط الصحّة:

$first = array_first($array, $callback, $default);

()array_flatten

تسطِّح الدالة مصفوفة متعدّدة الأبعاد لمصفوفة ببعد واحد:

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$flattened = array_flatten($array);

// ['Joe', 'PHP', 'Ruby']

()array_forget

تحذف الدالة الثنائي مفتاح\قيمة من مصفوفة متداخلة باستعمال رمز" النقطة ":

$array = ['products' => ['desk' => ['price' => 100]]];

array_forget($array, 'products.desk');

// ['products' => []]

()array_get

تسترجع الدالة قيمة من مصفوفة متداخلة باستعمال رمز "النقطة":

$array = ['products' => ['desk' => ['price' => 100]]];

$price = array_get($array, 'products.desk.price');

// 100

تقبل الدالة أيضًا قيمة افتراضية تعيدها في حال لم تجد المفتاح الممرّر:

$discount = array_get($array, 'products.desk.discount', 0);

// 0

()array_has

تتثبت الدالة من وجود عنصر أو عناصر ممرّرة في المصفوفة باستعمال الرمز "نقطة":

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = array_has($array, 'product.name');

// true

$contains = array_has($array, ['product.price', 'product.discount']);

// false

()array_last

تعيد الدالة آخر عنصر يستجيب لشرط الصحّة:

$array = [100, 200, 300, 110];

$last = array_last($array, function ($value, $key) {
 return $value >= 150;
});

// 300

يمكن تمرير قيمة افتراضية كمعامل ثالث تعيدها الدالة في حال لم يستجب أي عنصر لشرط الصحة:

$last = array_last($array, $callback, $default);

()array_only

تعبد الدالة فقط الثنائيات الممرّرة من المصفوفة:

$array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];

$slice = array_only($array, ['name', 'price']);

// ['name' => 'Desk', 'price' => 100]

()array_pluck

تستعيد الدالة كل القيم لمفتاح ممرّر من المصفوفة:

$array = [
  ['developer' => ['id' => 1, 'name' => 'Taylor']],
  ['developer' => ['id' => 2, 'name' => 'Abigail']],

$names = array_pluck($array, 'developer.name');
];

// ['Taylor', 'Abigail']

يمكنك أيضًا تحديد المفاتيح التي تريد لعرضها في النتيجة :

$names = array_pluck($array, 'developer.name', 'developer.id');

// [1 => 'Taylor', 2 => 'Abigail']

()array_prepend

تضبف الدالة عنصرًا في أول المصفوفة:

$array = ['one', 'two', 'three', 'four'];

$array = array_prepend($array, 'zero');

// ['zero', 'one', 'two', 'three', 'four']

عند الحاجة، بإمكانك تحديد المفتاح الذي يجب استعماله مع القيمة:

$array = ['price' => 100];

$array = array_prepend($array, 'Desk', 'name');

// ['name' => 'Desk', 'price' => 100]

()array_pull

تعيد الدالة وتحذف ثنائي مفتاح\قيمة من المصفوفة:

$array = ['name' => 'Desk', 'price' => 100];

$name = array_pull($array, 'name');

// $name: Desk

// $array: ['price' => 100]

يمكن تمرير قيمة افتراضية كمعامل ثالث تعيده الدالة في حال عدم وجود المفتاح:

$value = array_pull($array, $key, $default);

()array_random

تعيد الدالة قيمة عشوائية من المصفوفة:

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

$random = array_random($array);

// 4 - (اختيرت بعشوائية)

يمكن أيضًا تحديد عدد العناصر الذي يجب إعادته كمعامل ثاني اختياري.لاحظ أن هذا الخيار سيعيد مصفوفة حتو لو اخترت عنصرًا واحدًا:

$items = array_random($array, 2);

// [2, 5] - (retrieved randomly)

()array_set

تعيّن الدالة قيمة في مصفوفة متداخلة باستعمال الرمز "نقطة":

$array = ['products' => ['desk' => ['price' => 100]]];

array_set($array, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

()array_sort

ترتّب الدالة المصفوفة حسب القيم:

$array = ['Desk', 'Table', 'Chair'];

$sorted = array_sort($array);

// ['Chair', 'Desk', 'Table']

يمكن أيضًا ترتيب مصفوفة حسب نتائج النطاق المغلق Closure:

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(array_sort($array, function ($value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Chair'],
        ['name' => 'Desk'],
        ['name' => 'Table'],
    ]
*/

()array_sort_recursive

ترتّب الدالة المصفوفة مرتبة بشكل تكراري باستعمال الدالة sort:

$array = [
    ['Roman', 'Taylor', 'Li'],
    ['PHP', 'Ruby', 'JavaScript'],
];

$sorted = array_sort_recursive($array);

/*
    [
        ['Li', 'Roman', 'Taylor'],
        ['JavaScript', 'PHP', 'Ruby'],
    ]
*/

()array_where

ترشح الدالة المصفوفة باستعمال النطاق المغلق المعطى Closure:

$array = [100, '200', 300, '400', 500];

$filtered = array_where($array, function ($value, $key) {
    return is_string($value);
});

// [1 => '200', 3 => '400']

()array_wrap

تغلف الدالة القيمة الممرّرة في مصفوفة. إذا كانت القيمة الممرّرة مصفوفة بالأصل فلن تتغير:

$string = 'Laravel';

$array = array_wrap($string);

// ['Laravel']

إذا كانت القيمة الممرّرة null، تعيد الدالة array_wrap مصفوفة فارغة:

$nothing = null;

$array = array_wrap($nothing);

// []

()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

()data_set

تضبط الدالة قيمة في مصفوفة متداخلة أو كائن باستعمال الرمز "نقطة":

$data = ['products' => ['desk' => ['price' => 100]]];

data_set($data, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

تقبل الدالة data_set أيضًا محرفات بديلة وتعوضها بما يلائم:

$data = [

   'products' => [
       ['name' => 'Desk 1', 'price' => 100],
       ['name' => 'Desk 2', 'price' => 150],
   ],
];

data_set($data, 'products.*.price', 200);

/*

   [
       'products' => [
           ['name' => 'Desk 1', 'price' => 200],
           ['name' => 'Desk 2', 'price' => 200],
       ],
   ]

في العادة، تعاد كتابة القيم. إذا أردت تعيين قيمة غير موجودة، يمكنك تمرير القيمة false كمعامل ثالث:

$data = ['products' => ['desk' => ['price' => 100]]];

data_set($data, 'products.desk.price', 200, false);

// ['products' => ['desk' => ['price' => 100]]]

()head

تعيد الدالة العنصر الأول من مصفوفة ممرّرة:

$array = [100, 200, 300];

$first = head($array);

// 100

()last

تعيد الدالة العنصر الأخير من المصفوفة الممرّرة:

$array = [100, 200, 300];

$last = last($array);

// 300

المسارات

()app_path

تعيد الدالة المسار الكامل للدليل app. يمكن أيضًا استعمال الدالة لإنشاء مسار لملف موجود في دليل التطبيق:

$path = app_path();

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

()base_path

تعيد الدالة مسارا لجذر التطبيق. يمكنك أيضًا استعمال الدالة لإنشاء مسار مؤهل بشكل كامل لملف تابع لدليل جذر التطبيق:

$path = base_path();

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

()config_path

تعيد الدالة‎ المسار المؤهل بشكل كامل للدليل config. يمكنك استعمال الدالة لإنشاء مسار مؤهل بشكل كامل لملف معين في دليل الضبط:

$path = config_path();

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

()data_path

تعيد الدالة مسارا مؤهلا للدليل database. يمكن أيضًا استعمال الدالة لإنشاء مسار مؤهل لملف في دليل قاعدة البيانات:

$path = database_path();

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

()mix

تعيد الدالة مسارا للملف Mix:

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

()public_path

تعيد الدالة مسارًا مؤهلا للدليل public. يمكنك أيضًا استعمال الدالة لإنشاء مسارات مؤهلة لملفات في الدليل public:

$path = public_path();

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

()resource_path

تعيد الدالة مسارًا مؤهلا للدليل resources. يمكنك أيضًا استعمال الدالة لإنشاء مسار مؤهل لملف في الدليل resources:

$path = resource_path();

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

()storage_path

تعيد الدالة مسارًا مؤهلا للدليل storage. يمكن أيضًا استعمال الدالة لإنشاء مسارات مؤهلة لملف في الدليل storage:

$path = storage_path();

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

السلاسل النصية

()__

تترجم الدالة سلسلة الترجمة أو مفتاح الترجمة باستعمال ملفات الترجمة في التطبيق:

echo __('Welcome to our application');

echo __('messages.welcome');

إذا لم توجد سلسلة أو مفتاح الترجمة، تعيد الدالة القيمة الممرّرة. لذا باستعمال المثال السابق، تعيد الدالة "message.welcome" في حال عدم وجود المفتاح.

()camel_case

تحوّل الدالة السلسلة لسلسلة منسقةً بحالة سِنَام الجمل:

$converted = camel_case('foo_bar');

// fooBar

()class_basename

تعيد الدالة اسم الصنف للصنف الممرّر بعد حذف دليله:

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

// Baz

()e

تنفذ الدالة الدالة htmlspecialchars من PHP مع الخيار double_encode على القيمة true افتراضيًّا:

echo e('<html>foo</html>');

// <html>foo</html>

()ends_with

تحدّد الدالة إذا كانت السلسلة تنتهي بالقيمة الممرّرة:

$result = ends_with('This is my name', 'name');

// true

()kebab_case

تحول الدالة السلسلة الممرّرة منسقةً بحالة kebab-case:

$converted = kebab_case('fooBar');

// foo-bar

()preg_replace_array

تعوّض الدالة الأسلوب الممرّر في السلسلة باستعمال مصفوفة:

$string = 'The event will take place between :start and :end';

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

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

()snake_case

تحول الدالة السلسلة الممرّرة منسقةً بحالة snake_case:

$converted = snake_case('fooBar');

// foo_bar

()starts_with

تحدد الدالة إذا كان السلسلة الممرّرة تبدأ بالقيمة الممررّة:

$result = starts_with('This is my name', 'This');

// true

()str_after

تعيد الدالة كل شيء بعد السلسلة الممررة:

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

// ' my name'

()str_before

تعيد الدالة كل شيء قبل السلسلة الممررة:

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

// 'This is '

()str_contains

تحدد الدالة إذا كانت السلسلة تحتوي القيمة الممرّرة (مع احترام الحروف الكبيرة والصغيرة):

$contains = str_contains('This is my name', 'my');

// true

يمكنك تمرير مصفوفة من القيم لتحدد إذا كانت موجودة في السلسلة:

$contains = str_contains('This is my name', ['my', 'foo']);

// true

()str_finish

تضيف الدالة نسخةً واحدةً من قيمة ممرّرة لسلسلة إذا لم تكن السلسلة تنتهي بتلك القيمة:

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

// this/string/

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

// this/string/

()str_is

تحدد الدالة إذا كانت السلسلة مطابقة لأسلوب ممرّر. تُستعمل الرموز "*" للدلالة على محرف بدل:

$matches = str_is('foo*', 'foobar');

// true

$matches = str_is('baz*', 'foobar');

// false

()str_limit

تقطع الدالة السلسلة حسب الطول المحدد:

cated = str_limit('The quick brown fox jumps over the lazy dog', 20);

// The quick brown fox...

يمكنك تمرير معامل ثالث لتغيير السلسلة التي تضاف في الآخر:

$truncated = str_limit('The quick brown fox jumps over the lazy dog', 20, ' (...)');

// The quick brown fox (...)

()Str::orderedUuid

تنشئ الدالة معرف فريد عالمي لبصمة وقت يمكن تخزينه في قاعدة بيانات:

use Illuminate\Support\Str;

return (string) Str::orderedUuid();

()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

تنشئ الدالة سلسلة نصية عشوائية بالطول المحدد. تستخدم هذه الدالة الدالة random_bytes من PHP:

$random = str_random(40);

()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_singular

تحوّل الدالة سلسلة نصية لصيغة المفرد. تدعم الدالة الآن فقط اللغة الإنقليزية:

$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_slug

تنشئ الدالة قيمة "slug" يمكن استعمالها مع مسارات URL:

$slug = str_slug('Laravel 5 Framework', '-');

// laravel-5-framework

()str_start

تضيف الدالة نسخة واحدة من القيمة الممرّرة في أول السلسلة إذا لم تكن موجودة:

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

// /this/string

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

// /this/string

()studly_case

تحول الدالة السلسلة الممرّرة منسقةً بحالة StudlyCase:

$converted = studly_case('foo_bar');

// FooBar

()title_case

تحول الدالة السلسلة الممرّرة منسقةً بحالة Title Case:

$converted = title_case('a nice title uses the correct case');

// A Nice Title Uses The Correct Case

()trans

تترجم الدالة مفتاح الترجمة الممرّر باستعمال ملفات التوطين:

echo trans('messages.welcome');

إذا لم يكن مفتاح الترجمة موجودًا، تعيد الدالة المفتاح الممرّر. لذا، في المثال السابق ستعيد الدالة message.welcome في حال لم يكن المفتاح موجودًا في ملف التوطين.

()trans_choice

تترجم الدالة السلسلة الممرّرة مع مع تصريف الكلمة حسب العدد المُمرَّر إلى الدالة (inflection):

echo trans_choice('messages.notifications', $unreadCount);

إذا لم يكن مفتاح الترجمة موجودًا، تعيد الدالة المفتاح الممرّر. لذا، في المثال السابق ستعيد الدالة welcome.notifications في حال لم يكن المفتاح موجودًا.

()Str::uuid

تنشئ الدالة المعرف الفريد العالمي UUID (الإصدار 4):

use Illuminate\Support\Str;

return (string) Str::uuid();

العناوين URLs

()action

تنشئ الدالة عنوان URL لعمل وحدة التحكم. لا تحتاج لتمرير مجال الأسماء الكامل لوحدة التحكم. بدلًا من ذلك، مرّر اسم صنف وحدة التحكم نسبة لمجال الأسماء :

App\Http\Controllers:

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

$url = action([HomeController::class, 'index']);

إذا كان التابع يقبل معاملات مسارات، يمكنك تمريرها كمعامل ثاني للدالة:

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

()asset

تولّد الدالة عنوان URL للأصول باستخدام مخطط الطلب ( HTTP أو HTTPS):

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

()secure_asset

تولّد الدالة عنوان URL لأحد الأصول باستخدام HTTPS:

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

()route

تنشئ الدالة عنوان URL للمسار المسمى:

$url = route('routeName');

إذا كان المسار يقبل معاملات، يمكنك تمريرها كمعامل ثاني للتابع:

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

في العادة تنشئ الدالة route عنوان URL مطلق، إذا أردت عنوانا نسبيا، مرّر false كمعامل ثالث:

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

()secure_url

تنشئ الدالة عنوان HTTPS URL مؤهل بشكل تام للمسار الممرّر:

$url = secure_url('user/profile');

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

()url

تنشئ الدالة عنوان URL مؤهل بشكل تام للمسار الممرّر:

$url = url('user/profile');

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

إذا لم يُوفّر أي مسار، تعيد الدالة url نسخة Illuminate\Routing\UrlGenerator:

$current = url()->current();

$full = url()->full();

$previous = url()->previous();

متنوعات

()abort

تطلق الدالة استثناء HTTP يظهر بمعالج الإستثناءات:

abort(403);

يمكنك أيضًا توفير نص جواب الاستثناء والأجوبة المخصصة للترويسات:

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

()abort_if

تطلق الدالة استثناء HTTP إذا كانت نتيجة عبارة منطقية ممرّرة هي القيمة true:

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

مثل الدالة abort، يمكنك توفير نص جواب الاستثناء كمعامل ثالث و مصفوفة الأجوبة المخصصة للترويسات كمعامل رابع.

()abort_unless

تطلق الدالة استثناء HTTP إذا كان نتيجة عبارة منطقية ممرّرة هي القيمة false:

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

مثل الدالة abort، يمكنك توفير نص جواب الاستثناء كمعامل ثالث و مصفوفة الأجوبة المخصصة للترويسات كمعامل رابع.

()app

تعيد الدالة نسخة حاوي الخدمات:

$container = app();

يمكنك تمرير اسم صنف أو واجهة لتنفيذه من الحاوي:

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

()auth

تعيد الدالة نسخة مُصادق (authentificator). يمكنك استعمال الدالة بدل الواجهة الساكنة Auth لسهولة العمل:

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

عند الحاجة، يمكنك تحديد أي نسخة حارس تريد استعمالها:

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

()back

تنشئ الدالة جواب HTML لإعادة التوجيه للمكان السابق للمستخدم:

return back($status = 302, $headers = [], $fallback = false);

return back();

()bcrypt

تجزّء الدالة القيمة المرّرة باستعمال Bcrypt. يمكنك استعمال الدالة كبديل عن الواجهة الساكنة Hash:

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

()broadcast

تبث الدالة الحدث المرّر للمنصتات:

broadcast(new UserRegistered($user));

()blank

تتثبت الدالة من إذا كانت القيمة الممرّرة فارغة:

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

// true

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

// false

لعكس وظيفة الدالة blank، اطلع على الدالة filled.

()cache

تُستعمل الدالة لاسترجاع قيمة من التخزين المؤقت. إذا لم يكن المفتاح المرّر موجودًا، تعيد الدالة cache قيمة افتراضية:

$value = cache('key');

$value = cache('key', 'default');

يمكنك إضافة عناصر للتخزين المؤقت عبر تمرير ثنائي مفتاح \ قيمة للدالة cache. يجب عليك أيضًا تمرير عدد الدقائق أو المدة التي تبقى فيها القيمة صالحة في التخزين:

cache(['key' => 'value'], 5);

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

()class_uses_recursive

تعيد الدالة كل السمات (traits) التي يستعملها الصنف بما في ذلك السمات التي تستعملها الأصناف الآباء:

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

()collect

تنشئ لدالة نسخة مجموعة من القيم الممرّرة:

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

()config

تسترجع الدالة قيمة متغير ضبط. يمكن الوصول إلى القيمة باستعمال صياغة "النقاط" التي تتضمّن اسم الملف و الخيار الذي تريد الوصول إليه. يمكن تحديد قيمة افتراضية تعيدها الدالة config إذا كان خيار الضبط غير موجود:

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

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

يمكنك تعيين متغيرات ضبط وقت التشغيل عبر تمرير ثنائي مفتاح \ قيمة:

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

()cookie

تنشئ الدالة نسخة cookie جديدة:

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

()csrf_field

تنشئ الدالة حقل إدخال HTML مخفيًّا يحتوي قيمة الرمز csrf. مثلًا باستعمال صياغة Blade:

{{ csrf_field() }}

()csrf_token

تستردّ الدالة قيمة رمز CSRF:

$token = csrf_token();

()dd

تُفرغ الدالة المتغيّر الممرّر وتنهي تنفيذ السكريبت:

dd($value);

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

إذا لم ترد إيقاف السكريبت، استخدم الدالة dump.

()decrypt

تفك الدالة تشفير القيمة الممرّرة باستعمال مشفّر Laravel:

$decrypted = decrypt($encrypted_value);

()dispatch

تُرسل الدالة المهمة الممرّرة للطابور:

dispatch(new App\Jobs\SendEmails);

()dispatch_now

تنفذ الدالة المهمة الممرّرة وتعيد قيمة التابع handle:

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

()dump

تُفرغ الدالة المتغير الممرّر:

dump($value);

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

إذا أردت إيقاف التنفيذ بعد التفريغ استعمل الدالة dd.

ملاحظة : يمكنك استعمال الأمر dump-server لتلقي كل نداءات التفريغ وعرضهم في شاشة سطر الأوامر بدل المتصفح.

()encrypt

تشفّر الدالة القيمة الممرّرة باستعمال مشفّر Laravel:

$encrypted = encrypt($unencrypted_value);

()env

تستردّ الدالة متغيّرات البيئة أو تعيد قيمة افتراضية:

$env = env('APP_ENV');

// تعيد production إذا كانت المتغيرات غير معدّة

$env = env('APP_ENV', 'production');

()event

تطلق الدالة الأحداث للمنصتات:

event(new UserRegistered($user));

()factory

تنشئ الدالة منشئ نموذج منتج (model factory builder) للصنف والاسم والكمية المرّرة. يمكن استعمالها في الاختبار و في تعبئة قاعدة البيانات:

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

()filled

تعيد الدالة قيمة منطقية حول القيمة الممرّرة إن هي غير فارغة أم لا:

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

// true

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

// false

لعكس وظيفة الدالة، استعمل الدالة blank.

()info

تكتب الدالة معلومات في ملف log:

info('Some helpful information!');

يمكن أيضًا تمرير مصفوفة من البيانات النصيّة:

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

()logger

تُستعمل الدالة لكتابة رسائل في ملف الضبط في مستوى debug:

logger('Debug message');

يمكن أيضًا تمرير مصفوفة من البيانات النصيّة:

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

تعيد الدالة نسخة logger إذا لم تمرّر معاملات:

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

()method_field

تنشئ الدالة حقل كتابة مخفي يحتوي قيمة طريقة HTTP في الاستمارة. مثلًا، باستعمال صياغة Blade:

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

()now

تنشئ الدالة نسخة Illuminate\Support\Carbon للوقت الحالي:

$now = now();

()old

تسترجع الدالة قيمة قديمة حُذفت من الجلسة:

$value = old('value');

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

()optional

تقبل الدالة معاملا وتسمح لك بالوصول إلى خصائصه، توابعه، أو كائناته . سيعيد الطلب القيمة null بدل إحداث خطأ إذا كانت القيمة الممرّرة null:

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

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

تقبل الدالة أيضًا نداء Closure كمعامل ثاني. ينفَّذ المعامل الثاني إذا كانت قيمة المعامل الأول مخالفة لnull:

return optional(User::find($id), function ($user) {
    return TwitterApi::findUser($user->twitter_id);
});

()policy

تستردّ الدالة نسخة policy لصنف ممرّر:

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

()redirect

تعيد الدالة جواب HTTP لإعادة التوجيه أو تعيد نسخة الموجّه إذا نوديت دون معامل:

return redirect($to = null, $status = 302, $headers = [], $secure = null);

return redirect('/home');

return redirect()->route('route.name');

()report

تبلغ الدالة عن وجود استثناء باستعمال التابع report من معالج الاستثناءات:

report($e);

()request

تعيد الدالة نسخة الطلب الحالي أو تحصل على عنصر إدخال:

$request = request();

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

()rescue

تنفّذ الدالة النطاق المغلق الممرّر Closure و تتلقى كل استثناء مطلق عند تنفيذه. تُرسل كل الاستثناءات للتابع report من معالج الاستثناءات لكن الدالة تكمل العمل:

return rescue(function () {

   return $this->method();
});

يمكنك تمرير معامل ثاني  للدالة rescue يكون القيمة الافتراضية التي تعيدها في حال ظهور استثناء عند تنفيذ Closure:

return rescue(function () {

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

return rescue(function () {

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

   return $this->failure();
});

()resolve

تحل الدالة الصنف أو الواجهة الممرّرة باستعمال حاوي الخدمات:

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

()response

تنشئ الدالة نسخة جواب أو تحصل على نسخة من منتج الجواب:

return response('Hello World', 200, $headers);

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

()retry

تحاول الدالة تنفيذ النداء الممرّر حتى تصل للحد الأقصى المحدد من المحاولات. إذا لم يطلق النداء أي استثناء، تعيد الدالة retry القيمة المعادة من النداء. إذا أطلق النداء استثناء، تعيد الدالة retry محاولة تنفيذه. إذا وصلت الدالة للحد الأقصى من المحاولات، تطلق الدالة retry الاستثناء:

return retry(5, function () {

  // المحاولة 5 مرات مع الإنتظار 100 جزء من الثانية بين المحاولات
}, 100);

()session

يمكن استعمال الدالة لاسترداد أو تعيين قيم من الجلسة:

$value = session('key');

يمكنك تعيين قيم بتمرير ثنائي مفتاح \ قيمة للدالة:

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

يعاد مخزن الجلسة (session store) إذا نوديت الدالة دون تمرير أي قيمة:

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

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

()tap

تقبل الدالة معاملين : قيمة عشوائية value$ والنطاق المغلق Closure. تمرّر القيمة للنطاق المغلق Closure ثم تعيدها الدالة tap. القيمة التي تعيدها Closure غير مهمة:

$user = tap(User::first(), function ($user) {

   $user->name = 'taylor';
   $user->save();
});

إذا لم تمرّر Closure يمكنك نداء أي تابع مع القيمة value$. تعيد الدالة دائما value$ مهما أعاد التابع المنادى. على سبيل المثال، التابع update من Eloquent يعيد عادة رقمًا لكن بإمكاننا إرغام التابع على إعادة النموذج نفسه عبر إضافة التابع update  للدالة tap:

$user = tap($user)->update([

   'name' => $name,
   'email' => $email,
]);

()today

تنشئ الدالة نسخة Illuminate\Support\Carbon للتاريخ الحالي:

$today = today();

()thow_if

تطلق الدالة الاستثناء الممرّر إذا كانت نتيجة العبارة المنطقية الممرّرة true:

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(Auth::user()->isAdmin(), AuthorizationException::class);

throw_unless(

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

()trait_uses_recursive

تعيد الدالة كل السمات المستعملة من قبل سمة:

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

()transform

تنفذ الدالة النطاق المغلق Closure على قيمة ممرّرة إذا لم تكن فارغة وتعيد نتيجة النطاق المغلق:

$callback = function ($value) {

   return $value * 2;
};

$result = transform(5, $callback);

// 10

يمكن تمرير قيمة مبدئية أو Closure تعاد حين تكون القيمة الممرّرة فارغة:

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

// The value is blank

()validator

تنشئ الدالة نسخة validator بالمعامل الممرّر. يمكن استعمال الدالة كبديل عن الواجهة الساكنة Validator لسهولة العمل:

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

()value

تعيد الدالة القيمة الممرّرة، لكن إذا مرّرت نطاقًا مغلقًا، سينفذ وتعاد نتيجته:

$result = value(true);

// true

$result = value(function () {

   return false;
});

// false

()view

تستردّ الدالة نسخة واجهة:

return view('auth.login');

()with

تعيد الدالة القيمة الممرّرة. إذا مرّرت  نطاقًا مغلقًا Closure كمعامل ثاني للدالة، سينفذ وتعاد نتيجته:

$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

مصادر

• صفحة Helpers في توثيق Laravel الرسمي.