الفرق بين المراجعتين ل"Laravel/queries"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
ط (استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}')
 
(5 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة)
سطر 1: سطر 1:
 
+
<noinclude>{{DISPLAYTITLE:منشئ الاستعلامات في Laravel}}</noinclude>
<noinclude>{{DISPLAYTITLE:قواعد البيانات: منشئ الاستعلامات}}</noinclude>
+
[[تصنيف:Laravel|{{SUBPAGENAME}}]]
== مقدمة ==
+
[[تصنيف:Laravel Database|{{SUBPAGENAME}}]]
 
+
==مقدمة==
 
يوفّر منشئ استعلامات قاعدة بيانات Laravel واجهة ملائمة وسلسة لإنشاء وإدارة استعلامات قاعدة البيانات. يمكن استخدامه لتنفيذ معظم عمليات قاعدة البيانات بتطبيقك كما أنه يعمل على جميع أنظمة قواعد البيانات المدعومة.
 
يوفّر منشئ استعلامات قاعدة بيانات Laravel واجهة ملائمة وسلسة لإنشاء وإدارة استعلامات قاعدة البيانات. يمكن استخدامه لتنفيذ معظم عمليات قاعدة البيانات بتطبيقك كما أنه يعمل على جميع أنظمة قواعد البيانات المدعومة.
  
 
يستخدم منشئ استعلامات Laravel ارتباط المعاملة PDO لحماية تطبيقك من هجمات حقن SQL. لا حاجة لتنظيف السلاسل النصيّة التي تُمرّر كارتباطات.
 
يستخدم منشئ استعلامات Laravel ارتباط المعاملة PDO لحماية تطبيقك من هجمات حقن SQL. لا حاجة لتنظيف السلاسل النصيّة التي تُمرّر كارتباطات.
 
+
==استرداد النتائج==
== استرداد النتائج ==
+
===استرداد جميع الصفوف من الجدول===
 
 
==== استرداد جميع الصفوف من الجدول ====
 
 
تستطيع استخدام التابع <code>table</code> على الواجهة الساكنة <code>DB</code> لبدء استعلام. يرد التابع <code>table</code> نسخة منشئ استعلامات فصيحة (fluent) للجدول المحدد، ممّا يسمح لك بربط المزيد من القيود بالاستعلام ثم الحصول على النتائج في النهاية باستخدام التابع <code>get</code>:<syntaxhighlight lang="php">
 
تستطيع استخدام التابع <code>table</code> على الواجهة الساكنة <code>DB</code> لبدء استعلام. يرد التابع <code>table</code> نسخة منشئ استعلامات فصيحة (fluent) للجدول المحدد، ممّا يسمح لك بربط المزيد من القيود بالاستعلام ثم الحصول على النتائج في النهاية باستخدام التابع <code>get</code>:<syntaxhighlight lang="php">
 
<?php
 
<?php
سطر 39: سطر 37:
  
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===استرداد صف أو عمود مفرد من جدول===
==== استرداد صف أو عمود مفرد من جدول ====
 
 
تستطيع استخدام التابع <code>first</code> إن احتجت لاسترداد صف واحد فقط  من جدول قاعدة البيانات. سيعيد هذا التابع كائن <code>StdClass</code> واحد:<syntaxhighlight lang="php">
 
تستطيع استخدام التابع <code>first</code> إن احتجت لاسترداد صف واحد فقط  من جدول قاعدة البيانات. سيعيد هذا التابع كائن <code>StdClass</code> واحد:<syntaxhighlight lang="php">
 
$user = DB::table('users')->where('name', 'John')->first();
 
$user = DB::table('users')->where('name', 'John')->first();
سطر 50: سطر 47:
  
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===استرداد قائمة قيم الأعمدة===
==== استرداد قائمة قيم الأعمدة ====
 
 
تستطيع استخدام التابع <code>pluck</code> إن رغبت في استرداد مجموعة تحتوي على قيم عمود واحد. سنسترد في هذا المثال، مجموعة من عناوين الوظائف (roles):<syntaxhighlight lang="php">
 
تستطيع استخدام التابع <code>pluck</code> إن رغبت في استرداد مجموعة تحتوي على قيم عمود واحد. سنسترد في هذا المثال، مجموعة من عناوين الوظائف (roles):<syntaxhighlight lang="php">
 
$titles = DB::table('roles')->pluck('title');
 
$titles = DB::table('roles')->pluck('title');
سطر 67: سطر 63:
  
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===تقسيم النتائج (Chunking Results)===
=== تقسيم النتائج (Chunking Results) ===
 
 
من المُقترح استخدام التابع <code>chunk</code> إن إحتجت للعمل مع الآلاف من سجلات قاعدة البيانات. يعيد هذا التابع جزءًا صغيرًا من النتائج كل مرّة ويعطي كل قطعة لنطاق مغلق Closure للمعالجة. هذا التابع مفيد جدًا في كتابة الأوامر Artisan التي تعالج آلاف السجلات. دعنا نعمل مثلًا مع الجدول users كاملًا لكن على أجزاء من 100 سجل في كل مرّة:<syntaxhighlight lang="php">
 
من المُقترح استخدام التابع <code>chunk</code> إن إحتجت للعمل مع الآلاف من سجلات قاعدة البيانات. يعيد هذا التابع جزءًا صغيرًا من النتائج كل مرّة ويعطي كل قطعة لنطاق مغلق Closure للمعالجة. هذا التابع مفيد جدًا في كتابة الأوامر Artisan التي تعالج آلاف السجلات. دعنا نعمل مثلًا مع الجدول users كاملًا لكن على أجزاء من 100 سجل في كل مرّة:<syntaxhighlight lang="php">
 
DB::table('users')->orderBy('id')->chunk(100, function ($users) {
 
DB::table('users')->orderBy('id')->chunk(100, function ($users) {
سطر 83: سطر 78:
 
});
 
});
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===المجاميع===
=== المجاميع ===
 
 
يوفّر منشئ الاستعلامات أيضًا مجموعة متنوعة من التوابع التجميعية (aggregate methods) مثل <code>count</code>، و <code>max</code>، و <code>min</code>، و <code>avg</code>، و <code>sum</code>. تستطيع مناداة أي من هذه التوابع بعد إنشاء استعلامك:<syntaxhighlight lang="php">
 
يوفّر منشئ الاستعلامات أيضًا مجموعة متنوعة من التوابع التجميعية (aggregate methods) مثل <code>count</code>، و <code>max</code>، و <code>min</code>، و <code>avg</code>، و <code>sum</code>. تستطيع مناداة أي من هذه التوابع بعد إنشاء استعلامك:<syntaxhighlight lang="php">
 
$users = DB::table('users')->count();
 
$users = DB::table('users')->count();
سطر 95: سطر 89:
 
                 ->avg('price');
 
                 ->avg('price');
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
====تحديد ما إذا كانت السجلات موجودة====
==== تحديد ما إذا كانت السجلات موجودة ====
 
 
تستطيع استخدام الأساليب <code>exists</code> و <code>doesntExist</code> بدل استخدام التابع <code>count</code> لتحديد ما إذا طابقت أية سجلات قيود استعلامك:<syntaxhighlight lang="php">
 
تستطيع استخدام الأساليب <code>exists</code> و <code>doesntExist</code> بدل استخدام التابع <code>count</code> لتحديد ما إذا طابقت أية سجلات قيود استعلامك:<syntaxhighlight lang="php">
 
return DB::table('orders')->where('finalized', 1)->exists();
 
return DB::table('orders')->where('finalized', 1)->exists();
سطر 103: سطر 96:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
==معاملات عرض السجلّات Selects==
 
==معاملات عرض السجلّات Selects==
====تحديد بند Select====
+
===تحديد بند <code>Select</code>===
 
قد لا ترغب دائمًا طبعًا في تحديد (select) كافة الأعمدة من جدول قاعدة البيانات. تستطيع تحديد بند select مُخصّص للاستعلام باستخدام التابع <code>select</code>:<syntaxhighlight lang="php">
 
