league/csv PHP: دليل شامل، دوال، تثبيت وأمثلة

مقدمة عن مكتبة league/csv في PHP

مكتبة league/csv هي أداة قوية وسهلة للتعامل مع ملفات CSV (قيم مفصولة بفواصل) في PHP. توفر للمطورين واجهة برمجية بسيطة ومرنة لقراءة وكتابة ومعالجة وتحويل بيانات CSV. على عكس دوال PHP المدمجة (fgetcsv، fputcsv)، تقدم league/csv نهجًا كائني التوجه، ودعمًا لصيغ CSV المختلفة، والتعامل مع علامة ترتيب البايت (BOM)، ومعالجة الملفات الكبيرة باستخدام المكررات (iterators)، والعديد من الميزات المفيدة الأخرى.

هذه المكتبة جزء من نظام The League of Extraordinary Packages وتُعتبر المعيار الفعلي للتعامل مع CSV في PHP. يتم دعمها بنشاط، ولديها توثيق ممتاز، ومغطاة بالاختبارات.

لماذا تحتاج إلى league/csv؟

تبسيط العمل مع CSV: بدلاً من إدارة مؤشرات الملفات والحلقات يدويًا، تتعامل مع كائنات ودوال واضحة.
الأمان: تتعامل المكتبة بشكل صحيح مع ترميز الأحرف والاقتباسات وفواصل الأسطر داخل الحقول.
المرونة: دعم فواصل مختلفة (فاصلة، فاصلة منقوطة، تبويب)، ورموز ترميز، ومحددات نصوص.
الأداء: استخدام المولدات (yield) يسمح بمعالجة ملفات بأي حجم دون تحميل المحتوى بالكامل في الذاكرة.
الوظائف: دوال مدمجة للتحويل إلى JSON وHTML وXML والفرز والتصفية وتحويل الأعمدة.

تثبيت المكتبة

يتم تثبيت league/csv عبر Composer - مدير الحزم في PHP. تأكد من تثبيت Composer على نظامك.

افتح الطرفية في المجلد الجذر لمشروعك ونفذ الأمر التالي:

composer require league/csv

بعد التثبيت الناجح، سيظهر مجلد vendor وملف composer.json / composer.lock في مشروعك. لربط المكتبة في سكريبت PHP، استخدم المحمل التلقائي القياسي لـ Composer:

require 'vendor/autoload.php';

use League\Csv\Reader;
use League\Csv\Writer;
use League\Csv\Statement;

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

لننشئ ملف CSV بسيطًا، ونكتب فيه بيانات، ثم نقرأها.

مثال 1: كتابة البيانات إلى CSV

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

use League\Csv\Writer;

// إنشاء كائن Writer
$writer = Writer::createFromPath('users.csv', 'w+');

// إدراج العناوين
$writer->insertOne(['ID', 'الاسم', 'البريد الإلكتروني']);

// إدراج عدة صفوف من البيانات
$writer->insertAll([
    [1, 'أحمد علي', 'ahmed@example.com'],
    [2, 'محمد حسن', 'mohamed@example.com'],
    [3, 'سارة خالد', 'sara@example.com'],
]);

echo "تم إنشاء ملف users.csv بنجاح!";
?>

مثال 2: قراءة البيانات من CSV

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

use League\Csv\Reader;

// إنشاء كائن Reader
$reader = Reader::createFromPath('users.csv', 'r');
$reader->setHeaderOffset(0); // تحديد أن الصف الأول هو العناوين

// الحصول على جميع السجلات كمصفوفات ترابطية
$records = $reader->getRecords();

foreach ($records as $record) {
    echo "ID: " . $record['ID'] . ", الاسم: " . $record['الاسم'] . ", البريد الإلكتروني: " . $record['البريد الإلكتروني'] . "<br>";
}
?>