عرض مصدر Laravel/requests

<noinclude>{{DISPLAYTITLE:الطلبات HTTP}}</noinclude>
==الوصول إلى الطلب==
عليك التلميح إلى نوع الصنف <code>Illuminate\Http\Request</code> في وحدة تحكمّك للحصول على نسخة الطلب HTTP الحالي عبر إضافة الاعتماديّة. ستُضاف نسخة الطلب الوارد تلقائيًّا بواسطة حاوي الخدمات:<syntaxhighlight lang="php">
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * خزّن مستخدمًا جديدًا
     *
     * @param  Request  $request
     * @return Response
     */
    public function store(Request $request)
    {
        $name = $request->input('name');

       //
    }
}



</syntaxhighlight>
====إضافة الاعتماديّات ومعاملات المسار (Dependency Injection & Route Parameters)====
عليك إدراج مُعاملات مسارك بعد اعتماديّاتك الأخرى إن توقّع تابع وحدة التحكّم أيضًا إدخالًا من مُعاملة مسار. على سبيل المثال، إن عُرّف مسارك كما يلي:<syntaxhighlight lang="php">

Route::put('user/{id}', 'UserController@update');

</syntaxhighlight>لا يزال بإمكانك تلميح إلى النوع <code>Illuminate\Http\Request</code> والوصول إلى المعامل <code>id</code> بتعريف تابع وحدة تحكّمك كما يلي:<syntaxhighlight lang="php">
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * تحديث المستخدم المحدد.
     *
     * @param  Request  $request
     * @param  string  $id
     * @return Response
     */
    public function update(Request $request, $id)
    {
       //
    }
}



</syntaxhighlight>
====الوصول إلى الطلبات عبر المسارات Closure====
تستطيع أيضًا التلميح إلى نوع الصنف <code>Illuminate\Http\Request</code> في النطاق المغلق Closure للمسار. سيضيف حاوي الخدمات الطلب الوارد تلقائيًا في النطاق المغلق Closure عند تنفيذه:<syntaxhighlight lang="php">
use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
   //
});



</syntaxhighlight>
====مسار الطلب والتابع====
تُوفّر النسخة <code>Illuminate\Http\Request</code> مجموعةً متنوعةً من الدوال لفحص الطلب HTTP لتطبيقك وتوسيع الصنف <code>Symfony\Component\HttpFoundation\Request</code>. سنناقش أدناه بعضًا من أهم تلك الدوال.
====استرداد مسار الطلب====
يعيد التابع <code>path</code> معلومات مسار الطلب. أي إن استهدف الطلب الوارد <code><nowiki>http://domain.com/foo/bar</nowiki></code>، سيرد التابع <code>foo/bar</code> <code>path</code>:<syntaxhighlight lang="php">
$uri = $request->path();

</syntaxhighlight>يسمح لك التابع <code>is</code> بالتحقق من مطابقة مسار الطلب الوارد بنمط محدد. يمكنك استخدام الرمز <code>*</code> كحرف بدل (wildcard) عند استخدام هذا التابع:<syntaxhighlight lang="php">
if ($request->is('admin/*')) {
   //
}
</syntaxhighlight>
====استرداد عنوان الطلب====
تستطيع استخدام التابع <code>url</code> أو <code>fullUrl</code> لاسترداد العنوان URL الكامل للطلب الوارد. سيرد التابع <code>url</code> العنوان URL بدون سلسلة الاستعلام النصيّة (query string)، بينما يحتوي التابع <code>fullUrl</code> سلسلة الاستعلام:<syntaxhighlight lang="php">

// بدون سلسلة الاستعلام ...
$url = $request->url();

// مع سلسلة الاستعلام ...
$url = $request->fullUrl();

</syntaxhighlight>

==== استرداد تابع الطلب ====
سيُعيد التابع <code>method</code> الطريقة HTTP للطلب. تستطيع استخدام التابع <code>isMethod</code> للتحقق من مطابقة الطريقة HTTP لسلسلة نصيّة معينة:<syntaxhighlight lang="php">
$method = $request->method();