قد لا ترغب دائمًا طبعًا في تحديد (select) كافة الأعمدة من جدول قاعدة البيانات. تستطيع تحديد بند select مُخصّص للاستعلام باستخدام التابع <code>select</code>:<syntaxhighlight lang="php">
 
$users = DB::table('users')->select('name', 'email as user_email')->get();
 
$users = DB::table('users')->select('name', 'email as user_email')->get();
سطر 116: سطر 109:
  
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
==تعبيرات خام==
== تعبيرات خام ==
 
 
قد تحتاج في بعض الأحيان لاستخدام تعبير خام في استعلام. تستطيع استخدام التابع <code>DB::raw</code> لإنشاء تعبير خام:<syntaxhighlight lang="php">
 
قد تحتاج في بعض الأحيان لاستخدام تعبير خام في استعلام. تستطيع استخدام التابع <code>DB::raw</code> لإنشاء تعبير خام:<syntaxhighlight lang="php">
 
$users = DB::table('users')
 
$users = DB::table('users')
سطر 125: سطر 117:
 
                     ->get();
 
                     ->get();
 
</syntaxhighlight>ملاحظة: ستُضاف التعابير الخامة للاستعلام كسلاسل نصيّة لذا عليك التزام الحذر الشديد كيلا تخلق نقاط ضعف حُقن SQL.
 
</syntaxhighlight>ملاحظة: ستُضاف التعابير الخامة للاستعلام كسلاسل نصيّة لذا عليك التزام الحذر الشديد كيلا تخلق نقاط ضعف حُقن SQL.
 
+
===التوابع الخامة===
=== التوابع الخامة ===
 
 
تستطيع أيضًا استخدام التوابع التالية بدلاً من استخدام <code>DB::raw</code> لإدراج تعبير خام في أجزاء مختلفة من استعلامك.
 
تستطيع أيضًا استخدام التوابع التالية بدلاً من استخدام <code>DB::raw</code> لإدراج تعبير خام في أجزاء مختلفة من استعلامك.
 
+
====<code>selectRaw</code>====
==== selectRaw ====
 
 
يمكن استخدام التابع <code>selectRaw</code> بدلاً من <code>select(DB::raw(...))‎</code>. يقبل هذا التابع مصفوفةً اختياريّةً من الارتباطات كمتغيّر وسيط ثاني لها:<syntaxhighlight lang="php">
 
يمكن استخدام التابع <code>selectRaw</code> بدلاً من <code>select(DB::raw(...))‎</code>. يقبل هذا التابع مصفوفةً اختياريّةً من الارتباطات كمتغيّر وسيط ثاني لها:<syntaxhighlight lang="php">
 
$orders = DB::table('orders')
 
$orders = DB::table('orders')
سطر 136: سطر 126:
  
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
====<code>whereRaw</code> / <code>orWhereRaw</code>====
==== whereRaw / orWhereRaw ====
 
 
<code>whereRaw</code> و <code>orWhereRaw</code> هما تابعان يمكن استخدامها لإضافة بند <code>where</code> خام لاستعلامك. تقبل هذه التوابع مصفوفة اختياريّة من الارتباطات كمتغيّر وسيط ثاني لها:<syntaxhighlight lang="php">
 
<code>whereRaw</code> و <code>orWhereRaw</code> هما تابعان يمكن استخدامها لإضافة بند <code>where</code> خام لاستعلامك. تقبل هذه التوابع مصفوفة اختياريّة من الارتباطات كمتغيّر وسيط ثاني لها:<syntaxhighlight lang="php">
 
$orders = DB::table('orders')
 
$orders = DB::table('orders')
سطر 143: سطر 132:
 
                 ->get();
 
                 ->get();
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
====<code>havingRaw</code> / <code>orHavingRaw</code>====
==== havingRaw / orHavingRaw ====
 
 
<code>havingRaw</code> و <code>orHavingRaw</code> هما تابعان يمكن استخدامها لتعيين سلسلة نصيّة خام كقيمة البند having. تقبل هذه التوابع مصفوفة اختيارية من الارتباطات كمتغيّر وسيط ثاني لها:<syntaxhighlight lang="php">
 
<code>havingRaw</code> و <code>orHavingRaw</code> هما تابعان يمكن استخدامها لتعيين سلسلة نصيّة خام كقيمة البند having. تقبل هذه التوابع مصفوفة اختيارية من الارتباطات كمتغيّر وسيط ثاني لها:<syntaxhighlight lang="php">
 
$orders = DB::table('orders')
 
$orders = DB::table('orders')
سطر 152: سطر 140:
 
                 ->get();
 
                 ->get();
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
====<code>orderByRaw</code>====
==== orderByRaw ====
 
 
يمكن استخدام التابع <code>orderByRaw</code> لتعيين سلسلة نصيّة خامة كقيمة البند order by:<syntaxhighlight lang="php">
 
يمكن استخدام التابع <code>orderByRaw</code> لتعيين سلسلة نصيّة خامة كقيمة البند order by:<syntaxhighlight lang="php">
 
$orders = DB::table('orders')
 
$orders = DB::table('orders')
سطر 159: سطر 146:
 
                 ->get();
 
                 ->get();
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
==معاملات ربط الجداول Joins==
== معاملات ربط الجداول Joins ==
+
===بند الربط الداخلي (Inner Join Clause)===
 
 
==== بند الربط الداخلي (Inner Join Clause) ====
 
 
يمكن استخدام منشئ الاستعلامات لكتابة تعابير الربط (join statements). لإجراء "ربط داخلي" بسيط، تستطيع استخدام التابع <code>join</code> على نسخة منشئ استعلامات. أوّل متغيّر وسيط يُمرّر إلى التابع <code>join</code> هو اسم الجدول الذي تحتاج للربط به في حين أن المُغيّرات الباقية تحدد قيود العمود للربط. تستطيع كما ترى الربط بعدّة جداول في استعلام واحد:<syntaxhighlight lang="php">
 
يمكن استخدام منشئ الاستعلامات لكتابة تعابير الربط (join statements). لإجراء "ربط داخلي" بسيط، تستطيع استخدام التابع <code>join</code> على نسخة منشئ استعلامات. أوّل متغيّر وسيط يُمرّر إلى التابع <code>join</code> هو اسم الجدول الذي تحتاج للربط به في حين أن المُغيّرات الباقية تحدد قيود العمود للربط. تستطيع كما ترى الربط بعدّة جداول في استعلام واحد:<syntaxhighlight lang="php">
 
$users = DB::table('users')
 
$users = DB::table('users')
سطر 170: سطر 155:
 
             ->get();
 
             ->get();
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===بند الربط اليساري (Left Join Clause)===
==== بند الربط اليساري (Left Join Clause) ====
 
 
إن رغبت في عمل "ربط يساري" بدلاً من "ربط داخلي"، استخدم التابع <code>leftJoin</code>. يملك التابع <code>leftJoin</code> نفس توقيع التابع <code>join</code>:<syntaxhighlight lang="php">
 
إن رغبت في عمل "ربط يساري" بدلاً من "ربط داخلي"، استخدم التابع <code>leftJoin</code>. يملك التابع <code>leftJoin</code> نفس توقيع التابع <code>join</code>:<syntaxhighlight lang="php">
 
$users = DB::table('users')
 
$users = DB::table('users')
سطر 177: سطر 161:
 
             ->get();
 
             ->get();
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===بند الربط المُتقاطع (Cross Join Clause)===
==== بند الربط المُتقاطع (Cross Join Clause) ====
 
 
لعمل "ربط مُتقاطع"، استخدم التابع <code>crossJoin</code> مع اسم الجدول الذي ترغب في الربط به. يولّد الربط المُتقاطع نتيجة ديكارتيّة بين الجدول الأول والجدول المربوط:<syntaxhighlight lang="php">
 
لعمل "ربط مُتقاطع"، استخدم التابع <code>crossJoin</code> مع اسم الجدول الذي ترغب في الربط به. يولّد الربط المُتقاطع نتيجة ديكارتيّة بين الجدول الأول والجدول المربوط:<syntaxhighlight lang="php">
 
$users = DB::table('sizes')
 
