تخصيص التّصفيح (Pagination) في Laravel: دليل شامل ومفصل

يُعدّ إطار العمل Laravel من أشهر وأقوى أُطُر تطوير تطبيقات الويب بلغة PHP، وذلك لما يوفّره من سهولة في الاستخدام، ومرونة عالية في تنفيذ العديد من الوظائف، ومن بينها نظام التّصفيح (Pagination). التّصفيح هو أحد الأدوات الأساسية في تطوير التطبيقات التي تعتمد على عرض بيانات كثيرة بشكل منظم يسهل تصفحها من قبل المستخدم. في هذا المقال، سنستعرض بالتفصيل كيفية تخصيص نظام التّصفيح في Laravel، مع شرح معمق لأهم الخيارات المتاحة لتلبية احتياجات المشاريع المختلفة.

مفهوم التّصفيح وأهميته في تطوير التطبيقات

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

في Laravel، التّصفيح مدمج بشكل أساسي ويُقدّم طريقة سهلة وسلسة للتعامل مع قواعد البيانات وعرض البيانات المصّفحة في الواجهات، سواء كانت تطبيقات ويب تقليدية أو تطبيقات API.

أنواع التّصفيح في Laravel

يُوفّر Laravel نوعين رئيسيين من التّصفيح:

1. التّصفيح العادي (Simple Pagination):

   • يعرض روابط تصفح أمام المستخدم مثل “التالي” و”السابق”.

   • لا يُظهر عدد الصفحات الكلي.

   • أقل استهلاكًا للموارد.

   • يُستخدم في حالة عدم الحاجة لمعرفة العدد الإجمالي للصفحات.

2. التّصفيح الكامل (LengthAware Pagination):

   • يعرض روابط جميع الصفحات، مع إمكانية التنقل بينها بشكل مباشر.

   • يعرض عدد الصفحات الكلي وعدد العناصر.

   • يحتاج إلى استعلام إضافي لحساب العدد الإجمالي.

كيفية استخدام التّصفيح في Laravel

التّصفيح العادي (Simple Pagination)

يمكن استخدام التّصفيح العادي عبر استدعاء الدالة simplePaginate على استعلام قاعدة البيانات، كالتالي:

php
CopyEdit
$users = User::simplePaginate(10);

هذا يعني أن كل صفحة ستحتوي على 10 مستخدمين، وسيتم عرض أزرار “التالي” و”السابق” فقط.

التّصفيح الكامل (LengthAware Pagination)

أما التّصفيح الكامل فيتم عبر الدالة paginate:

php
CopyEdit
$users = User::paginate(10);

هنا، يعرض التطبيق روابط لكل الصفحات مع عددها، ويمكن للمستخدم التنقل بينها مباشرة.

تخصيص التّصفيح في Laravel

واحدة من أهم ميزات Laravel هي إمكانية تخصيص التّصفيح بالشكل الذي يلائم متطلبات المشروع. هذا التخصيص يتنوع بين شكل العرض (HTML)، طريقة استدعاء البيانات، وحتى طريقة تخزين إعدادات التّصفيح.

1. تخصيص عدد العناصر في الصفحة

يمكن للمطور تحديد عدد العناصر التي تظهر في كل صفحة حسب الحاجة. يتم ذلك بتمرير الرقم المطلوب إلى دوال التّصفيح paginate أو simplePaginate:

php
CopyEdit
$products = Product::paginate(20);

في هذا المثال، سيعرض التطبيق 20 منتجًا في كل صفحة.

2. تخصيص رابط التّصفيح (URL)

بشكل افتراضي، يستخدم Laravel معلمة ?page= في روابط التّصفيح، لكن يمكن تغييره باستخدام الدالة withQueryString() أو تخصيص اسم المعلمة.

• حفظ باقي معاملات الطلب (Query Parameters):

php
CopyEdit
$users = User::paginate(10)->withQueryString();

يحتفظ هذا الخيار بجميع المعلمات الموجودة في الرابط، مثل عوامل البحث أو التصفية، مما يحسن تجربة المستخدم.

• تغيير اسم معلمة الصفحة:

