Prev
Version |
ExcelExplorer Manual |
Next
ExploreString |
 |
(ExcelExplorer 4.0)
Read data from a binary Excel file.
integer ExploreFile( string $excel_file_name [, array $options = array()] )
Parameters
- string $excel_file_name
- Name or full path to the Excel file need to be explored.
- array $options
- Exploring options (see below).
Description
In order to access data stored in Excel file you MUST call this method
(or, alternatively, ExploreString())
BEFORE using any other methods that works with Excel data (worksheets, cells, styles, etc.).
Returns one of the following values that indicate if file explored successfully or not:
| Error code |
Description |
| EE_OK |
Exploring done without error. |
| EE_INVFILE |
File corrupted or not in Excel 5.0 and above format. |
| EE_INVVER |
Unknown Excel file version. |
| EE_FILENOTFOUND |
File open fails. |
Notes
- You don't need to open or close a file by yourself - it will be done automatically during ExcelExplorer object destruction or another file passed to this method.
- This method provides memory_safe option that unavailable in ExploreString() method.
Options gives you the ability to control what data will be readed from an Excel file (except memory-safe option, which described below).
It can be used to maximize efficiency or Excel file processing.
If $options is set, it contains associative array or all needed options - keys as option name, and a values as option value (see examples how to use it).
You can set as many options as you wish - all other will set to their default values.
| Option |
Type |
Description |
| read_filter |
int |
Since ExcelExplorer 4.1 this option controls what data will be readed.
The value combined from the possible constants, described below, using bitwise OR operation.
| Constant |
Description |
| EE_READ_SHEETSINFO |
Only worksheets info (title, type, visibility, etc) will be readed from an Excel file. Useful when you need only to extract worksheet names for example. |
| EE_READ_SHEETSDATA |
Read worksheets info and data (cell values, styles, etc.) |
| EE_READ_IMAGES |
Read images from Excel file |
| EE_READ_SUMMARY |
Read summary information (see SummaryInformation() method description) |
| EE_READ_ALL |
Read all available data. Equals to EE_READ_SHEETSINFO | EE_READ_SHEETSDATA | EE_READ_IMAGES | EE_READ_SUMMARY |
If option is not set EE_READ_ALL mask will be used.
|
| read_only_sheets_info |
boolean |
This option is obsolete. Since ExcelExplorer 4.1 this option replaced by EE_READ_SHEETSINFO mask for read_filter.
This option remains only for backward compatibility.
If TRUE then only worksheets info (title, type, visibility, etc) will be readed from an Excel file. Useful when you need only to extract worksheet names for example.
Default value: FALSE
Note: if this option is set to TRUE all other options has no effect. |
| explore_sheet |
int |
If set, then data from the specified worksheet only will be readed.
Otherwise data from all worksheets will be readed.
NOTES
- If it set and no worksheet with such index is defined then this method will not read data from any worksheet.
- Regardless of this option all information about all worksheets such as titles, types, visibility will be readed. WorksheetsNum() method always returns actual number of worksheets in the file.
- If data readed for one worksheet all other worksheets is considered as defined, but empty.
- All information about styles, fonts and formats will be readed regardless of this option.
- In order to read data from another worksheet use ExploreWorksheet() method.
|
| read_font |
boolean |
Set this to FALSE if you don't need to read info about cell fonts.
Default value: TRUE |
| read_format |
boolean |
Set this to FALSE if you don't need to read info about cell formats.
Default value: TRUE |
| read_align |
boolean |
Set this to FALSE if you don't need to read info about cell alignment.
Default value: TRUE |
| read_bgcolor |
boolean |
Set this to FALSE if you don't need to read info about cell background color.
Default value: TRUE |
| read_border |
boolean |
Set this to FALSE if you don't need to read info about cell borders.
Default value: TRUE |
| read_formula |
boolean |
Set this to FALSE if you don't need to read data from cells that contains the formula.
Default value: TRUE |
| read_link |
boolean |
Set this to FALSE if you don't need to read info about hyperlinks.
Default value: TRUE |
| read_shape |
boolean |
Set this to FALSE if you don't need to read info about shapes.
Default value: TRUE |
| Option |
Type |
Description |
| memory_safe |
boolean |
If TRUE then ExcelExplorer will operate in memory-safe mode. Otherwise it operates in normal mode.
Default value: FALSE |
Another important ability of ExcelExplorer is to operate in memory-limited enviroment.
In normal mode all readed data will be stored in internal class structures and will be accessible via class methods.
In memory-safe mode most of all data will be readed on-the-fly when it needed, e.g. when using class methods to read cells data.
ExcelExplorer operating in memory-safe mode allows you to read data from huge Excel files, that cannot be readed in normal mode because of memory limitations.
But it still require some memory to store critical data.
Note that in this mode ExcelExplorer uses an internal caching mechanism and uses Excel indexing structures, that increases speed. However it works slower than in normal mode.
IMPORTANT! Do not modify Excel file while working with it in memory-safe mode.
1. Read only worksheets info in memory-safe mode
<?php
$filename = 'Test.xls';
$options = array(
'read_filter' => EE_READ_SHEETSINFO,
'memory_safe' => true
);
$result = $ee->ExploreFile($filename,$options);
switch( $result ) {
case EE_OK:
break;
case EE_INVFILE:
die("File corrupted or not in Excel 5.0 and above format");
case EE_INVVER:
die("Unknown Excel file version");
case EE_FILENOTFOUND:
die("Cannot open file");
default:
die("Unknown error");
}
// print worksheets number
echo $ee->WorksheetsNum();
?>
2. Read data from second worksheet except fonts
<?php
$filename = 'Test.xls';
$options = array(
'explore_sheet' => 1,
'read_font' => false
);
$result = $ee->ExploreFile($filename,$options);
switch( $result ) {
case EE_OK:
break;
case EE_INVFILE:
die("File corrupted or not in Excel 5.0 and above format");
case EE_INVVER:
die("Unknown Excel file version");
case EE_FILENOTFOUND:
die("Cannot open file");
default:
die("Unknown error");
}
// print defined rows number in this worksheet
if( $area = $ee->Worksheet(1)->DefinedArea() ) {
echo $area->Height();
}
?>
3. Read all data but images
<?php
$filename = 'Test.xls';
$options = array(
'read_filter' => EE_READ_ALL ^ EE_READ_IMAGES
);
$result = $ee->ExploreFile($filename,$options);
switch( $result ) {
case EE_OK:
break;
case EE_INVFILE:
die("File corrupted or not in Excel 5.0 and above format");
case EE_INVVER:
die("Unknown Excel file version");
case EE_FILENOTFOUND:
die("Cannot open file");
default:
die("Unknown error");
}
// print defined rows number in this worksheet
if( $area = $ee->Worksheet(1)->DefinedArea() ) {
echo $area->Height();
}
?>
|