$users = DB::table('sizes')
سطر 184: سطر 167:
 
             ->get();
 
             ->get();
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
===بنود الربط المتقدّمة===
==== بنود الربط المتقدّمة ====
+
تستطيع أيضًا تحديد شروط ربط أكثر تقّدمًا. للبدء، مرّر Closure كالمتغيّر الوسيط الثاني في التابع <code>join</code>. سيتلقّى Closure كائن <code>JoinClause</code> والذي يسمح لك بتحديد القيود على البند <code>join</code>:<syntaxhighlight lang="php">
تستطيع أيضًا تحديد شروط ربط أكثر تقّدمًا. للبدء، مرّر Closure كالمتغيّر الوسيط الثاني في التابع <code>join</code>. سيتلقّى Closure كائن <code>JoinClause</code> والذي يسمح لك بتحديد القيود على البند join:<syntaxhighlight lang="php">
 
 
DB::table('users')
 
DB::table('users')
 
         ->join('contacts', function ($join) {
 
         ->join('contacts', function ($join) {
سطر 199: سطر 181:
 
         })
 
         })
 
         ->get();
 
         ->get();
 +
 +
</syntaxhighlight>
 +
===ربط الاستعلام الفرعي ( Sub-Query Joins)===
 +
تستطيع استخدام التوابع  <code>joinSub</code> <code>leftJoinSub</code> و <code>rightJoinSub</code> و <code>rightJoinSub</code> لربط استعلام باستعلام فرعي. يتلقى كل تابع من هذه التوابع ثلاث مُتغيّرات وسيطة: الاستعلام الفرعي، واسم جدولها المستعار (table alias)، ونطاق مغلق يحدّد الأعمدة ذات الصلة:<syntaxhighlight lang="php">
 +
$latestPosts = DB::table('posts')
 +
                  ->select('user_id', DB::raw('MAX(created_at) as last_post_created_at'))
 +
                  ->where('is_published', true)
 +
                  ->groupBy('user_id');
 +
 +
$users = DB::table('users')
 +
        ->joinSub($latestPosts, 'latest_posts', function($join) {
 +
            $join->on('users.id', '=', 'latest_posts.user_id');
 +
        })->get();
 +
</syntaxhighlight>
 +
 +
== معاملات الدمج Unions ==
 +
يُوفّر منشئ الاستعلامات أيضًا طريقة سريعة "لدمج" استعلامين معًا. تستطيع مثلًا إنشاء استعلام الأولي ثم استخدام التابع <code>union</code> لدمجه باستعلام الثاني:<syntaxhighlight lang="php">
 +
$first = DB::table('users')
 +
            ->whereNull('first_name');
 +
 +
$users = DB::table('users')
 +
            ->whereNull('last_name')
 +
            ->union($first)
 +
            ->get();
 +
</syntaxhighlight>ملاحظة: يوجد أيضًا التابع <code>unionAll</code> وله نفس إمضاء التابع <code>union</code>.
 +
 +
== البنود Where ==
 +
 +
=== بنود <code>Where</code> البسيطة ===
 +
تستطيع استخدام التابع <code>where</code> على نسخة منشئ استعلامات لإضافة بنود <code>where</code> للاستعلام. يتطلب أبسط نداء <code>where</code> ثلاث وسائط. المتغيّر الوسيط الأول هو اسم العمود. المتغيّر الوسيط الثاني هو المُعامل (operator)، والذي يمكن أن يكون أي من المُعاملين المعتمدين في قاعدة البيانات. وأخيرًا يكون المتغيّر الوسيط الثالث هو القيمة التي تُقيّم حسب العمود.
 +
 +
تجد هنا مثلًا استعلامًا يتحقّق من مساواة قيمة العمود "votes" للعدد 100:<syntaxhighlight lang="php">
 +
$users = DB::table('users')->where('votes', '=', 100)->get();
 +
 +
</syntaxhighlight>إن أردت التحقّق من مساواة عمود ما لقيمة معيّنة تستطيع ببساطة تمرير القيمة مباشرة كالمُتغيّر الثاني بالتابع <code>where</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')->where('votes', 100)->get();
 +
 +
</syntaxhighlight>تستطيع طبعًا استخدام عدّة مُعاملين آخرين عند كتابة الشرط where:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->where('votes', '>=', 100)
 +
                ->get();
 +
 +
$users = DB::table('users')
 +
                ->where('votes', '<>', 100)
 +
                ->get();
 +
 +
$users = DB::table('users')
 +
                ->where('name', 'like', 'T%')
 +
                ->get();
 +
</syntaxhighlight>تستطيع أيضًا تمرير مصفوفة من الشروط للتابع <code>where</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')->where([
 +
    ['status', '=', '1'],
 +
    ['subscribed', '<>', '1'],
 +
])->get();
 +
 +
</syntaxhighlight>
 +
 +
=== العبارات <code>Or</code> ===
 +
تستطيع ربط قيود <code>where</code> معًا كما تستطيع إضافةً بنود <code>or</code> للاستعلام. يقبل التابع <code>orWhere</code> نفس المُتغيّرات الوسيطة كالتابع <code>where</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->where('votes', '>', 100)
 +
                    ->orWhere('name', 'John')
 +
                    ->get();
 +
 +
 +
</syntaxhighlight>
 +
 +
=== بنود <code>Where</code> إضاقيّة ===
 +
 +
==== <code>whereBetween</code> ====
 +
يتحقّق التابع من كون قيمة العمود بين قيمتين:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->whereBetween('votes', [1, 100])->get();
 +
</syntaxhighlight>
 +
 +
==== <code>whereNotBetween</code> ====
 +
يتحقّق التابع من كون قيمة العمود خارج قيمتين:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->whereNotBetween('votes', [1, 100])
 +
                    ->get();
 +
</syntaxhighlight>
 +
 +
==== <code>whereIn</code> / <code>whereNotIn</code> ====
 +
يتحقق التابع <code>whereIn</code> من وجود قيمة العمود المحدّد داخل المصفوفة المحدّدة:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->whereIn('id', [1, 2, 3])
 +
                    ->get();
 +
</syntaxhighlight>يتحقق التابع <code>whereNotIn</code> من عدم وجود قيمة العمود المحدّد داخل المصفوفة المحدّدة:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->whereNotIn('id', [1, 2, 3])
 +
                    ->get();
 +
</syntaxhighlight>
 +
 +
==== <code>whereNull</code> / <code>whereNotNull</code> ====
 +
يتحقق التابع <code>whereNull</code> من كون قيمة العمود المحدّدة <code>NULL</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->whereNull('updated_at')
 +
                    ->get();
 +
</syntaxhighlight>يتحقق التابع <code>whereNotNull</code> من عدم كون قيمة العمود المحدّدة <code>NULL</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                    ->whereNotNull('updated_at')
 +
                    ->get();
 +
</syntaxhighlight>
 +
 +
==== <code>whereDate</code> / <code>whereMonth</code> / <code>whereDay</code> / <code>whereYear</code> / <code>whereTime</code> ====
 +
يمكن استخدام التابع <code>whereDate</code> لمقارنة قيمة العمود بتاريخ ما:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereDate('created_at', '2016-12-31')
 +
                ->get();
 +
</syntaxhighlight>يمكن استخدام التابع <code>whereMonth</code> لمقارنة قيمة العمود بشهر مُعيّن من السنة:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereMonth('created_at', '12')
 +
                ->get();
 +
</syntaxhighlight>يمكن استخدام التابع <code>whereDay</code> لمقارنة قيمة العمود بيوم معيّن من الشهر:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereDay('created_at', '31')
 +
                ->get();
 +
</syntaxhighlight>يمكن استخدام التابع <code>whereTime</code> لمقارنة قيمة العمود بتوقيت معيّن:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereTime('created_at', '=', '11:20:45')
 +
                ->get();
 +
</syntaxhighlight>
 +
 +
==== <code>whereColumn</code> ====
 +
يمكن استخدام التابع <code>whereColumn</code> للتحقق من تساوي عمودين:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereColumn('first_name', 'last_name')
 +
                ->get();
 +
</syntaxhighlight>تستطيع أيضًا تمرير عامل مقارنة (comparison operator) للتابع:<syntaxhighlight lang="php">
 +