يمكن تخصيص اسم المعلمة التي تحمل رقم الصفحة باستخدام خاصية Paginator::currentPageResolver أو عن طريق تعيينها في إعدادات التطبيق.

php
CopyEdit
Paginator::currentPageResolver(function ($pageName = 'my_page') {
    return request()->input($pageName);
});

وبذلك تصبح روابط التّصفيح مثلاً: ?my_page=2 بدلًا من ?page=2.

3. تخصيص واجهة عرض التّصفيح (HTML)

Laravel يستخدم مكونات Blade جاهزة لعرض التّصفيح، يمكن للمطور تعديلها أو استبدالها حسب التصميم المطلوب.

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

في مجلد resources/views/vendor/pagination/ يمكن نسخ ملفات العرض الإفتراضية وتعديلها لتناسب التصميم الخاص.

مثلاً، يمكنك نسخ ملف default.blade.php وتعديله، ثم استخدامه كالتالي:

php
CopyEdit
{{ $users->links('vendor.pagination.custom') }}

حيث custom هو اسم القالب المخصص.

• تغيير تنسيق HTML الخاص بالتّصفيح:

يمكن التعديل على طريقة عرض أزرار الصفحة، إضافة أيقونات، أو تعديل النصوص (مثل تغيير “التالي” إلى “التالي >>”).

4. تخصيص عدد روابط الصفحات الظاهرة

بشكل افتراضي، يعرض Laravel عدد معين من روابط الصفحات، لكن يمكن التحكم في هذا العدد من خلال تخصيص الطريقة التي تُعرض فيها الروابط.

مثلاً، يمكن بناء روابط الصفحات يدويًا عبر تعديل ملف Blade الخاص بالتّصفيح.

5. تصفيح API باستخدام Laravel

في تطبيقات الـ API التي تستخدم Laravel، من الضروري تقديم التّصفيح بطريقة JSON مناسبة.

• التّصفيح في الـ API:

php
CopyEdit
$users = User::paginate(15);
return response()->json($users);

سيقوم Laravel تلقائيًا بإضافة بيانات التّصفيح مثل عدد الصفحات، الصفحة الحالية، وعدد العناصر الإجمالي في الاستجابة.

• تخصيص تنسيق التّصفيح في JSON:

يمكن إنشاء موارد Resource مخصصة باستخدام Laravel Resource Collections لتنسيق الاستجابة بالشكل المطلوب.

خطوات تنفيذ تخصيص التّصفيح عمليًا

مثال عملي: تخصيص التّصفيح مع استعلامات مخصصة

افترض وجود جدول posts ونريد عرض المقالات مع التّصفيح، لكن مع دعم عمليات البحث والتصفية، مع الحفاظ على جميع المعلمات في الرابط.

php
CopyEdit
public function index(Request $request)
{
    $query = Post::query();

    if ($request->has('category')) {
        $query->where('category_id', $request->category);
    }

    if ($request->has('search')) {
        $query->where('title', 'like', '%' . $request->search . '%');
    }

    $posts = $query->paginate(10)->withQueryString();

    return view('posts.index', compact('posts'));
}

• هنا تم استخدام دالة withQueryString() للحفاظ على معاملات البحث والتصفية في روابط التّصفيح.

• في واجهة العرض Blade يمكن عرض التّصفيح بالشكل المعتاد:

blade
CopyEdit
{{ $posts->links() }}

تخصيص قالب التّصفيح في Blade

يمكن نسخ ملفات التّصفيح الافتراضية من الحزمة الرسمية عبر الأمر:

bash
CopyEdit
php artisan vendor:publish --tag=laravel-pagination

سيتم نسخ ملفات العرض إلى مجلد resources/views/vendor/pagination/ حيث يمكن التعديل عليها بحرية لتغيير شكل التّصفيح.

استخدام Bootstrap أو Tailwind مع التّصفيح في Laravel

Laravel يدعم التّصفيح المتوافق مع أشهر مكتبات CSS مثل Bootstrap وTailwind، من خلال تحديد “ستايل” التّصفيح.

ضبط التّصفيح ليتوافق مع Bootstrap