if ($request->isMethod('post')) {
   //
}
</syntaxhighlight>

=== الطلبات PSR-7 ===
يحدّد المعيار PSR-7 واجهات الرسائل HTTP، بما في ذلك الطلبات والردود. إذا رغبت في الحصول على نسخة لطلب PSR-7 بدلاً من طلب Laravel، ستحتاج أولاً لتثبيت بضع مكتبات. يستخدم Laravel المكوّن Symfony HTTP Message Bridge لتحويل طلبات واستجابات Laravel المُعتادة إلى تعاريف استخدام متوافقة مع PSR-7:<syntaxhighlight lang="php">
composer require symfony/psr-http-message-bridge
composer require zendframework/zend-diactoros
</syntaxhighlight>يمكنك الحصول على طلب PSR-7 بمجرد تثبيتك لهذه المكتبات بالتلميح إلى نوع واجهة الطلب على مسارك (Closure) أو تابع وحدة التحكّم:<syntaxhighlight lang="php">
use Psr\Http\Message\ServerRequestInterface;

Route::get('/', function (ServerRequestInterface $request) {
   //
});
</syntaxhighlight>'''ملاحظة''': ستُحوّل نسخة الاستجابة PSR-7 من مسار أو وحدة تحكّم، تلقائيًا إلى نسخة استجابة Laravel وسيتم عرضها بواسطة إطار العمل.

== تشذيب الإدخالات والتطبيع (Input Trimming & Normalization) ==
يحتوي Laravel البرمجيّات الوسيطة <code>TrimStrings</code> و <code>ConvertEmptyStringsToNull</code> في مكدّس (stack) برمجيّتك الوسيطة العامة بتطبيقك افتراضيًّا. تجد قائمة هذه البرمجيّات الوسيطة في المكدّس في الصنف <code>App\Http\Kernel</code>. ستُشذّب هذه البرامج الوسيطة كلّ حقول السلاسل النصيّة الواردة تلقائيًا في الطلب، إضافةً لتحويل أي حقول سلسلة فارغة إلى قيمة خالية <code>null</code>. تريحك هذه الخاصيّة من القلق حول مشاكل التطبيع في مساراتك ووحدات تحكّمك.
يمكنك إزالة البرمجيّتين الوسيطتين من مُكدّس برمجيّات تطبيقك الوسيطة عبر إزالتها من الخاصيّة <code>middleware$</code>  بالصنف <code>App\Http\Kernel</code> إذا رغبت في تعطيل هذا السلوك.

== استرجاع الإدخالات ==

==== استرداد جميع بيانات الإدخالات ====
تستطيع أيضًا استرداد جميع بيانات الإدخال كمصفوفة باستخدام التابع <code>all</code>:<syntaxhighlight lang="php">
$input = $request->all();

</syntaxhighlight>

==== استرداد قيمة إدخال ====
باستخدام بعض الدوال البسيطة، يمكنك الوصول لكافّة إدخالات المستخدم من نسختك <code>Illuminate\Http\Request</code> دون القلق بشأن هويّة الطريقة HTTP المستخدمة في الطلب. يمكن استخدام التابع <code>input</code> لاسترداد إدخال المستخدم بغض النظر عن الطريقة HTTP:<syntaxhighlight lang="php">
$name = $request->input('name');

</syntaxhighlight>يمكنك تمرير قيمة افتراضية كمتغيّر وسيط ثاني للتابع <code>input</code>. ستُردُّ هذه القيمة إن لم تكن قيمة الإدخال المطلوبة موجودة في الطلب:<syntaxhighlight lang="php">
$name = $request->input('name', 'Sally');

</syntaxhighlight>استخدم التدوين "نقطة" للوصول إلى المصفوفات عند استخدام استمارات تحتوي على إدخالات مصفوفة:<syntaxhighlight lang="php">
$name = $request->input('products.0.name');

$names = $request->input('products.*.name');
</syntaxhighlight>