users = DB::table('users')
 +
                ->whereColumn('updated_at', '>', 'created_at')
 +
                ->get();
 +
</syntaxhighlight>يمكن أيضاً تمرير مصفوفة من عدّة شروط للتابع <code>whereColumn</code>. ستُضمّ هذه الشروط باستخدام المعامل and:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereColumn([
 +
['first_name', '=', 'last_name'],
 +
                    ['updated_at', '>', 'created_at']
 +
                ])->get();
 +
</syntaxhighlight>
 +
 +
=== تجميع المعاملات (Parameter Grouping) ===
 +
قد تحتاج أحياناً لإنشاء بنود <code>where</code> متطوّرة أكثر حيث توجد عبارات مثل "where exists" أو معاملات تجميع متداخلة (nested parameter groupings). يستطيع منشئ الاستعلامات Laravel التعامل معها أيضًا. دعنا نلق نظرة على مثال على قيود التجميع بين قوسين للبدء:<syntaxhighlight lang="php">
 +
DB::table('users')
 +
            ->where('name', '=', 'John')
 +
            ->where(function ($query) {
 +
                $query->where('votes', '>', 100)
 +
                      ->orWhere('title', '=', 'Admin');
 +
            })
 +
            ->get();
 +
</syntaxhighlight>يأمر تمرير Closure للتابع <code>where</code> منشئ الاستعلامات ببدء مجموعة قيود. سيتلقى Closure نسخة منشئ استعلامات تستطيع استخدامها لتحديد القيود التي يجب احتواؤها داخل مجموعة القوسين. سينتج المثال أعلاه SQL التالي:<syntaxhighlight lang="sql">
 +
 +
select * from users where name = 'John' and (votes > 100 or title = 'Admin')
 +
 +
</syntaxhighlight>ملاحظة: يجب دائمًا تجميع نداءات <code>orWhere</code> تجنّبًا لحدوث سلوك غير متوقع عند تطبيق النطاقات العامة.
 +
 +
=== البنود Where <code>Exists</code> ===
 +
يسمح لك التابع <code>whereExists</code> بكتابة العبارات <code>whereexists</code> SQL. يقبل التابع <code>whereExists</code> متغيّر وسيط Closure والذي سيتلقّى نسخة منشئ الاستعلامات ممّا يسمح لك بتعريف الاستعلام الذي يجب وضعه داخل البند "exists":<syntaxhighlight lang="php">
 +
DB::table('users')
 +
            ->whereExists(function ($query) {
 +
                $query->select(DB::raw(1))
 +
                      ->from('orders')
 +
                      ->whereRaw('orders.user_id = users.id');
 +
            })
 +
            ->get();
 +
</syntaxhighlight>سينتج الاستعلام أعلاه SQL التالي:<syntaxhighlight lang="sql">
 +
select * from users
 +
where exists (
 +
    select 1 from orders where orders.user_id = users.id
 +
)
 +
 +
</syntaxhighlight>
 +
 +
=== البنود JSON Where ===
 +
يدعم Laravel أيضًا الاستعلام عن أنواع الأعمدة JSON بقواعد البيانات التي تدعم أنواع الأعمدة JSON. يتضمّن هذا حاليًّا MySQL 5.7 و PostgreSQL و SQL Server 2016 و SQLite 3.9.0 (مع ملحق JSON1). للاستعلام عن عمود JSON ، استخدم عامل التشغيل ‎<code>-></code>‎:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->where('options->language', 'en')
 +
                ->get();
 +
 +
$users = DB::table('users')
 +
                ->where('preferences->dining->meal', 'salad')
 +
                ->get();
 +
</syntaxhighlight>يدعم [[MySQL]] و [[PostgreSQL]] عدّة قيم من <code>whereJsonContains</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->whereJsonContains('options->languages', ['en', 'de'])
 +
                ->get();
 +
</syntaxhighlight>
 +
 +
== الترتيب والتجميع والحد والإزاحة ==
 +
 +
=== <code>orderBy</code> ===
 +
يتيح لك التابع فرز نتائج الاستعلام حسب عمود محدّد. يجب أن يكون متغيّر التابع <code>orderBy</code> الوسيط الأول هو العمود الذي تريد الفرز حسبه بينما يتحكّم المتغيّر الوسيط الثاني في اتجاه الفرز وقد تكون إمّا <code>asc</code> أو <code>desc</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->orderBy('name', 'desc')
 +
                ->get();
 +
</syntaxhighlight>
 +
 +
=== <code>latest</code> / <code>oldest</code> ===
 +
يسمح لك التابعان بترتيب النتائج حسب التاريخ بسهولة. تُرتّب النتيجة افتراضيًّا حسب العمود <code>created_at</code>. أو تستطيع تمرير اسم العمود الذي تريد الترتيب وفقًا له:<syntaxhighlight lang="php">
 +
$user = DB::table('users')
 +
                ->latest()
 +
                ->first();
 +
</syntaxhighlight>
 +
 +
=== <code>inRandomOrder</code> ===
 +
يُمكن استخدام التابع لفرز نتائج الاستعلام عشوائيًّا. تستطيع مثلًا استخدام هذا التابع لجلب مستخدم عشوائي:<syntaxhighlight lang="php">
 +
$randomUser = DB::table('users')
 +
                ->inRandomOrder()
 +
                ->first();
 +
</syntaxhighlight>
 +
 +
=== <code>groupBy</code> / <code>having</code> ===
 +
يمكن استخدام التابعين لتجميع نتائج الاستعلام. يُشابه توقيع التابع <code>having</code> توقيع التابع <code>where</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->groupBy('account_id')
 +
                ->having('account_id', '>', 100)
 +
                ->get();
 +
</syntaxhighlight>تستطيع تمرير عدّة مُتغيّرات وسيطة للتابع <code>groupBy</code> لتجميع عدّة أعمدة:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->groupBy('first_name', 'status')
 +
                ->having('account_id', '>', 100)
 +
                ->get();
 +
</syntaxhighlight>لمزيد من المعلومات حول عبارات <code>having</code> أكثر تطوّرًا راجع التابع <code>havingRaw</code>.
 +
 +
=== <code>skip</code> / <code>take</code> ===
 +
للحد من عدد من النتائج التي يردّها الاستعلام، أو لتخطّي عدد معيّن من النتائج في الاستعلام، تستطيع استخدام التابعين <code>skip</code> و <code>take</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')->skip(10)->take(5)->get();
 +
 +
</syntaxhighlight>تستطيع كبديل استخدام التابعين <code>limit</code> و <code>offset</code>:<syntaxhighlight lang="php">
 +
$users = DB::table('users')
 +
                ->offset(10)
 +
                ->limit(5)
 +
                ->get();
 +
</syntaxhighlight>
 +
 +
== البنود المشروطة (Conditional Clauses) ==
 +
قد ترغب أحيانًا في تطبيق بنود ما على الاستعلام فقط عندما تكون قيمة شيء آخر <code>true</code>. قد ترغب مثلًا بتطبيق عبارة <code>where</code> فقط إن كانت قيمة إدخال معيّنة موجودة في الطلب الوارد. تقدر على فعل هذا باستخدام التابع <code>when</code>:<syntaxhighlight lang="php">
 +
$role = $request->input('role');
 +
 +
$users = DB::table('users')
 +
                ->when($role, function ($query, $role) {
 +
                    return $query->where('role_id', $role);
 +
                })
 +
                ->get();
 +
</syntaxhighlight>يُنفّذ التابع <code>when</code> النطاق المُغلق المحدّد Closure فقط عندما تكون المعاملة الأولى true. في حالة كانت المعاملة الأولى false لن يُنفّذ النطاق المغلق Closure.
 +
 +
تستطيع تمرير نطاق مُغلق Closure آخر كثالث معامل للتابع <code>when</code>. سيُنفّذ هذا النطاق المُغلق في حالة كانت المعاملة الأولى false. لتوضيح كيفيّة استخدام هذه الميزة سنستخدمها لاعداد الفرز الافتراضي لاستعلام:<syntaxhighlight lang="php">
 +
$sortBy = null;
 +
 +
