تحويل سجلات JSON إلى تنسيق CSV هو طلب شائع للتقارير وتبادل البيانات في تطبيقات PHP الحديثة. يوفر Aspose.BarCode Cloud SDK for PHP واجهة برمجة تطبيقات قوية لإنشاء صور الباركود ومعالجة تحويلات الملفات مباشرةً من خادمك. في هذا الدليل ستشاهد مثالًا كاملاً لتحويل JSON إلى CSV بلغة PHP يتضمن أيضًا صور الباركود لكل سجل. سنستعرض الإعداد، التنفيذ خطوة بخطوة، بديل cURL، وأفضل ممارسات الأداء.

كيفية تحويل بيانات JSON إلى CSV في PHP - خطوة بخطوة

  1. تثبيت SDK عبر Composer: استخدم حزمة Composer الرسمية لإضافة المكتبة إلى مشروعك.
composer require aspose-barcode-cloud
  1. تكوين بيانات اعتماد API وإنشاء مثيل BarCodeApi: استبدل YOUR_APP_SID و YOUR_APP_KEY ببيانات اعتماد السحابة الخاصة بك.
use Aspose\BarCode\Cloud\Configuration;
use Aspose\BarCode\Cloud\BarCodeApi;

$appSid = 'YOUR_APP_SID';
$appKey = 'YOUR_APP_KEY';
$config = new Configuration($appSid, $appKey);
$apiInstance = new BarCodeApi($config);

المرجع: BarCodeApi class. 3. فتح ملف JSON المصدر وملف CSV الهدف: يعمل السكريبت باستخدام تدفقات الملفات للحفاظ على استهلاك الذاكرة منخفضًا.

$inputHandle  = fopen($inputJsonPath, 'rb');
$outputHandle = fopen($outputCsvPath, 'wb');
  1. التكرار عبر سجلات JSON، إنشاء الباركود، وكتابة صفوف CSV: يتم تحويل حقل id في كل سجل إلى صورة باركود، تُشفّر بصيغة base64، وتُضاف إلى ملف CSV.
while (($line = fgets($inputHandle)) !== false) {
    $record = json_decode(trim($line), true);
    $barcodeValue = $record['id'] ?? '';
    $barcodeRequest = new GenerateBarcodeRequest([
        'type'   => $barcodeFormat,
        'text'   => (string)$barcodeValue,
        'format' => 'PNG',
        'resolutionX' => 300,
        'resolutionY' => 300
    ]);
    $barcodeResponse = $apiInstance->generateBarcode($barcodeRequest);
    $record['barcode_image'] = base64_encode($barcodeResponse);
    // Write header once, then rows
    // ...
}
  1. تنظيف الملفات المؤقتة وإغلاق التدفقات: يتم حذف المجلد المؤقت بعد المعالجة.
fclose($inputHandle);
fclose($outputHandle);
array_map('unlink', glob($barcodeTempDir . '/*.png'));
rmdir($barcodeTempDir);

إنشاء مخرجات CSV من JSON في PHP - مثال كامل للكود

يوضح المثال التالي التنفيذ الكامل لقراءة ملف JSON، وإنشاء صور الباركود، وكتابة البيانات إلى ملف CSV باستخدام Aspose.BarCode Cloud SDK for PHP.

<?php
declare(strict_types=1);

// Autoload Composer dependencies (Aspose.BarCode Cloud SDK)
require __DIR__ . '/vendor/autoload.php';

use Aspose\BarCode\Cloud\Configuration;
use Aspose\BarCode\Cloud\BarCodeApi;
use Aspose\BarCode\Cloud\Model\GenerateBarcodeRequest;

// -------------------- Configuration --------------------
$appSid = 'YOUR_APP_SID';
$appKey = 'YOUR_APP_KEY';
$config = new Configuration($appSid, $appKey);
$apiInstance = new BarCodeApi($config);

// -------------------- Settings --------------------
$inputJsonPath   = __DIR__ . '/data/input.json';   // JSON source (one object per line)
$outputCsvPath   = __DIR__ . '/data/output.csv';   // Resulting CSV
$delimiter       = ';';                           // Custom CSV delimiter
$encoding        = 'UTF-8';                       // Target CSV encoding
$barcodeFormat   = 'Code128';                     // Barcode symbology
$barcodeField    = 'id';                          // JSON field to turn into barcode
$barcodeTempDir  = __DIR__ . '/temp_barcodes';    // Temporary folder for barcode images

// Ensure temporary directory exists
if (!is_dir($barcodeTempDir)) {
    mkdir($barcodeTempDir, 0777, true);
}