==== استرداد الإدخالات من سلسلة الاستعلام النصيّة (Query string) ====
بينما يقوم التابع <code>input</code> باسترداد القيم من كامل حمولة الطلب بالكامل (بما في ذلك سلسلة الاستعلام)، يقوم التابع query باسترداد القيم من سلسلة الاستعلام فقط:<syntaxhighlight lang="php">
$name = $request->query('name');

</syntaxhighlight>سيُرد المتغيّر الوسيط الثاني لهذا التابع إن لم تكن بيانات قيمة سلسلة الاستعلام المطلوبة موجودة:<syntaxhighlight lang="php">
$name = $request->query('name', 'Helen');

</syntaxhighlight>تستطيع استدعاء التابع <code>query</code> دون أي متغيّرات وسيطة لاسترداد جميع قيم سلسلة الاستعلام كمصفوفة ترابطية:<syntaxhighlight lang="php">
$query = $request->query();

</syntaxhighlight>

==== استرداد الإدخالات عبر الخاصيّات الديناميكية ====
تستطيع أيضًا الوصول إلى إدخال المستخدم باستخدام الخصائص الديناميكية في النسخة <code>Illuminate\Http\Request</code>. على سبيل المثال، إن احتوى أحد نماذج تطبيقك على حقل name، يمكنك الوصول إلى قيمة الحقل بهذه الطريقة:<syntaxhighlight lang="php">
$name = $request->name;

</syntaxhighlight>سيبحث Laravel أولاً عن قيمة المُعامل في حمولة للطلب عند استخدام الخصائص الديناميكية. إن لم يوجد، سيبحث Laravel عن الحقل في معامل المسار.

==== استرجاع قيم إدخال JSON ====
عند إرسال طلبات JSON إلى تطبيقك، يمكنك الوصول إلى بيانات JSON عبر التابع <code>input</code> ما دامت ترويسة الطلب Content-Type معيّنة بشكل صحيح إلى <code>application/json</code>.

يمكنك حتى استخدام التدوين "نقطة" للتنقيب في مصفوفات JSON:<syntaxhighlight lang="php">
$name = $request->input('user.name');

</syntaxhighlight>

==== استرداد جزء من بيانات الإدخال ====
إن احتجت لاسترداد مجموعة فرعية من بيانات الإدخال، يمكنك استخدام التابعين <code>only</code> و <code>except</code>. يقبل كلاهما مصفوفة واحدة أو قائمة ديناميكية من الوسائط:<syntaxhighlight lang="php">
$input = $request->only(['username', 'password']);

$input = $request->only('username', 'password');

$input = $request->except(['credit_card']);

$input = $request->except('credit_card');
</syntaxhighlight>'''ملاحظة''': يُعيد التابع <code>only</code> كل أزواج المفاتيح/القيم التي تطلبها لكنها لن ترد أزواج المفاتيح/القيمة غير الموجودة في الطلب.

==== التأكد من وجود قيمة الإدخال ====
عليك استخدام التابع <code>has</code> على الطلب للتأكد من وجود قيمة ما. يرد التابع <code>has</code> القيمة <code>true</code> إذا كانت القيمة موجودة في الطلب:<syntaxhighlight lang="php">
if ($request->has('name')) {
   //
}
</syntaxhighlight>سيحّدد التابع <code>has</code> إذا كانت جميع القيم المحددة موجودة عند إعطائه مصفوفة معيّنة:<syntaxhighlight lang="php">
if ($request->has(['name', 'email'])) {
   //
}
</syntaxhighlight>إذا رغبت في تحديد ما إذا كانت القيمة غير فارغة وموجودة في الطلب، تستطيع استخدام التابع <code>filled</code>:<syntaxhighlight lang="php">
if ($request->filled('name')) {
   //
}
</syntaxhighlight>