$users = DB::table('users')
 +
                ->when($sortBy, function ($query, $sortBy) {
 +
                    return $query->orderBy($sortBy);
 +
                }, function ($query) {
 +
                    return $query->orderBy('name');
 +
                })
 +
                ->get();
 +
</syntaxhighlight>
 +
 +
== إدخالات السجلّات للجدول Inserts ==
 +
يوفّر منشئ الاستعلامات أيضا تابع <code>insert</code> لإدراج السجلّات في جدول قاعدة البيانات. يقبل التابع <code>insert</code> مصفوفةً من أسماء الأعمدة وقيمها:<syntaxhighlight lang="php">
 +
DB::table('users')->insert(
 +
    ['email' => '[email protected]', 'votes' => 0]
 +
);
 +
 +
</syntaxhighlight>تستطيع حتى إدراج عدة سجلّات في الجدول بنداء insert واحد عن طريق تمرير مصفوفة من المصفوفات. تمثّل كل مصفوفة صفًا سيُدرج في الجدول:<syntaxhighlight lang="php">
 +
DB::table('users')->insert([
 +
    ['email' => '[email protected]com', 'votes' => 0],
 +
    ['email' => '[email protected]', 'votes' => 0]
 +
]);
 +
 +
</syntaxhighlight>
 +
 +
=== المُعرّفات تلقائيّة الزيادة (Auto-Incrementing IDs) ===
 +
استخدم التابعين <code>insertGetId</code> و <code>insertGetId</code> إذا احتوى الجدول على معرّف تلقائي الزيادة لإدراج سجلّ ثم استرد الُمعرّف:<syntaxhighlight lang="php">
 +
$id = DB::table('users')->insertGetId(
 +
    ['email' => '[email protected]', 'votes' => 0]
 +
);
 +
 +
</syntaxhighlight>'''ملاحظة''': عند استخدام ،PostgreSQL يتوقّع التابع <code>insertGetId</code> تسمية عمود الزيادة التلقائية باسم <code>id</code>. تستطيع تمرير اسم العمود كمعاملة ثانية للتابع <code>insertGetId</code> إن رغبت باسترداد المعرّف من "تسلسل" مختلف.
 +
 +
== التحديثات Updates ==
 +
يستطيع منشئ الاستعلامات أيضًا تحديث السجلات الموجودة باستخدام التابع <code>update</code> إضافةً لإدخال السجلات في قاعدة البيانات. يقبل التابع <code>update</code>، مثل التابع <code>insert</code>، مصفوفة من أزواج الأعمدة والقيم التي تحتوي على الأعمدة المُراد تحديثها. تستطيع تقييد استعلام update باستخدام بنود where:<syntaxhighlight lang="php">
 +
DB::table('users')
 +
            ->where('id', 1)
 +
            ->update(['votes' => 1]);
 +
</syntaxhighlight>
 +
 +
=== تحديث أعمدة JSON ===
 +
يجب استخدام الصيغة -> عند تحديث عمود JSON للوصول للمفتاح المناسب في الكائن JSON. هذه العملية مدعومة فقط على MySQL 5.7+‎:<syntaxhighlight lang="php">
 +
DB::table('users')
 +
            ->where('id', 1)
 +
            ->update(['options->enabled' => true]);
 +
</syntaxhighlight>
 +
 +
=== الزيادة والنقصان ===
 +
يوفّر منشئ الاستعلامات أيضًا توابع ملائمة لزيادة قيمة العمود المُحدّد أو انقاصها. هذا اختصار يوفّر واجهة أكثر تعبيرًا واقتضابًا مقارنة بكتابة العبارة <code>update</code> يدويًا.
 +
 +
يقبل كلا التابعين متغيّر وسيط واحد على الأقل: العمود المُراد تعديله. قد يُمرّر متغيّر وسيط ثاني اختياريًا للتحكّم في مقدار زيادة العمود أو تنقيصه:<syntaxhighlight lang="php">
 +
DB::table('users')->increment('votes');
 +
 +
DB::table('users')->increment('votes', 5);
 +
 +
DB::table('users')->decrement('votes');
 +
 +
DB::table('users')->decrement('votes', 5);
 +
 +
</syntaxhighlight>تستطيع أيضًا تحديد أعمدة إضافيّة لتحديثها أثناء العملية:<syntaxhighlight lang="php">
 +
DB::table('users')->increment('votes', 1, ['name' => 'John']);
 +
 +
</syntaxhighlight>
 +
 +
== الحذف Deletes ==
 +
يمكن أيضًا استخدام منشئ الاستعلامات لحذف السجلات من الجدول عبر التابع <code>delete</code>. تستطيع تقييد العبارات <code>delete</code> بإضافة بنود where قبل مناداة التابع <code>delete</code>:<syntaxhighlight lang="php">
 +
DB::table('users')->delete();
 +
 +
DB::table('users')->where('votes', '>', 100)->delete();
 +
 +
</syntaxhighlight>تستطيع استخدام التابع <code>truncate</code> إن رغبت في اقتطاع الجدول بأكمله، ممّا سيؤدي لإزالة جميع الصفوف وإعادة المُعرّف تلقائي الزيادة للصفر:<syntaxhighlight lang="php">
 +
DB::table('users')->truncate();
 +
 +
</syntaxhighlight>
 +
 +
== «الإقفال المتشائم» (Pessimistic Locking) ==
 +
ويشمل منشئ الاستعلامات أيضًا عددًا صغيرًا من الدوال لمساعدتك على "الإقفال المتشائم" بعباراتك select. تستطيع استخدام التابع <code>sharedLock</code> في الاستعلام لتشغيل العبارة باستخدام "قفل مشترك". يمنع القفل المشترك تعديل الصفوف المحدّدة حتى تنفيذ (commit) معاملتك:<syntaxhighlight lang="php">
 +
 +
DB::table('users')->where('votes', '>', 100)->sharedLock()->get();
 +
 +
</syntaxhighlight>تستطيع استخدام التابع <code>lockForUpdate</code> كبديل. يمنع قفل "للتحديث" (for update) تعديل الصفوف أو تحديدها باستخدام قفل مشترك آخر:<syntaxhighlight lang="php">
 +
 +
DB::table('users')->where('votes', '>', 100)->lockForUpdate()->get();
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== ربط الاستعلام الفرعي ( Sub-Query Joins) ====
+
== مصادر ==
تستطيع استخدام التوابع  <code>joinSub</code> <code>leftJoinSub</code> و <code>rightJoinSub</code> و <code>rightJoinSub</code> لربط استعلام باستعلام فرعي. يتلقى كل تابع من هذه التوابع ثلاث مُتغيّرات وسيطة: الاستعلام الفرعي، واسم جدولها المستعار (table alias)، ونطاق مغلق يحدّد الأعمدة ذات الصلة:
+
* [https://laravel.com/docs/5.6/queries صفحة Database: Query Builder في توثيق Laravel الرسمي.]

المراجعة الحالية بتاريخ 13:25، 23 أكتوبر 2018

مقدمة

يوفّر منشئ استعلامات قاعدة بيانات Laravel واجهة ملائمة وسلسة لإنشاء وإدارة استعلامات قاعدة البيانات. يمكن استخدامه لتنفيذ معظم عمليات قاعدة البيانات بتطبيقك كما أنه يعمل على جميع أنظمة قواعد البيانات المدعومة.

يستخدم منشئ استعلامات Laravel ارتباط المعاملة PDO لحماية تطبيقك من هجمات حقن SQL. لا حاجة لتنظيف السلاسل النصيّة التي تُمرّر كارتباطات.

استرداد النتائج

استرداد جميع الصفوف من الجدول

تستطيع استخدام التابع table على الواجهة الساكنة DB لبدء استعلام. يرد التابع table نسخة منشئ استعلامات فصيحة (fluent) للجدول المحدد، ممّا يسمح لك بربط المزيد من القيود بالاستعلام ثم الحصول على النتائج في النهاية باستخدام التابع get:

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * عرض قائمة كل مستخدمي التطبيق.
     *
     * @return Response
     */
    public function index()
    {
        $users = DB::table('users')->get();

        return view('user.index', ['users' => $users]);
    }
}