// -------------------- Open Files --------------------
$inputHandle  = fopen($inputJsonPath, 'rb');
if ($inputHandle === false) {
    throw new RuntimeException("Unable to open input JSON file.");
}
$outputHandle = fopen($outputCsvPath, 'wb');
if ($outputHandle === false) {
    fclose($inputHandle);
    throw new RuntimeException("Unable to open output CSV file.");
}

// Write UTF-8 BOM for Excel compatibility
fwrite($outputHandle, "\xEF\xBB\xBF");

// -------------------- Process JSON --------------------
$headerWritten = false;
while (($line = fgets($inputHandle)) !== false) {
    $line = trim($line);
    if ($line === '' || $line === '[' || $line === ']') {
        continue; // skip empty lines or array brackets
    }
    // Remove trailing commas if present (common in pretty‑printed arrays)
    $line = rtrim($line, ',');
    $record = json_decode($line, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        continue; // skip malformed lines
    }

// Generate barcode image for the selected field
    $barcodeValue = $record[$barcodeField] ?? '';
    $barcodeRequest = new GenerateBarcodeRequest([
        'type' => $barcodeFormat,
        'text' => (string)$barcodeValue,
        'format' => 'PNG',
        'resolutionX' => 300,
        'resolutionY' => 300
    ]);
    try {
        $barcodeResponse = $apiInstance->generateBarcode($barcodeRequest);
        $barcodeFilePath = $barcodeTempDir . '/' . uniqid('barcode_', true) . '.png';
        file_put_contents($barcodeFilePath, $barcodeResponse);
        // Store relative path (or base64) in CSV; here we use base64 to keep CSV self‑contained
        $barcodeBase64 = base64_encode($barcodeResponse);
        $record['barcode_image'] = $barcodeBase64;
    } catch (Exception $e) {
        $record['barcode_image'] = '';
    }

// Prepare CSV row with proper UTF‑8 encoding
    $csvRow = [];
    foreach ($record as $value) {
        if (is_array($value) || is_object($value)) {
            $value = json_encode($value, JSON_UNESCAPED_UNICODE);
        }
        $csvRow[] = mb_convert_encoding((string)$value, $encoding, 'UTF-8');
    }

// Write header once
    if (!$headerWritten) {
        $header = array_keys($record);
        fputcsv($outputHandle, $header, $delimiter);
        $headerWritten = true;
    }

// Write data row
    fputcsv($outputHandle, $csvRow, $delimiter);
}

// -------------------- Cleanup --------------------
fclose($inputHandle);
fclose($outputHandle);

// Optionally delete temporary barcode files
array_map('unlink', glob($barcodeTempDir . '/*.png'));
rmdir($barcodeTempDir);

ملاحظة: يوضح مثال الشيفرة هذا الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث مسارات الملفات (input.json, output.csv, إلخ) لتطابق المواقع الفعلية للملفات لديك، وتحقق من تثبيت جميع الاعتمادات المطلوبة بشكل صحيح، واختبر بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشكلات، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

إنشاء CSV عبر REST API من JSON باستخدام cURL

يمكنك تحقيق النتيجة نفسها دون كتابة كود PHP عن طريق استدعاء نقاط النهاية REST الخاصة بـ Aspose.BarCode Cloud مباشرةً. تتكون سير العمل من تحميل ملف JSON، وإنشاء رمز شريطي لكل سجل، وتنزيل ملف CSV النهائي.

  1. الحصول على رمز وصول (استبدل العناصر النائبة ببيانات الاعتماد الخاصة بك).
curl -X POST "https://api.aspose.cloud/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

تحتوي الاستجابة على access_token.

  1. تحميل ملف JSON المصدر.
curl -X PUT "https://api.aspose.cloud/v3.0/barcode/storage/file/input.json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     --data-binary @data/input.json
  1. إنشاء رمز شريطي لسجل واحد (تكرار لكل سجل في البرنامج النصي).
curl -X POST "https://api.aspose.cloud/v3.0/barcode/generate" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "type":"Code128",
           "text":"12345",
           "format":"PNG",
           "resolutionX":300,
           "resolutionY":300
         }' \
     -o temp/barcode_12345.png
  1. تجميع ملف CSV (يمكنك استخدام برنامج نصي بسيط يقرأ ملف JSON المرفوع، يدرج الباركود المشفر بقاعدة64، ويكتب ملف CSV).
    خطوة التجميع تُنفَّذ محليًا؛ لا توفر الواجهة البرمجية (API) نقطة نهاية مباشرة من JSON إلى CSV.

  2. تحميل ملف CSV الناتج.

