حزمة Spatie PHP: دليل شامل مع أمثلة تطبيقية

ما هي هذه المكتبة ولماذا تحتاجها؟

Spatie ليست مكتبة واحدة، بل نظام بيئي متكامل من حزم PHP عالية الجودة، تم تطويرها بواسطة شركة بلجيكية تحمل نفس الاسم. تشتهر Spatie بنهجها في كتابة كود نظيف وقابل للاختبار وموثق جيدًا. تغطي حزمها مجموعة واسعة من المهام: من التعامل مع ملفات الوسائط وتخزين الاستعلامات مؤقتًا إلى إدارة الأدوار والصلاحيات.

مجموعة أدوات Spatie (spatie/collection-utilities) هي مجموعة من الدوال والفئات المساعدة التي توسع الإمكانيات القياسية للمصفوفات والمجموعات في PHP. توفر طرقًا مريحة للتصفية والفرز والتحويل وتحليل البيانات، مما يجعل الكود أكثر قابلية للقراءة والاختصار.

لماذا تحتاجها؟ في تطوير PHP الحديث (خاصة في أطر العمل مثل Laravel)، التعامل مع مجموعات البيانات هو مهمة يومية. توفر Spatie Collection Utilities حلاً جاهزًا وموثقًا جيدًا، مما يغنيك عن كتابة الحلقات والشروط المتكررة. هذا يسرع التطوير ويقلل الأخطاء ويزيد من قابلية صيانة الكود.

التثبيت

يتم تثبيت حزم Spatie عبر Composer، مدير الحزم القياسي لـ PHP.

composer require spatie/collection-utilities

إذا كنت تستخدم Laravel، سيتم تسجيل الحزمة تلقائيًا بفضل التحميل التلقائي لـ Composer. لأطر العمل الأخرى أو PHP الخالص، أضف السطر require 'vendor/autoload.php'; إلى ملفك البرمجي.

بداية سريعة مع مثال برمجي

بعد التثبيت، يمكنك البدء فورًا في استخدام الأدوات. الفئة الرئيسية التي ستتعامل معها هي Spatie\CollectionUtilities\Collection. هذه الفئة توسع الفئة القياسية Illuminate\Support\Collection (من Laravel) أو يمكن استخدامها كفئة مستقلة.

<?php
require 'vendor/autoload.php';

use Spatie\CollectionUtilities\Collection;

// إنشاء مجموعة
$collection = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

// استخدام طريقة filter للحصول على الأرقام الزوجية
$evenNumbers = $collection->filter(fn($item) => $item % 2 === 0);

// استخدام طريقة map لضرب كل عنصر في 2
$doubled = $evenNumbers->map(fn($item) => $item * 2);

// استخدام طريقة toArray للتحويل مرة أخرى إلى مصفوفة
print_r($doubled->toArray());
// النتيجة: Array ( [0] => 4 [1] => 8 [2] => 12 [3] => 16 [4] => 20 )
?>

هذا المثال البسيط يوضح سلسلة الطرق (method chaining)، وهي ميزة أساسية للعمل مع مجموعات Spatie.

الطرق/الدوال الأساسية

1. filter()

الوظيفة: تقوم بتصفية المجموعة باستخدام دالة رد (callback). تُرجع فقط العناصر التي تعيد الدالة لها القيمة true.

المعاملات:

• callback (callable): دالة تستقبل العنصر الحالي ومفتاحه. يجب أن تعيد true أو false.
• mode (int): اختياري. وضع التصفية (الافتراضي هو ARRAY_FILTER_USE_BOTH).

مثال برمجي عملي:

$users = new Collection([
    ['name' => 'أحمد', 'age' => 25],
    ['name' => 'سارة', 'age' => 17],
    ['name' => 'خالد', 'age' => 30],
]);

$adults = $users->filter(fn($user) => $user['age'] >= 18);
// النتيجة: مجموعة تحتوي على أحمد وخالد

2. map()

الوظيفة: تطبق دالة رد على كل عنصر في المجموعة وتُعيد مجموعة جديدة تحتوي على العناصر المحولة.

المعاملات:

• callback (callable): دالة تستقبل العنصر الحالي ومفتاحه. يجب أن تعيد القيمة المحولة.

مثال برمجي عملي:

$prices = new Collection([100, 200, 300]);
$withTax = $prices