يعيد التابع get الملف Illuminate\Support\Collection الذي يحتوي على النتائج بحيث تكون كل نتيجة نسخة من الكائن PHP StdClass. تستطيع الوصول لقيمة كل عمود عن طريق الوصول للعمود كخاصية للكائن:

foreach ($users as $user) {
    echo $user->name;
}

استرداد صف أو عمود مفرد من جدول

تستطيع استخدام التابع first إن احتجت لاسترداد صف واحد فقط  من جدول قاعدة البيانات. سيعيد هذا التابع كائن StdClass واحد:

$user = DB::table('users')->where('name', 'John')->first();

echo $user->name;

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

$email = DB::table('users')->where('name', 'John')->value('email');

استرداد قائمة قيم الأعمدة

تستطيع استخدام التابع pluck إن رغبت في استرداد مجموعة تحتوي على قيم عمود واحد. سنسترد في هذا المثال، مجموعة من عناوين الوظائف (roles):

$titles = DB::table('roles')->pluck('title');

foreach ($titles as $title) {
    echo $title;
}

تستطيع أيضًا تحديد عمود مفاتيح مخصصّة للمجموعة المردودة:

$roles = DB::table('roles')->pluck('title', 'name');

foreach ($roles as $name => $title) {
    echo $title;
}

تقسيم النتائج (Chunking Results)

من المُقترح استخدام التابع chunk إن إحتجت للعمل مع الآلاف من سجلات قاعدة البيانات. يعيد هذا التابع جزءًا صغيرًا من النتائج كل مرّة ويعطي كل قطعة لنطاق مغلق Closure للمعالجة. هذا التابع مفيد جدًا في كتابة الأوامر Artisan التي تعالج آلاف السجلات. دعنا نعمل مثلًا مع الجدول users كاملًا لكن على أجزاء من 100 سجل في كل مرّة:

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    foreach ($users as $user) {
        //
    }
});

تستطيع إيقاف معالجة قطع أخرى عبر رد القيمة false من Closure:

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    // عالج السجلات...

    return false;
});

المجاميع

يوفّر منشئ الاستعلامات أيضًا مجموعة متنوعة من التوابع التجميعية (aggregate methods) مثل count، و max، و min، و avg، و sum. تستطيع مناداة أي من هذه التوابع بعد إنشاء استعلامك:

$users = DB::table('users')->count();

$price = DB::table('orders')->max('price');

تستطيع طبعًا دمج هذه التوابع مع بنود أخرى:

$price = DB::table('orders')
                ->where('finalized', 1)
                ->avg('price');

تحديد ما إذا كانت السجلات موجودة

تستطيع استخدام الأساليب exists و doesntExist بدل استخدام التابع count لتحديد ما إذا طابقت أية سجلات قيود استعلامك:

return DB::table('orders')->where('finalized', 1)->exists();

return DB::table('orders')->where('finalized', 1)->doesntExist();

معاملات عرض السجلّات Selects

تحديد بند Select

قد لا ترغب دائمًا طبعًا في تحديد (select) كافة الأعمدة من جدول قاعدة البيانات. تستطيع تحديد بند select مُخصّص للاستعلام باستخدام التابع select:

$users = DB::table('users')->select('name', 'email as user_email')->get();

يسمح لك التابع distinct باجبار الاستعلام على ردّ النتائج الفريدة:

$users = DB::table('users')->distinct()->get();

تستطيع استخدام التابع addSelect إن كان لديك نسخة منشئ استعلامات مسبقًا ورغبت في إضافة عمود آخر لعموده Select الحالي:

$query = DB::table('users')->select('name');

$users = $query->addSelect('age')->get();

تعبيرات خام

قد تحتاج في بعض الأحيان لاستخدام تعبير خام في استعلام. تستطيع استخدام التابع DB::raw لإنشاء تعبير خام:

$users = DB::table('users')
                     ->select(DB::raw('count(*) as user_count, status'))
                     ->where('status', '<>', 1)
                     ->groupBy('status')
                     ->get();

ملاحظة: ستُضاف التعابير الخامة للاستعلام كسلاسل نصيّة لذا عليك التزام الحذر الشديد كيلا تخلق نقاط ضعف حُقن SQL.

التوابع الخامة

تستطيع أيضًا استخدام التوابع التالية بدلاً من استخدام DB::raw لإدراج تعبير خام في أجزاء مختلفة من استعلامك.

selectRaw

يمكن استخدام التابع selectRaw بدلاً من select(DB::raw(...))‎. يقبل هذا التابع مصفوفةً اختياريّةً من الارتباطات كمتغيّر وسيط ثاني لها:

$orders = DB::table('orders')
                ->selectRaw('price * ? as price_with_tax', [1.0825])
                ->get();

whereRaw / orWhereRaw

whereRaw و orWhereRaw هما تابعان يمكن استخدامها لإضافة بند where خام لاستعلامك. تقبل هذه التوابع مصفوفة اختياريّة من الارتباطات كمتغيّر وسيط ثاني لها:

$orders = DB::table('orders')
                ->whereRaw('price > IF(state = "TX", ?, 100)', [200])
                ->get();

havingRaw / orHavingRaw

havingRaw و orHavingRaw هما تابعان يمكن استخدامها لتعيين سلسلة نصيّة خام كقيمة البند having. تقبل هذه التوابع مصفوفة اختيارية من الارتباطات كمتغيّر وسيط ثاني لها:

$orders = DB::table('orders')
                ->select('department', DB::raw('SUM(price) as total_sales'))
                ->groupBy('department')
                ->havingRaw('SUM(price) > ?', [2500])
                ->get();

orderByRaw

يمكن استخدام التابع orderByRaw لتعيين سلسلة نصيّة خامة كقيمة البند order by:

$orders = DB::table('orders')
                ->orderByRaw('updated_at - created_at DESC')
                ->get();

معاملات ربط الجداول Joins

بند الربط الداخلي (Inner Join Clause)

يمكن استخدام منشئ الاستعلامات لكتابة تعابير الربط (join statements). لإجراء "ربط داخلي" بسيط، تستطيع استخدام التابع join على نسخة منشئ استعلامات. أوّل متغيّر وسيط يُمرّر إلى التابع join هو اسم الجدول الذي تحتاج للربط به في حين أن المُغيّرات الباقية تحدد قيود العمود للربط. تستطيع كما ترى الربط بعدّة جداول في استعلام واحد:

$users = DB::table('users')
            ->join('contacts', 'users.id', '=', 'contacts.user_id')
            ->join('orders', 'users.id', '=', 'orders.user_id')
            ->select('users.*', 'contacts.phone', 'orders.price')
            ->get();

بند الربط اليساري (Left Join Clause)

إن رغبت في عمل "ربط يساري" بدلاً من "ربط داخلي"، استخدم التابع leftJoin. يملك التابع leftJoin نفس توقيع التابع join:

$users = DB::table('users')
            ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
            ->get();

بند الربط المُتقاطع (Cross Join Clause)

لعمل "ربط مُتقاطع"، استخدم التابع crossJoin مع اسم الجدول الذي ترغب في الربط به. يولّد الربط المُتقاطع نتيجة ديكارتيّة بين الجدول الأول والجدول المربوط:

$users = DB::table('sizes')
            ->crossJoin('colours')
            ->get();

بنود الربط المتقدّمة

تستطيع أيضًا تحديد شروط ربط أكثر تقّدمًا. للبدء، مرّر Closure كالمتغيّر الوسيط الثاني في التابع join. سيتلقّى Closure كائن JoinClause والذي يسمح لك بتحديد القيود على البند join:

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')->orOn(...);
        })
        ->get();

تستطيع استخدام التابعين where و orWhere في الربط إن رغبت في استخدام شرط على نمط "where" في ارتباطاتك (joins). ستُقارن هذه التوابع العمود بالقيمة بدلاً من مقارنة عمودين ببعضهما:

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')
                 ->where('contacts.user_id', '>', 5);
        })
        ->get();

ربط الاستعلام الفرعي ( Sub-Query Joins)