يمكن ضبط التّصفيح ليستخدم تنسيقات Bootstrap عبر إعداد القيمة في ملف AppServiceProvider.php داخل دالة boot:

php
CopyEdit
use Illuminate\Pagination\Paginator;

public function boot()
{
    Paginator::useBootstrap();
}

بعد ذلك، ستستخدم روابط التّصفيح تنسيقات Bootstrap بشكل تلقائي.

ضبط التّصفيح ليتوافق مع Tailwind CSS

بنفس الطريقة:

php
CopyEdit
public function boot()
{
    Paginator::useTailwind();
}

يتم استخدام تنسيق Tailwind لتوليد روابط التّصفيح.

تحسين أداء التّصفيح في قواعد البيانات الكبيرة

عند التعامل مع قواعد بيانات كبيرة، قد يؤدي حساب العدد الكلي للصفحات في التّصفيح الكامل إلى بطء في الأداء، لأن Laravel يقوم بتنفيذ استعلام COUNT(*) لكل استعلام تصفيح.

الحلول المتاحة:

• استخدام التّصفيح العادي simplePaginate:

  يتجنب هذا الخيار استعلام العد، ويُفضل عند عدم الحاجة لمعرفة العدد الكامل للصفحات.

• التخزين المؤقت (Caching):

  تخزين نتيجة استعلام العد مؤقتاً يقلل الضغط على قاعدة البيانات.

• استخدام مكتبات خارجية:

  مثل Laravel Scout مع محركات بحث متقدمة، أو حزم متخصصة لتحسين التّصفيح.

الجدول التالي يوضح مقارنة بين خصائص التّصفيح العادي والتّصفيح الكامل في Laravel:

نصائح متقدمة لتخصيص التّصفيح في Laravel

• تخصيص عدد العناصر بشكل ديناميكي:

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

  php
  CopyEdit
  $perPage = $request->input('per_page', 15); // 15 هو القيمة الافتراضية
  $items = Item::paginate($perPage);
  

• تخصيص رابط التّصفيح ليشمل ترتيب البيانات:

  عند تطبيق عمليات ترتيب، يجب المحافظة على معاملات الطلب:

  php
  CopyEdit
  $items = Item::orderBy('created_at', 'desc')->paginate(10)->withQueryString();
  

• التّصفيح مع العلاقات:

  يمكن تطبيق التّصفيح على العلاقات عبر Eloquent:

  php
  CopyEdit
  $user = User::find(1);
  $posts = $user->posts()->paginate(10);
  

• التّصفيح المخصص باستخدام مكتبات خارجية:

  يمكن دمج مكتبات JavaScript مثل Vue.js مع Laravel لتحقيق تصفيح ديناميكي بدون إعادة تحميل الصفحة باستخدام API مخصصة.

الخلاصة

تخصيص التّصفيح في Laravel هو عنصر حيوي يمكن من خلاله تحسين تجربة المستخدم وأداء التطبيق. إطار Laravel يتيح مرونة واسعة في التّصفيح، بداية من تحديد عدد العناصر في الصفحة، مرورًا بتخصيص روابط التّصفيح، تعديل شكل العرض، وصولاً إلى تنسيقات متوافقة مع أشهر مكتبات CSS. بالإضافة إلى ذلك، يوفر خيارات للتعامل مع قواعد بيانات ضخمة عبر التّصفيح العادي أو التخزين المؤقت.

من المهم اختيار نوع التّصفيح المناسب حسب حجم البيانات وطبيعة الاستخدام، مع مراعاة تحسين الأداء وتوفير واجهة مستخدم سلسة ومرنة. التّصفيح في Laravel ليس مجرد وظيفة جاهزة، بل هو نظام متكامل قابل للتخصيص والتطوير بما يتناسب مع متطلبات المشاريع المتنوعة.

المصادر والمراجع

1. Laravel Documentation – Pagination

2. Laravel News – Customizing Pagination Views

هذا المقال يقدم شرحًا متعمقًا وشاملاً لكيفية تخصيص نظام التّصفيح في Laravel، ويغطي معظم جوانب الاستخدام العملي والتقني التي تهم المطورين الراغبين في بناء تطبيقات متقدمة وفعالة.