curl -X GET "https://api.aspose.cloud/v3.0/barcode/storage/file/output.csv" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o data/output.csv

للحصول على قائمة كاملة بالمعلمات، راجع وثائق API الرسمية.

إعداد البيئة

لبدء الترميز، تحتاج إلى بيئة تشغيل PHP (الإصدار 7.4 أو أحدث) وحساب Aspose.BarCode Cloud صالح.

composer require aspose-barcode-cloud

قم بتنزيل حزمة SDK من صفحة الإصدار الرسمية: Aspose.BarCode Cloud SDK for PHP Download. بعد التثبيت، أنشئ ملف config.php يحتوي على APP_SID و APP_KEY الخاصين بك.

تحسين أداء معالجة JSON الكبيرة

  1. تدفق ملف JSON - قراءة السطر بسطر بدلاً من تحميل الملف بالكامل في الذاكرة.
  2. إعادة استخدام مثيل BarCodeApi - إنشاء عميل جديد لكل سجل يضيف عبئًا إضافيًا.
  3. تحديد دقة الباركود - 300 dpi كافية لمعظم التقارير؛ القيم الأقل تقلل حجم الحمولة.
  4. كتابة صفوف CSV على دفعات - تخزين مؤقت لعدد قليل من الصفوف قبل استدعاء fputcsv لتقليل عمليات الإدخال/الإخراج على القرص.

نصائح عملية لتحويل JSON إلى CSV بكفاءة

  • استخدم الفاصلة المنقوطة (;) أو علامة الجدولة (\t) كفاصل عندما قد تحتوي بياناتك على فواصل.
  • شفر الأحرف غير ASCII باستخدام UTF‑8 وأضف BOM (\xEF\xBB\xBF) في البداية لضمان توافق Excel.
  • احفظ صور الباركود كسلاسل Base64 داخل ملف CSV للحفاظ على الملف مكتفٍ ذاتيًا.
  • نظّف مجلد الباركود المؤقت بعد كل تشغيل لتجنب فوضى القرص.
  • تحقق من صحة سطور JSON باستخدام json_last_error() لتجاوز السجلات المشوهة بسلاسة.

الخلاصة

هذا الدليل أرشدك خلال مثال كامل لتحويل JSON إلى CSV باستخدام PHP باستخدام Aspose.BarCode Cloud SDK for PHP. تعلمت كيفية تكوين SDK، إنشاء الباركود لكل سجل، التعامل مع الفواصل المخصصة وترميز UTF‑8، وتطبيق تحسينات الأداء لمجموعات البيانات الكبيرة. SDK هو منتج تجاري؛ يمكنك شراء ترخيص للاستخدام في الإنتاج أو الحصول على ترخيص مؤقت من صفحة الترخيص المؤقت لتقييم المكتبة. ابدأ بدمج الكود اليوم وسهّل عمليات تبادل البيانات الخاصة بك.

الأسئلة المتكررة

س: كيف يتعامل مثال كود JSON إلى CSV في PHP مع الكائنات المتداخلة؟
ج: يتم تحويل المصفوفات أو الكائنات المتداخلة إلى سلسلة JSON باستخدام json_encode قبل كتابتها إلى ملف CSV، مما يضمن بقاء CSV مسطحًا مع الحفاظ على البيانات الأصلية. لمزيد من التفاصيل، راجع Aspose.BarCode Cloud SDK for PHP documentation.

Q: هل يمكنني تغيير الفاصل بين القيم في ملف CSV في سكريبت تحويل JSON إلى CSV في PHP؟
A: نعم، قم بتعديل المتغير $delimiter في أعلى السكريبت (مثلاً، اضبطه على ',' للحصول على ملف مفصول بفواصل). السكريبت يدعم أي فاصل أحادي الأحرف تقوم بتحديده.

Q: هل هناك طريقة لمعالجة آلاف سجلات JSON بكفاءة؟
A: بالتأكيد. يوصي قسم الأداء في البرنامج التعليمي ببث ملف الإدخال، وإعادة استخدام عميل API، وكتابة الصفوف على دفعات. تقلل هذه التقنيات من استهلاك الذاكرة وتسرّع معالجة ملفات JSON الكبيرة.

س: هل تدعم أداة تحويل JSON إلى CSV في PHP صيغ باركود أخرى؟
ج: يمكن تعيين المتغير $barcodeFormat إلى أي رموز مدعومة من قبل Aspose.BarCode، مثل QR أو DataMatrix أو Code39. ما عليك سوى تحديث القيمة قبل تشغيل السكريبت.

اقرأ المزيد