تستطيع استخدام التوابع joinSub leftJoinSub و rightJoinSub و rightJoinSub لربط استعلام باستعلام فرعي. يتلقى كل تابع من هذه التوابع ثلاث مُتغيّرات وسيطة: الاستعلام الفرعي، واسم جدولها المستعار (table alias)، ونطاق مغلق يحدّد الأعمدة ذات الصلة:

$latestPosts = DB::table('posts')
                   ->select('user_id', DB::raw('MAX(created_at) as last_post_created_at'))
                   ->where('is_published', true)
                   ->groupBy('user_id');

$users = DB::table('users')
        ->joinSub($latestPosts, 'latest_posts', function($join) {
            $join->on('users.id', '=', 'latest_posts.user_id');
        })->get();

معاملات الدمج Unions

يُوفّر منشئ الاستعلامات أيضًا طريقة سريعة "لدمج" استعلامين معًا. تستطيع مثلًا إنشاء استعلام الأولي ثم استخدام التابع union لدمجه باستعلام الثاني:

$first = DB::table('users')
            ->whereNull('first_name');

$users = DB::table('users')
            ->whereNull('last_name')
            ->union($first)
            ->get();

ملاحظة: يوجد أيضًا التابع unionAll وله نفس إمضاء التابع union.

البنود Where

بنود Where البسيطة

تستطيع استخدام التابع where على نسخة منشئ استعلامات لإضافة بنود where للاستعلام. يتطلب أبسط نداء where ثلاث وسائط. المتغيّر الوسيط الأول هو اسم العمود. المتغيّر الوسيط الثاني هو المُعامل (operator)، والذي يمكن أن يكون أي من المُعاملين المعتمدين في قاعدة البيانات. وأخيرًا يكون المتغيّر الوسيط الثالث هو القيمة التي تُقيّم حسب العمود.

تجد هنا مثلًا استعلامًا يتحقّق من مساواة قيمة العمود "votes" للعدد 100:

$users = DB::table('users')->where('votes', '=', 100)->get();

إن أردت التحقّق من مساواة عمود ما لقيمة معيّنة تستطيع ببساطة تمرير القيمة مباشرة كالمُتغيّر الثاني بالتابع where:

$users = DB::table('users')->where('votes', 100)->get();

تستطيع طبعًا استخدام عدّة مُعاملين آخرين عند كتابة الشرط where:

$users = DB::table('users')
                ->where('votes', '>=', 100)
                ->get();

$users = DB::table('users')
                ->where('votes', '<>', 100)
                ->get();

$users = DB::table('users')
                ->where('name', 'like', 'T%')
                ->get();

تستطيع أيضًا تمرير مصفوفة من الشروط للتابع where:

$users = DB::table('users')->where([
    ['status', '=', '1'],
    ['subscribed', '<>', '1'],
])->get();

العبارات Or

تستطيع ربط قيود where معًا كما تستطيع إضافةً بنود or للاستعلام. يقبل التابع orWhere نفس المُتغيّرات الوسيطة كالتابع where:

$users = DB::table('users')
                    ->where('votes', '>', 100)
                    ->orWhere('name', 'John')
                    ->get();

بنود Where إضاقيّة

whereBetween

يتحقّق التابع من كون قيمة العمود بين قيمتين:

$users = DB::table('users')
                    ->whereBetween('votes', [1, 100])->get();

whereNotBetween

يتحقّق التابع من كون قيمة العمود خارج قيمتين:

$users = DB::table('users')
                    ->whereNotBetween('votes', [1, 100])
                    ->get();

whereIn / whereNotIn

يتحقق التابع whereIn من وجود قيمة العمود المحدّد داخل المصفوفة المحدّدة:

$users = DB::table('users')
                    ->whereIn('id', [1, 2, 3])
                    ->get();

يتحقق التابع whereNotIn من عدم وجود قيمة العمود المحدّد داخل المصفوفة المحدّدة:

$users = DB::table('users')
                    ->whereNotIn('id', [1, 2, 3])
                    ->get();

whereNull / whereNotNull

يتحقق التابع whereNull من كون قيمة العمود المحدّدة NULL:

$users = DB::table('users')
                    ->whereNull('updated_at')
                    ->get();

يتحقق التابع whereNotNull من عدم كون قيمة العمود المحدّدة NULL:

$users = DB::table('users')
                    ->whereNotNull('updated_at')
                    ->get();

whereDate / whereMonth / whereDay / whereYear / whereTime

يمكن استخدام التابع whereDate لمقارنة قيمة العمود بتاريخ ما:

$users = DB::table('users')
                ->whereDate('created_at', '2016-12-31')
                ->get();

يمكن استخدام التابع whereMonth لمقارنة قيمة العمود بشهر مُعيّن من السنة:

$users = DB::table('users')
                ->whereMonth('created_at', '12')
                ->get();

يمكن استخدام التابع whereDay لمقارنة قيمة العمود بيوم معيّن من الشهر:

$users = DB::table('users')
                ->whereDay('created_at', '31')
                ->get();

يمكن استخدام التابع whereTime لمقارنة قيمة العمود بتوقيت معيّن:

$users = DB::table('users')
                ->whereTime('created_at', '=', '11:20:45')
                ->get();

whereColumn

يمكن استخدام التابع whereColumn للتحقق من تساوي عمودين:

$users = DB::table('users')
                ->whereColumn('first_name', 'last_name')
                ->get();

تستطيع أيضًا تمرير عامل مقارنة (comparison operator) للتابع:

users = DB::table('users')
                ->whereColumn('updated_at', '>', 'created_at')
                ->get();

يمكن أيضاً تمرير مصفوفة من عدّة شروط للتابع whereColumn. ستُضمّ هذه الشروط باستخدام المعامل and:

$users = DB::table('users')
                ->whereColumn([
['first_name', '=', 'last_name'],
                    ['updated_at', '>', 'created_at']
                ])->get();

تجميع المعاملات (Parameter Grouping)

قد تحتاج أحياناً لإنشاء بنود where متطوّرة أكثر حيث توجد عبارات مثل "where exists" أو معاملات تجميع متداخلة (nested parameter groupings). يستطيع منشئ الاستعلامات Laravel التعامل معها أيضًا. دعنا نلق نظرة على مثال على قيود التجميع بين قوسين للبدء:

DB::table('users')
            ->where('name', '=', 'John')
            ->where(function ($query) {
                $query->where('votes', '>', 100)
                      ->orWhere('title', '=', 'Admin');
            })
            ->get();

يأمر تمرير Closure للتابع where منشئ الاستعلامات ببدء مجموعة قيود. سيتلقى Closure نسخة منشئ استعلامات تستطيع استخدامها لتحديد القيود التي يجب احتواؤها داخل مجموعة القوسين. سينتج المثال أعلاه SQL التالي:

select * from users where name = 'John' and (votes > 100 or title = 'Admin')

ملاحظة: يجب دائمًا تجميع نداءات orWhere تجنّبًا لحدوث سلوك غير متوقع عند تطبيق النطاقات العامة.

البنود Where Exists

يسمح لك التابع whereExists بكتابة العبارات whereexists SQL. يقبل التابع whereExists متغيّر وسيط Closure والذي سيتلقّى نسخة منشئ الاستعلامات ممّا يسمح لك بتعريف الاستعلام الذي يجب وضعه داخل البند "exists":

DB::table('users')
            ->whereExists(function ($query) {
                $query->select(DB::raw(1))
                      ->from('orders')
                      ->whereRaw('orders.user_id = users.id');
            })
            ->get();

سينتج الاستعلام أعلاه SQL التالي:

select * from users
where exists (
    select 1 from orders where orders.user_id = users.id
)

البنود JSON Where

يدعم Laravel أيضًا الاستعلام عن أنواع الأعمدة JSON بقواعد البيانات التي تدعم أنواع الأعمدة JSON. يتضمّن هذا حاليًّا MySQL 5.7 و PostgreSQL و SQL Server 2016 و SQLite 3.9.0 (مع ملحق JSON1). للاستعلام عن عمود JSON ، استخدم عامل التشغيل ‎->‎:

$users = DB::table('users')
                ->where('options->language', 'en')
                ->get();