==== الإدخالات القديمة ====
يتيح لك Laravel الاحتفاظ بالإدخال من طلب واحد أثناء الطلب التالي. هذه الميزة مفيدة بشكل خاص في إعادة ملء الاستمارات بعد اكتشاف أخطاء عند التحقق من الصحة. لكن إن كنت تستخدم ميزات التحقق (validation features) المضمنة في Laravel فمن غير الرّاجح أن تحتاج لاستخدام هذه الأساليب يدويًا نظرًا لأن بعض وحدات التحقق المضمنة في Laravel تُناديها تلقائيًا.

==== توميض الإدخالات للجلسة ====
سيومض التابع <code>flash</code> في الصنف <code>Illuminate\Http\Request</code> الإدخال الحالي في الجلسة كي تكون متاحة أثناء طلب المستخدم التالي للتطبيق:<syntaxhighlight lang="php">
$request->flash();

</syntaxhighlight>يمكنك أيضًا استخدام التابعين <code>flashOnly</code> و <code>flashExcept</code> لتوميض مجموعة فرعية من بيانات الطلب للجلسة. هذه التوابع مفيدة في الاحتفاظ بالمعلومات الحساسة مثل كلمات المرور خارج الجلسة:<syntaxhighlight lang="php">
$request->flashOnly(['username', 'email']);

$request->flashExcept('password');
</syntaxhighlight>

==== توميض الإدخالات ثم إعادة التوجيه ====
نظرًا لأنك سترغب غالبًا بتوميض الإدخال في الجلسة ثم إعادة التوجيه إلى الصفحة السابقة، يمكنك بسهولة سلسلة توميض الإدخالات عند إعادة التوجيه باستخدام التابع <code>withInput</code>:<syntaxhighlight lang="php">
return redirect('form')->withInput();

return redirect('form')->withInput(
    $request->except('password')
);
</syntaxhighlight>

==== استرداد المدخلات القديمة ====
لاسترداد الإدخال المموّض (flashed) من الطلب السابق، استخدم التابع <code>old</code> على النسخة <code>Request</code> . سيسحب التابع <code>old</code> بيانات الإدخال التي مُوّضت سابقًا من الجلسة:<syntaxhighlight lang="php">
$username = $request->old('username');

</syntaxhighlight>كما يوفّر Laravel مساعد <code>old</code> عام. من الأفضل استخدام المساعد <code>old</code> إن كنت تعرض المدخلات القديمة في قالب Blade. في حالة عدم وجود إدخال قديم للحقل المحدد ستُردّ قيمة <code>null</code>:<syntaxhighlight lang="php">

<input type="text" name="username" value="{{ old('username') }}">

</syntaxhighlight>

=== ملفات تعريف الارتباط (Cookies) ===

==== استرداد ملفات تعريف الارتباط من الطلبات ====
تُشفّر جميع ملفات تعريف الارتباط التي ينشئها إطار العمل Laravel وتُوّقع بشفرة استيثاق، مما يعني اعتبارها غير صالحة إن غيّرها العميل. لاسترداد قيمة ملف تعريف الارتباط من الطلب، استخدم التابع <code>cookie</code>  على النسخة <code>Illuminate\Http\Request instance</code>:<syntaxhighlight lang="php">
$value = $request->cookie('name');

</syntaxhighlight>يمكنك استخدام الواجهة الساكنة <code>Cookie</code> للوصول إلى قيم ملفات تعريف الارتباط:<syntaxhighlight lang="php">

$value = Cookie::get('name');

</syntaxhighlight>

