fast excel reader
v2.22.1
يعد FastExcelReader جزءًا من مشروع FastExcelPhp الذي يتكون من
تم تصميم هذه المكتبة لتكون خفيفة الوزن وفائقة السرعة وتتطلب الحد الأدنى من استخدام الذاكرة.
يستطيع FastExcelReader قراءة جداول البيانات المتوافقة مع Excel بتنسيق XLSX (Office 2007+). فهو يقرأ البيانات فقط، ولكنه يفعل ذلك بسرعة كبيرة وباستخدام الحد الأدنى من الذاكرة.
سمات
استخدم composer لتثبيت FastExcelReader في مشروعك:
composer require avadim/fast-excel-reader
انتقل إلى:
يمكنك العثور على المزيد من الأمثلة في المجلد /demo
use avadim FastExcelReader Excel ;
$ file = __DIR__ . ' /files/demo-00-simple.xlsx ' ;
// Open XLSX-file
$ excel = Excel:: open ( $ file );
// Read all values as a flat array from current sheet
$ result = $ excel -> readCells ();سوف تحصل على هذه المصفوفة:
Array
(
[A1] => 'col1'
[B1] => 'col2'
[A2] => 111
[B2] => 'aaa'
[A3] => 222
[B3] => 'bbb'
)
// Read all rows in two-dimensional array (ROW x COL)
$ result = $ excel -> readRows ();سوف تحصل على هذه المصفوفة:
Array
(
[1] => Array
(
['A'] => 'col1'
['B'] => 'col2'
)
[2] => Array
(
['A'] => 111
['B'] => 'aaa'
)
[3] => Array
(
['A'] => 222
['B'] => 'bbb'
)
)
// Read all columns in two-dimensional array (COL x ROW)
$ result = $ excel -> readColumns ();سوف تحصل على هذه المصفوفة:
Array
(
[A] => Array
(
[1] => 'col1'
[2] => 111
[3] => 222
)
[B] => Array
(
[1] => 'col2'
[2] => 'aaa'
[3] => 'bbb'
)
)
$ sheet = $ excel -> sheet ();
foreach ( $ sheet -> nextRow () as $ rowNum => $ rowData ) {
// $rowData is array ['A' => ..., 'B' => ...]
$ addr = ' C ' . $ rowNum ;
if ( $ sheet -> hasImage ( $ addr )) {
$ sheet -> saveImageTo ( $ addr , $ fullDirectoryPath );
}
// handling of $rowData here
// ...
}
// OR
foreach ( $ sheet -> nextRow () as $ rowNum => $ rowData ) {
// handling of $rowData here
// ...
// get image list from current row
$ imageList = $ sheet -> getImageListByRow ();
foreach ( $ imageList as $ imageInfo ) {
$ imageBlob = $ sheet -> getImageBlob ( $ imageInfo [ ' address ' ]);
}
}
// OR
foreach ( $ sheet -> nextRow ([ ' A ' => ' One ' , ' B ' => ' Two ' ], Excel:: KEYS_FIRST_ROW ) as $ rowNum => $ rowData ) {
// $rowData is array ['One' => ..., 'Two' => ...]
// ...
}طريقة بديلة لقراءة صف بعد صف
// Init internal read generator
$ sheet -> reset ([ ' A ' => ' One ' , ' B ' => ' Two ' ], Excel:: KEYS_FIRST_ROW );
// read the first row
$ rowData = $ sheet -> readNextRow ();
var_dump ( $ rowData );
// read the next 3 rows
for ( $ i = 0 ; $ i < 3 ; $ i ++) {
$ rowData = $ sheet -> readNextRow ();
var_dump ( $ rowData );
}
// Reset internal generator and read all rows
$ sheet -> reset ([ ' A ' => ' One ' , ' B ' => ' Two ' ], Excel:: KEYS_FIRST_ROW );
$ result = [];
while ( $ rowData = $ sheet -> readNextRow ()) {
$ result [] = $ rowData ;
}
var_dump ( $ result ); // Read rows and use the first row as column keys
$ result = $ excel -> readRows ( true );سوف تحصل على هذه النتيجة:
Array
(
[2] => Array
(
['col1'] => 111
['col2'] => 'aaa'
)
[3] => Array
(
['col1'] => 222
['col2'] => 'bbb'
)
)
تحدد الوسيطة الثانية الاختيارية مفاتيح صفيف النتائج
// Rows and cols start from zero
$ result = $ excel -> readRows ( false , Excel:: KEYS_ZERO_BASED );سوف تحصل على هذه النتيجة:
Array
(
[0] => Array
(
[0] => 'col1'
[1] => 'col2'
)
[1] => Array
(
[0] => 111
[1] => 'aaa'
)
[2] => Array
(
[0] => 222
[1] => 'bbb'
)
)
القيم المسموح بها لوضع النتيجة
| خيارات الوضع | الأوصاف |
|---|---|
| المفاتيح_الأصلية | صفوف من '1'، أعمدة من 'A' (افتراضي) |
| KEYS_ROW_ZERO_BASED | صفوف من 0 |
| KEYS_COL_ZERO_BASED | الأعمدة من 0 |
| KEYS_ZERO_BASED | الصفوف من 0، والأعمدة من 0 (مثل KEYS_ROW_ZERO_BASED + KEYS_COL_ZERO_BASED) |
| KEYS_ROW_ONE_BASED | صفوف من 1 |
| KEYS_COL_ONE_BASED | الأعمدة من 1 |
| KEYS_ONE_BASED | صفوف من 1، أعمدة من 1 (مثل KEYS_ROW_ONE_BASED + KEYS_COL_ONE_BASED) |
الخيارات الإضافية التي يمكن دمجها مع أوضاع النتيجة
| خيارات | الأوصاف |
|---|---|
| KEYS_FIRST_ROW | وهو نفس الصحيح في الحجة الأولى |
| المفاتيح_النسبية | فهرس من الخلية العلوية اليسرى للمنطقة (وليس ورقة) |
| KEYS_SWAP | مبادلة الصفوف والأعمدة |
على سبيل المثال
$ result = $ excel -> readRows ([ ' A ' => ' bee ' , ' B ' => ' honey ' ], Excel:: KEYS_FIRST_ROW | Excel:: KEYS_ROW_ZERO_BASED );سوف تحصل على هذه النتيجة:
Array
(
[0] => Array
(
[bee] => 111
[honey] => 'aaa'
)
[1] => Array
(
[bee] => 222
[honey] => 'bbb'
)
)
تتخطى المكتبة بالفعل الخلايا الفارغة والصفوف الفارغة بشكل افتراضي. الخلايا الفارغة هي خلايا لا يُكتب فيها أي شيء، والصفوف الفارغة هي صفوف تكون جميع الخلايا فيها فارغة. إذا كانت الخلية تحتوي على سلسلة فارغة، فلا تعتبر فارغة. ولكن يمكنك تغيير هذا السلوك وتخطي الخلايا ذات السلاسل الفارغة.
$ sheet = $ excel -> sheet ();
// Skip empty cells and empty rows
foreach ( $ sheet -> nextRow () as $ rowNum => $ rowData ) {
// handle $rowData
}
// Skip empty cells and cells with empty strings
foreach ( $ sheet -> nextRow ([], Excel:: TREAT_EMPTY_STRING_AS_EMPTY_CELL ) as $ rowNum => $ rowData ) {
// handle $rowData
}
// Skip empty cells and empty rows (rows containing only whitespace characters are also considered empty)
foreach ( $ sheet -> nextRow ([], Excel:: TRIM_STRINGS | Excel:: TREAT_EMPTY_STRING_AS_EMPTY_CELL ) as $ rowNum => $ rowData ) {
// handle $rowData
}طريقة أخرى
$ sheet -> reset ([], Excel:: TRIM_STRINGS | Excel:: TREAT_EMPTY_STRING_AS_EMPTY_CELL );
$ rowData = $ sheet -> readNextRow ();
// do something
$ rowData = $ sheet -> readNextRow ();
// handle next row
// ... use avadim FastExcelReader Excel ;
$ file = __DIR__ . ' /files/demo-02-advanced.xlsx ' ;
$ excel = Excel:: open ( $ file );
$ result = [
' sheets ' => $ excel -> getSheetNames () // get all sheet names
];
$ result [ ' #1 ' ] = $ excel
// select sheet by name
-> selectSheet ( ' Demo1 ' )
// select area with data where the first row contains column keys
-> setReadArea ( ' B4:D11 ' , true )
// set date format
-> setDateFormat ( ' Y-m-d ' )
// set key for column 'C' to 'Birthday'
-> readRows ([ ' C ' => ' Birthday ' ]);
// read other arrays with custom column keys
// and in this case we define range by columns only
$ columnKeys = [ ' B ' => ' year ' , ' C ' => ' value1 ' , ' D ' => ' value2 ' ];
$ result [ ' #2 ' ] = $ excel
-> selectSheet ( ' Demo2 ' , ' B:D ' )
-> readRows ( $ columnKeys );
$ result [ ' #3 ' ] = $ excel
-> setReadArea ( ' F5:H13 ' )
-> readRows ( $ columnKeys );يمكنك تعيين منطقة القراءة بأسماء محددة في المصنف. على سبيل المثال، إذا قام المصنف بتعريف رؤوس الاسم بالنطاق Demo1!$B$4:$D$4 ، فيمكنك قراءة الخلايا بهذا الاسم
$ excel -> setReadArea ( ' Values ' );
$ cells = $ excel -> readCells ();لاحظ أنه بما أن القيمة تحتوي على اسم الورقة، تصبح هذه الورقة هي الورقة الافتراضية.
يمكنك ضبط منطقة القراءة في الورقة
$ sheet = $ excel -> getSheet ( ' Demo1 ' )-> setReadArea ( ' Headers ' );
$ cells = $ sheet -> readCells ();ولكن إذا حاولت استخدام هذا الاسم على ورقة أخرى، فسوف تحصل على خطأ
$ sheet = $ excel -> getSheet ( ' Demo2 ' )-> setReadArea ( ' Headers ' );
// Exception: Wrong address or range "Values" إذا لزم الأمر، يمكنك التحكم بشكل كامل في عملية القراءة باستخدام طريقة readSheetCallback() مع وظيفة رد الاتصال
use avadim FastExcelReader Excel ;
$ excel = Excel:: open ( $ file );
$ result = [];
$ excel -> readCallback ( function ( $ row , $ col , $ val ) use (& $ result ) {
// Any manipulation here
$ result [ $ row ][ $ col ] = ( string ) $ val ;
// if the function returns true then data reading is interrupted
return false ;
});
var_dump ( $ result ); افتراضيًا، تُرجع جميع قيم التاريخ والوقت كطابع زمني. ولكن يمكنك تغيير هذا السلوك باستخدام dateFormatter()
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> sheet ()-> setReadArea ( ' B5:D7 ' );
$ cells = $ sheet -> readCells ();
echo $ cells [ ' C5 ' ]; // -2205187200
// If argument TRUE is passed, then all dates will be formatted as specified in cell styles
// IMPORTANT! The datetime format depends on the locale
$ excel -> dateFormatter ( true );
$ cells = $ sheet -> readCells ();
echo $ cells [ ' C5 ' ]; // '14.02.1900'
// You can specify date format pattern
$ excel -> dateFormatter ( ' Y-m-d ' );
$ cells = $ sheet -> readCells ();
echo $ cells [ ' C5 ' ]; // '1900-02-14'
// set date formatter function
$ excel -> dateFormatter ( fn ( $ value ) => gmdate ( ' m/d/Y ' , $ value ));
$ cells = $ sheet -> readCells ();
echo $ cells [ ' C5 ' ]; // '02/14/1900'
// returns DateTime instance
$ excel -> dateFormatter ( fn ( $ value ) => ( new DateTime ())-> setTimestamp ( $ value ));
$ cells = $ sheet -> readCells ();
echo get_class ( $ cells [ ' C5 ' ]); // 'DateTime'
// custom manipulations with datetime values
$ excel -> dateFormatter ( function ( $ value , $ format , $ styleIdx ) use ( $ excel ) {
// get Excel format of the cell, e.g. '[$-F400]h:mm:ss AM/PM'
$ excelFormat = $ excel -> getFormatPattern ( $ styleIdx );
// get format converted for use in php functions date(), gmdate(), etc
// for example the Excel pattern above would be converted to 'g:i:s A'
$ phpFormat = $ excel -> getDateFormatPattern ( $ styleIdx );
// and if you need you can get value of numFmtId for this cell
$ style = $ excel -> getCompleteStyleByIdx ( $ styleIdx , true );
$ numFmtId = $ style [ ' format-num-id ' ];
// do something and write to $result
$ result = gmdate ( $ phpFormat , $ value );
return $ result ;
});في بعض الأحيان، إذا تم تحديد تنسيق الخلية كتاريخ ولكنه لا يحتوي على تاريخ، فقد تسيء المكتبة تفسير هذه القيمة. لتجنب ذلك، يمكنك تعطيل تنسيق التاريخ
هنا، تحتوي الخلية B1 على السلسلة "3.2" وتحتوي الخلية B2 على التاريخ 2024-02-03، ولكن تم تعيين كلا الخليتين على تنسيق التاريخ
$ excel = Excel:: open ( $ file );
// default mode
$ cells = $ sheet -> readCells ();
echo $ cell [ ' B1 ' ]; // -2208798720 - the library tries to interpret the number 3.2 as a timestamp
echo $ cell [ ' B2 ' ]; // 1706918400 - timestamp of 2024-02-03
// date formatter is on
$ excel -> dateFormatter ( true );
$ cells = $ sheet -> readCells ();
echo $ cell [ ' B1 ' ]; // '03.01.1900'
echo $ cell [ ' B2 ' ]; // '3.2'
// date formatter is off
$ excel -> dateFormatter ( false );
$ cells = $ sheet -> readCells ();
echo $ cell [ ' B1 ' ]; // '3.2'
echo $ cell [ ' B2 ' ]; // 1706918400 - timestamp of 2024-02-03 // Returns count images on all sheets
$ excel -> countImages ();
// Returns count images on sheet
$ sheet -> countImages ();
// Returns image list of sheet
$ sheet -> getImageList ();
// Returns image list of specified row
$ sheet -> getImageListByRow ( $ rowNumber );
// Returns TRUE if the specified cell has an image
$ sheet -> hasImage ( $ cellAddress );
// Returns mime type of image in the specified cell (or NULL)
$ sheet -> getImageMimeType ( $ cellAddress );
// Returns inner name of image in the specified cell (or NULL)
$ sheet -> getImageName ( $ cellAddress );
// Returns an image from the cell as a blob (if exists) or NULL
$ sheet -> getImageBlob ( $ cellAddress );
// Writes an image from the cell to the specified filename
$ sheet -> saveImage ( $ cellAddress , $ fullFilenamePath );
// Writes an image from the cell to the specified directory
$ sheet -> saveImageTo ( $ cellAddress , $ fullDirectoryPath );تحاول المكتبة تحديد أنواع قيم الخلايا، وفي معظم الحالات تقوم بذلك بشكل صحيح. ولذلك، يمكنك الحصول على قيم رقمية أو سلسلة. يتم إرجاع قيم التاريخ كطابع زمني افتراضيًا. ولكن يمكنك تغيير هذا السلوك عن طريق تحديد تنسيق التاريخ (راجع خيارات التنسيق الخاصة بوظيفة date() php).
$ excel = Excel:: open ( $ file );
$ result = $ excel -> readCells ();
print_r ( $ result );المثال أعلاه سوف يخرج:
Array
(
[B2] => -2205187200
[B3] => 6614697600
[B4] => -6845212800
)
$ excel = Excel:: open ( $ file );
$ excel -> setDateFormat ( ' Y-m-d ' );
$ result = $ excel -> readCells ();
print_r ( $ result );المثال أعلاه سوف يخرج:
Array
(
[B2] => '1900-02-14'
[B3] => '2179-08-12'
[B4] => '1753-01-31'
)
عادةً ما تقوم وظائف القراءة بإرجاع قيم الخلايا فقط، ولكن يمكنك قراءة القيم باستخدام الأنماط. في هذه الحالة، لكل خلية، لن يتم إرجاع قيمة عددية، ولكن سيتم إرجاع مصفوفة مثل ['v' => scalar_value , 's' => style_array , 'f' => Formula ]
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> sheet ();
$ rows = $ sheet -> readRowsWithStyles ();
$ columns = $ sheet -> readColumnsWithStyles ();
$ cells = $ sheet -> readCellsWithStyles ();
$ cells = $ sheet -> readCellsWithStyles ();أو يمكنك قراءة الأنماط فقط (بدون قيم)
$ cells = $ sheet -> readCellStyles ();
/*
array (
'format' =>
array (
'format-num-id' => 0,
'format-pattern' => 'General',
),
'font' =>
array (
'font-size' => '10',
'font-name' => 'Arial',
'font-family' => '2',
'font-charset' => '1',
),
'fill' =>
array (
'fill-pattern' => 'solid',
'fill-color' => '#9FC63C',
),
'border' =>
array (
'border-left-style' => NULL,
'border-right-style' => NULL,
'border-top-style' => NULL,
'border-bottom-style' => NULL,
'border-diagonal-style' => NULL,
),
)
*/
$ cells = $ sheet -> readCellStyles ( true );
/*
array (
'format-num-id' => 0,
'format-pattern' => 'General',
'font-size' => '10',
'font-name' => 'Arial',
'font-family' => '2',
'font-charset' => '1',
'fill-pattern' => 'solid',
'fill-color' => '#9FC63C',
'border-left-style' => NULL,
'border-right-style' => NULL,
'border-top-style' => NULL,
'border-bottom-style' => NULL,
'border-diagonal-style' => NULL,
)
*/لكننا لا ننصح باستخدام هذه الطرق مع الملفات الكبيرة
يمكن أن تحتوي كل ورقة في ملف XLSX الخاص بك على مجموعة من قواعد التحقق من صحة البيانات. لاستردادها، يمكنك استدعاء getDataValidations على الورقة الخاصة بك
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> sheet ();
$ validations = $ sheet -> getDataValidations ();
/*
[
[
'type' => 'list',
'sqref' => 'E2:E527',
'formula1' => '"Berlin,Cape Town,Mexico City,Moscow,Sydney,Tokyo"',
'formula2' => null,
], [
'type' => 'decimal',
'sqref' => 'G2:G527',
'formula1' => '0.0',
'formula2' => '999999.0',
],
]
*/ استرداد عرض عمود معين في الورقة:
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> selectSheet ( ' SheetName ' );
// Get the width of column 1 (column 'A')
$ columnWidth = $ sheet -> getColumnWidth ( 1 );
echo $ columnWidth ; // Example: 11.85 استرداد ارتفاع صف معين في الورقة:
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> selectSheet ( ' SheetName ' );
// Get the height of row 1
$ rowHeight = $ sheet -> getRowHeight ( 1 );
echo $ rowHeight ; // Example: 15 استرداد معلومات جزء التجميد لورقة:
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> selectSheet ( ' SheetName ' );
// Get the freeze pane configuration
$ freezePaneConfig = $ sheet -> getFreezePaneInfo ();
print_r ( $ freezePaneConfig );
/*
Example Output:
Array
(
[xSplit] => 0
[ySplit] => 1
[topLeftCell] => 'A2'
)
*/ استرداد معلومات لون علامة التبويب لورقة:
Copy code
$ excel = Excel:: open ( $ file );
$ sheet = $ excel -> selectSheet ( ' SheetName ' );
// Get the tab color configuration
$ tabColorConfig = $ sheet -> getTabColorInfo ();
print_r ( $ tabColorConfig );
/*
Example Output:
Array
(
[theme] => '2'
[tint] => '-0.499984740745262'
)
*/ يمكنك استخدام الطرق التالية:
Sheet::getMergedCells() - إرجاع كافة النطاقات المدمجةSheet::isMerged(string $cellAddress) - التحقق من دمج الخليةSheet::mergedRange(string $cellAddress) - إرجاع نطاق الدمج للخلية المحددةعلى سبيل المثال
if ( $ sheet -> isMerged ( ' B3 ' )) {
$ range = $ sheet -> mergedRange ( ' B3 ' );
}getSheetNames() - إرجاع مجموعة أسماء جميع الأوراقsheet(?string $name = null) - إرجاع الورقة الافتراضية أو المحددةgetSheet(string $name, ?string $areaRange = null, ?bool $firstRowKeys = false) - الحصول على الورقة بالاسمgetSheetById(int $sheetId, ?string $areaRange = null, ?bool $firstRowKeys = false) - الحصول على الورقة حسب المعرفgetFirstSheet(?string $areaRange = null, ?bool $firstRowKeys = false) - احصل على الورقة الأولىselectSheet(string $name, ?string $areaRange = null, ?bool $firstRowKeys = false) - حدد الورقة الافتراضية حسب الاسم وقم بإرجاعهاselectSheetById(int $sheetId, ?string $areaRange = null, ?bool $firstRowKeys = false) - حدد الورقة الافتراضية حسب المعرف وقم بإعادتهاselectFirstSheet(?string $areaRange = null, ?bool $firstRowKeys = false) - حدد الورقة الأولى كافتراضية وقم بإعادتهاgetDefinedNames() - إرجاع الأسماء المحددة للمصنفname() - إرجاع اسم السلسلةisActive() - ورقة عمل نشطةisHidden() - إذا كانت ورقة العمل مخفيةisVisible() - إذا كانت ورقة العمل مرئيةstate() - إرجاع حالة سلسلة ورقة العمل (المستخدمة في isHidden() و isVisible() )dimension() - يُرجع بُعد منطقة العمل الافتراضية من خصائص الورقةcountRows() - حساب الصفوف من البعدcountColumns() - حساب الأعمدة من البعدfirstRow() - رقم الصف الأولfirstCol() - حرف العمود الأولreadFirstRow() - إرجاع قيم خلايا الصف الأول كمصفوفةreadFirstRowWithStyles() - إرجاع قيم وأنماط خلايا الصف الأول كمصفوفةgetColumnWidth(int) - إرجاع عرض رقم عمود معينgetFreezePaneConfig() - إرجاع مصفوفة تحتوي على تكوين جزء التجميدgetTabColorConfiguration() - إرجاع مصفوفة تحتوي على تكوين لون علامة التبويب إذا وجدت هذه الحزمة مفيدة، يمكنك أن تمنحني نجمة على GitHub.
أو يمكنك التبرع لي :)