$users = DB::table('users')
                ->where('preferences->dining->meal', 'salad')
                ->get();

يدعم MySQL و PostgreSQL عدّة قيم من whereJsonContains:

$users = DB::table('users')
                ->whereJsonContains('options->languages', ['en', 'de'])
                ->get();

الترتيب والتجميع والحد والإزاحة

orderBy

يتيح لك التابع فرز نتائج الاستعلام حسب عمود محدّد. يجب أن يكون متغيّر التابع orderBy الوسيط الأول هو العمود الذي تريد الفرز حسبه بينما يتحكّم المتغيّر الوسيط الثاني في اتجاه الفرز وقد تكون إمّا asc أو desc:

$users = DB::table('users')
                ->orderBy('name', 'desc')
                ->get();

latest / oldest

يسمح لك التابعان بترتيب النتائج حسب التاريخ بسهولة. تُرتّب النتيجة افتراضيًّا حسب العمود created_at. أو تستطيع تمرير اسم العمود الذي تريد الترتيب وفقًا له:

$user = DB::table('users')
                ->latest()
                ->first();

inRandomOrder

يُمكن استخدام التابع لفرز نتائج الاستعلام عشوائيًّا. تستطيع مثلًا استخدام هذا التابع لجلب مستخدم عشوائي:

$randomUser = DB::table('users')
                ->inRandomOrder()
                ->first();

groupBy / having

يمكن استخدام التابعين لتجميع نتائج الاستعلام. يُشابه توقيع التابع having توقيع التابع where:

$users = DB::table('users')
                ->groupBy('account_id')
                ->having('account_id', '>', 100)
                ->get();

تستطيع تمرير عدّة مُتغيّرات وسيطة للتابع groupBy لتجميع عدّة أعمدة:

$users = DB::table('users')
                ->groupBy('first_name', 'status')
                ->having('account_id', '>', 100)
                ->get();

لمزيد من المعلومات حول عبارات having أكثر تطوّرًا راجع التابع havingRaw.

skip / take

للحد من عدد من النتائج التي يردّها الاستعلام، أو لتخطّي عدد معيّن من النتائج في الاستعلام، تستطيع استخدام التابعين skip و take:

$users = DB::table('users')->skip(10)->take(5)->get();

تستطيع كبديل استخدام التابعين limit و offset:

$users = DB::table('users')
                ->offset(10)
                ->limit(5)
                ->get();

البنود المشروطة (Conditional Clauses)

قد ترغب أحيانًا في تطبيق بنود ما على الاستعلام فقط عندما تكون قيمة شيء آخر true. قد ترغب مثلًا بتطبيق عبارة where فقط إن كانت قيمة إدخال معيّنة موجودة في الطلب الوارد. تقدر على فعل هذا باستخدام التابع when:

$role = $request->input('role');

$users = DB::table('users')
                ->when($role, function ($query, $role) {
                    return $query->where('role_id', $role);
                })
                ->get();

يُنفّذ التابع when النطاق المُغلق المحدّد Closure فقط عندما تكون المعاملة الأولى true. في حالة كانت المعاملة الأولى false لن يُنفّذ النطاق المغلق Closure. تستطيع تمرير نطاق مُغلق Closure آخر كثالث معامل للتابع when. سيُنفّذ هذا النطاق المُغلق في حالة كانت المعاملة الأولى false. لتوضيح كيفيّة استخدام هذه الميزة سنستخدمها لاعداد الفرز الافتراضي لاستعلام:

$sortBy = null;

$users = DB::table('users')
                ->when($sortBy, function ($query, $sortBy) {
                    return $query->orderBy($sortBy);
                }, function ($query) {
                    return $query->orderBy('name');
                })
                ->get();

إدخالات السجلّات للجدول Inserts

يوفّر منشئ الاستعلامات أيضا تابع insert لإدراج السجلّات في جدول قاعدة البيانات. يقبل التابع insert مصفوفةً من أسماء الأعمدة وقيمها:

DB::table('users')->insert(
    ['email' => '[email protected]', 'votes' => 0]
);

تستطيع حتى إدراج عدة سجلّات في الجدول بنداء insert واحد عن طريق تمرير مصفوفة من المصفوفات. تمثّل كل مصفوفة صفًا سيُدرج في الجدول:

DB::table('users')->insert([
    ['email' => '[email protected]com', 'votes' => 0],
    ['email' => '[email protected]', 'votes' => 0]
]);

المُعرّفات تلقائيّة الزيادة (Auto-Incrementing IDs)

استخدم التابعين insertGetId و insertGetId إذا احتوى الجدول على معرّف تلقائي الزيادة لإدراج سجلّ ثم استرد الُمعرّف:

$id = DB::table('users')->insertGetId(
    ['email' => '[email protected]', 'votes' => 0]
);

ملاحظة: عند استخدام ،PostgreSQL يتوقّع التابع insertGetId تسمية عمود الزيادة التلقائية باسم id. تستطيع تمرير اسم العمود كمعاملة ثانية للتابع insertGetId إن رغبت باسترداد المعرّف من "تسلسل" مختلف.

التحديثات Updates

يستطيع منشئ الاستعلامات أيضًا تحديث السجلات الموجودة باستخدام التابع update إضافةً لإدخال السجلات في قاعدة البيانات. يقبل التابع update، مثل التابع insert، مصفوفة من أزواج الأعمدة والقيم التي تحتوي على الأعمدة المُراد تحديثها. تستطيع تقييد استعلام update باستخدام بنود where:

DB::table('users')
            ->where('id', 1)
            ->update(['votes' => 1]);

تحديث أعمدة JSON

يجب استخدام الصيغة -> عند تحديث عمود JSON للوصول للمفتاح المناسب في الكائن JSON. هذه العملية مدعومة فقط على MySQL 5.7+‎:

DB::table('users')
            ->where('id', 1)
            ->update(['options->enabled' => true]);

الزيادة والنقصان

يوفّر منشئ الاستعلامات أيضًا توابع ملائمة لزيادة قيمة العمود المُحدّد أو انقاصها. هذا اختصار يوفّر واجهة أكثر تعبيرًا واقتضابًا مقارنة بكتابة العبارة update يدويًا.

يقبل كلا التابعين متغيّر وسيط واحد على الأقل: العمود المُراد تعديله. قد يُمرّر متغيّر وسيط ثاني اختياريًا للتحكّم في مقدار زيادة العمود أو تنقيصه:

DB::table('users')->increment('votes');

DB::table('users')->increment('votes', 5);

DB::table('users')->decrement('votes');

DB::table('users')->decrement('votes', 5);

تستطيع أيضًا تحديد أعمدة إضافيّة لتحديثها أثناء العملية:

DB::table('users')->increment('votes', 1, ['name' => 'John']);

الحذف Deletes

يمكن أيضًا استخدام منشئ الاستعلامات لحذف السجلات من الجدول عبر التابع delete. تستطيع تقييد العبارات delete بإضافة بنود where قبل مناداة التابع delete:

DB::table('users')->delete();

DB::table('users')->where('votes', '>', 100)->delete();

تستطيع استخدام التابع truncate إن رغبت في اقتطاع الجدول بأكمله، ممّا سيؤدي لإزالة جميع الصفوف وإعادة المُعرّف تلقائي الزيادة للصفر:

DB::table('users')->truncate();

«الإقفال المتشائم» (Pessimistic Locking)

ويشمل منشئ الاستعلامات أيضًا عددًا صغيرًا من الدوال لمساعدتك على "الإقفال المتشائم" بعباراتك select. تستطيع استخدام التابع sharedLock في الاستعلام لتشغيل العبارة باستخدام "قفل مشترك". يمنع القفل المشترك تعديل الصفوف المحدّدة حتى تنفيذ (commit) معاملتك:

DB::table('users')->where('votes', '>', 100)->sharedLock()->get();

تستطيع استخدام التابع lockForUpdate كبديل. يمنع قفل "للتحديث" (for update) تعديل الصفوف أو تحديدها باستخدام قفل مشترك آخر:

DB::table('users')->where('votes', '>', 100)->lockForUpdate()->get();

مصادر