xlsx reader

قارئ xlsx

يعد xlsx-reader امتدادًا لقارئ جداول البيانات الذي يستهدف XLSX والذي يعد جزءًا من قارئ جداول البيانات.

فهو يوفر وظيفة لقراءة البيانات الموجودة في ملف XLSX المحدد بكفاءة.

ينصب تركيز هذه المكتبة على تسليم البيانات الموجودة في خلايا جدول بيانات XLSX، وليس على نمط المستند. وعلى هذا النحو، لا تقدم المكتبة أي دعم لإمكانيات XLSX التي ليست ضرورية لتحقيق هذا الهدف. يتم دعم تنسيق قيمة الخلية الأساسية ووظائف السلسلة المشتركة فقط.

متطلبات

• PHP 7.1.0 أو أحدث، مع تمكين الميزات الاختيارية التالية على الأقل:
  • الرمز البريدي (راجع http://php.net/manual/en/zip.installation.php)
  • XMLReader (راجع http://php.net/manual/en/xmlreader.installation.php)

التثبيت باستخدام الملحن

الحزمة متاحة على Packagist. يمكنك تثبيته باستخدام Composer.

 composer require aspera/xlsx-reader

الاستخدام

تتم قراءة كافة البيانات من الملف بالتسلسل، مع إرجاع كل صف كمصفوفة من الأعمدة.

 <?php
use Aspera  Spreadsheet  XLSX  Reader ;

$ reader = new Reader ();
$ reader -> open ( ' example.xlsx ' );

foreach ( $ reader as $ row ) {
    print_r ( $ row );
}

$ reader -> close ();

يتم أيضًا دعم ملفات XLSX التي تحتوي على أوراق عمل متعددة. تقوم الطريقة getSheets() بإرجاع مصفوفة تحتوي على فهارس الأوراق كمفاتيح وكائنات ورقة العمل كقيم. يتم استخدام طريقة ChangeSheet($index) للتبديل بين الأوراق المراد قراءتها.

 <?php
use Aspera  Spreadsheet  XLSX  Reader ;

$ reader = new Reader ();
$ reader -> open ( ' example.xlsx ' );

$ sheets = $ reader -> getSheets ();
foreach ( $ sheets as $ index => $ sheet_data ) {
    $ reader -> changeSheet ( $ index );
    echo ' Sheet # ' . $ index . ' : ' . $ sheet_data -> getName ();

    // Note: Any call to changeSheet() resets the current read position to the beginning of the selected sheet.
    foreach ( $ reader as $ row_number => $ row ) {
        echo ' Row # ' . $ row_number . ' : ' . print_r ( $ row , true );
    }
}

$ reader -> close ();

يمكن تحديد خيارات لضبط سلوك القارئ ومخرجاته عبر مثيل ReaderConfiguration.

للحصول على قائمة كاملة بالخيارات المدعومة وتأثيراتها، راجع وثائق التعليمات البرمجية الخاصة بـ ReaderConfiguration.

 <?php
use Aspera  Spreadsheet  XLSX  Reader ;
use Aspera  Spreadsheet  XLSX  ReaderConfiguration ;
use Aspera  Spreadsheet  XLSX  ReaderSkipConfiguration ;

$ reader_configuration = ( new ReaderConfiguration ())
  -> setTempDir ( ' C:/Temp/ ' )
  -> setSkipEmptyCells ( ReaderSkipConfiguration :: SKIP_EMPTY )
  -> setReturnDateTimeObjects ( true )
  -> setCustomFormats ( array ( 20 => ' hh:mm ' ));
// For a full list of supported options and their effects, consult the in-code documentation of ReaderConfiguration.

$ spreadsheet = new Reader ( $ reader_configuration );

ملاحظات حول أداء المكتبة

تستخدم ملفات XLSX ما يسمى "السلاسل المشتركة" لتحسين أحجام الملفات في الحالات التي تتكرر فيها نفس السلسلة عدة مرات. بالنسبة للمستندات الأكبر حجمًا، يمكن أن تصبح قائمة السلاسل المشتركة هذه كبيرة جدًا، مما يتسبب إما في اختناقات في الأداء أو استهلاك كبير للذاكرة عند تحليل المستند.

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

لتكوين هذا السلوك بالتفصيل، على سبيل المثال لزيادة مقدار الذاكرة المتاحة للقارئ، يمكن إرفاق مثيل SharedStringsConfiguration بمثيل ReaderConfiguration المقدم إلى مُنشئ القارئ.

للحصول على قائمة كاملة بالخيارات المدعومة وتأثيراتها، راجع وثائق التعليمات البرمجية الخاصة بـ SharedStringsConfiguration.

 <?php
use Aspera  Spreadsheet  XLSX  Reader ;
use Aspera  Spreadsheet  XLSX  ReaderConfiguration ;
use Aspera  Spreadsheet  XLSX  SharedStringsConfiguration ;

$ shared_strings_configuration = ( new SharedStringsConfiguration ())
    -> setCacheSizeKilobyte ( 16 * 1024 )
    -> setUseOptimizedFiles ( false );
// For a full list of supported options and their effects, consult the in-code documentation of SharedStringsConfiguration.

$ reader_configuration = ( new ReaderConfiguration ())
  -> setSharedStringsConfiguration ( $ shared_strings_configuration );

$ spreadsheet = new Reader ( $ reader_configuration );

ملاحظات حول الميزات غير المدعومة

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

وعلى وجه الخصوص، ينبغي ملاحظة ما يلي فيما يتعلق بالميزات غير المدعومة:

• يتم تجاهل عرض خلية العرض. ونتيجة لذلك، في الحالات التي يقوم فيها محررو xlsx المشهورون بتقصير القيم باستخدام التدوين العلمي أو "#####" - العناصر النائبة، سيرجع القارئ قيمًا غير مختصرة بدلاً من ذلك.
• الملفات التي تحتوي على ملفات سلاسل مشتركة داخلية متعددة غير مدعومة.
• الملفات التي تحتوي على ملفات تعريف أنماط داخلية متعددة غير مدعومة.
• الكسور مدعومة جزئيًا فقط. قد تكون النتائج التي يقدمها القارئ مختلفة قليلاً عن المدخلات الأصلية.

الترخيص

جميع الأكواد الموجودة في هذه المكتبة مرخصة بموجب ترخيص MIT كما هو مضمن في ملف LICENSE.md.