==== إرفاق ملفات تعريف الارتباط بالردود ====
تستطيع إرفاق ملفات تعريف الارتباط بالنسخة <code>Illuminate\Http\Response</code> الصادرة باستخدام التابع <code>cookie</code>. يجب أن تُمرّر الاسم والقيمة وعدد الدقائق التي تُعتبر ملفات تعريف الارتباط فيها صالحة لهذا التابع:<syntaxhighlight lang="php">
return response('Hello World')->cookie(
    'name', 'value', $minutes
);
</syntaxhighlight>يقبل التابع <code>cookie</code> أيضًا بضع متغيّرات وسيطة أخرى تُستخدم بشكل أندر. عمومًا، لهذه المتغيّرات الوسيطة نفس الغرض والمعنى التي يُعطى للتابع <code>setcookie</code> المحليّة في PHP:<syntaxhighlight lang="php">
return response('Hello World')->cookie(
    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
);
</syntaxhighlight>كبديل، تستطيع استخدام الواجهة الساكنة <code>Cookie</code> لوضع ملفات تعريف الارتباط المعدّة ل Laravel بالاستجابة الصادرة من تطبيقك في "طابور". يقبل التابع queue نسخة Cookie أو المتغيّرات الوسيطة اللازمة لإنشاء نسخة <code>Cookie</code>. ستُرفق هذه الملفات بالاستجابة الصادرة قبل إرسالها إلى المتصفح:<syntaxhighlight lang="php">
Cookie::queue(Cookie::make('name', 'value', $minutes));

Cookie::queue('name', 'value', $minutes);
</syntaxhighlight>

==== توليد نُسخ ملفات تعريف الارتباط ====
إن رغبت في إنشاء نسخة <code>Symfony\Component\HttpFoundation\Cookie</code> يمكن إعطاؤها لنسخة استجابة في وقت لاحق، تستطيع استخدام المساعد العام <code>cookie</code>. لن يُرسل هذا الملف للعميل ما لم تُلحق بنسخة استجابة:<syntaxhighlight lang="php">
$cookie = cookie('name', 'value', $minutes);

return response('Hello World')->cookie($cookie);
</syntaxhighlight>

== الملفات ==

=== استرجاع الملفات المُحمّلة ===
يمكنك الوصول إلى الملفات المُحمّلة عبر النسخة <code>Illuminate\Http\Request</code> باستخدام التابع <code>file</code> أو باستخدام الخصائص الديناميكية. يعيد التابع <code>file</code> نسخة من الصنف <code>Illuminate\Http\UploadedFile</code> الذي يمتد إلى الصنف PHP <code>SplFileInfo</code> ويوفّر مجموعة متنوعة من التوابع للتفاعل مع الملف:<syntaxhighlight lang="php">
$file = $request->file('photo');

$file = $request->photo;
</syntaxhighlight>تستطيع تحديد ما إذا كان الملف موجودًا على الطلب باستخدام التابع <code>hasFile</code>:<syntaxhighlight lang="php">
if ($request->hasFile('photo')) {
   //
}
</syntaxhighlight>

==== التحقق من عمليات التحميل الناجحة ====
بالإضافة للتحقّق من موجود الملف، يمكنك التحقق من عدم وجود مشاكل عند تحميل الملف باستخدام التابع <code>isValid</code>:<syntaxhighlight lang="php">
if ($request->file('photo')->isValid()) {
   //
}
</syntaxhighlight>

==== مسارات الملفات والإضافات ====
يحتوي الصنف <code>UploadedFile</code> أيضًا على توابع للوصول إلى مسار الملف المؤهل بالكامل (fully-qualified) وإضافته (extension). سيحاول التابع <code>extension</code> تخمين امتداد الملف استنادًا إلى محتوياته. قد تختلف هذه الإضافة عن الإضافة التي قدمها العميل:<syntaxhighlight lang="php">
$path = $request->photo->path();

$extension = $request->photo->extension();
</syntaxhighlight>

==== دوال ملفات أخرى ====
توجد مجموعة متنوعة من التوابع الأخرى المتوفرة في النُسخ <code>UploadedFile</code>. ألقِ نظرةً على توثيق الواجهة البرمجية API للصنف لمزيد من المعلومات حول هذه الدوال.

=== تخزين الملفات المُحمّلة ===
لتخزين محمّل، ستستخدم عادةً أحد أنظمة الملفات التي أعددتها. يحتوي الصنف <code>UploadedFile</code> على تابع <code>store</code> ينقل الملف المُحمّل لأحد أقراصك والذي قد يكون موقعًا على نظام ملفاتك المحلي أو حتى موقع تخزين سحابي مثل Amazon S3.
يقبل التابع <code>store</code> المسار الذي يجب تخزين الملف فيه بالنسبة لمجلّد الجذر (root) المُعد لنظام الملفات. يجب ألّا يحتوي هذا المسار على اسم ملف، نظرًا لأن معرّفًّا فريدًا سيولّد تلقائيًا ليكون بمثابة اسم الملف.

يقبل التابع <code>store</code> أيضًا متغيّرًّا وسيطًا ثانيًا اختياريًّا لاسم القرص الذي يجب تخزين الملف فيه. سيُعيدّ التابع مسار الملف نسبة إلى جذر القرص:<syntaxhighlight lang="php">
$path = $request->photo->store('images');

$path = $request->photo->store('images', 's3');
</syntaxhighlight>إن لم ترغب بإنشاء اسم الملف تلقائيًا تستطيع استخدام التابع <code>storeAs</code> الذي يقبل المسار واسم الملف واسم القرص كوسائطه:<syntaxhighlight lang="php">
$path = $request->photo->storeAs('images', 'filename.jpg');

$path = $request->photo->storeAs('images', 'filename.jpg', 's3');
</syntaxhighlight>

= إعداد الخوادم الوسيطة الموثوقة =
قد تلاحظ أن تطبيقك لا يقوم أحيانًا بإنشاء روابط HTTPS عند تشغيل تطبيقاتك مع مُوازن تحميل يحتوي الشهادات TLS / SSL.سبب ذلك عادة هو تلقّي تطبيقك لإعادة توجيه حركة (traffic) من موازن التحميل على المنفذ 80 دون أن يعرف أن عليه (أي تطبيقك) إنشاء ارتباطات آمنة.

لحل هذه المشكلة، تستطيع استخدام البرمجيّة الوسيطة للتطبيق <code>App\Http\Middleware\TrustProxies</code> المُضمّنة في تطبيق Laravel ممّا يسمح لك بتخصيص مُوازنات الحمل أو الوُكلاء التي على تطبيقك الثقة بها بسرعة. يجب إدراج وكلائك الموثوقين كمصفوفة في الخاصيّة <code>proxies$</code> لهذه البرمجيّة الوسيطة. إضافةً لتهيئة بروكسيات الوُكلاء الموثوقين، تستطيع إعداد الوكيل <code>headers$</code> الذي ينبغي الوثوق به:<syntaxhighlight lang="php">
<?php

namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Fideloper\Proxy\TrustProxies as Middleware;

class TrustProxies extends Middleware
{
    /**
     * الوكلاء الموثوق بهم لهذا التطبيق.
     *
     * @var array
     */
    protected $proxies = [
        '192.168.1.1',
        '192.168.1.2',
    ];

    /**
     * الترويسات التي يجب استخدامها لاكتشاف الوكلاء.
     *
     * @var string
     */
    protected $headers = Request::HEADER_X_FORWARDED_ALL;
}

</syntaxhighlight>'''ملاحظة''': إذا كنت تستخدم AWS Load Balancing، فيجب أن تكون قيمة المتغير <code>‎$headers</code> هي <code>Request::HEADER_X_FORWARDED_AWS_ELB</code>. لمزيد من المعلومات حول الثوابت التي يمكن استخدامها في الخاصيّة <code>‎$headers</code>، تحقق من توثيق Symfony حول الثقة بالوكلاء.

==== الوثوق بجميع الوكلاء ====
إذا كنت تستخدم Amazon AWS أو موفّر آخر لموازنة الحمل "cloud"، فقد لا تعرف العناوين IP لمُوَازناتك الفعلية. تستطيع في هذه الحالة استخدام <code>*</code> للثقة بجميع الوكلاء:

== مصادر ==
* [https://laravel.com/docs/5.6/requests صفحة HTTP requests في توثيق laravel الرسمي]
[[تصنيف:Laravel]]
[[تصنيف:Laravel Basics]]