用于excel的剖析[PHPExcelParser_ReadMe]

       Excel Parser Professional
       excal 剖析者

INSTALLATION
安装
------------

To install and use this script you need only installed and properly configured
PHP. Script was tested on PHP vesion >= 4.3.x.
要安装和使用这个脚本你的的配置必须要适应以下要求
你的PHP版本要在4.3以下

DESCRIPTION
描述
-----------

This parser can import data from Excel file versions from Excel 5.0 to Excel 2000 and XP.
这个工具能够从excel文件内（版本必须是5.0以上的）转换成为输出流
Only string and numbers will be imported.
但是他只会输出字符与数字
String can be in compressed unicode (8-bits per character) or uncompressed unicode (16-bits per character) formats.
字符将出会被压缩成为unicode编码或是其它编码格式

NEW OBJECT CREATION
创建一个新的对像
-------------------

requires 'excelparser.php';//导入类库文件

$excel = new ExcelFileParser( $logfilename, $logtype );//实例类

$logfilename - optional parameter (filename for debug logging). Default value - empty string, no logging.
//参数选项：日志文件名
$logtype - log severity. Default value ABC_NO_LOG - disable logging.
//生成日志类型，默认是没有
   Log type can be one of the following:
   //日志类型将会从下面挑选
    ABC_CRITICAL
    ABC_ERROR
    ABC_ALERT
    ABC_WARNING
    ABC_NOTICE
    ABC_INFO
    ABC_DEBUG
    ABC_TRACE
    ABC_VAR_DUMP
    ABC_NO_LOG
   Bitwise combination of these flags is not allowed.
   You can use only one of them.

Two methods are used for processing Excel data:
//有两个方法用于剖析excel数据
 ParseFromFile( $filename )
  This function is optimized for memory usage, but the script takes more times
  to be completely executed and to parse the selected data. Use with large files.
  这个函数适于放在内存中使用，他将会花更多的时间在内存中完全执行并且剖析挑选好的数据。
  
 ParseFromString( $contents )
  This function is not optimized for memory usage, but the script takes less times
  to be completely executed and to parse the selected data. Use when parsing speed
  is critical (PHP memory limit can be exceed for huge files and script will terminate!). 
  这个函数并不怎么适合在内存中运行，但是这个脚本只需要花一小会的时间去剖析挑选好了的数据，在关键的时候你非常适

合去用他，PHP内存可能会因为所大的文件而超时（下一句不知道啥意思了，感觉前后不对应呀）

Examples:
$error_code = $excel->ParseFromFile($filename)

$fd = fopen( $filename, 'rb');
$content = fread ($fd, filesize ($name));
fclose($fd);
$error_code = $excel->ParseFromString($content);
unset( $content, $fd );

Errors codes:
//错误代码对应表
 0 - no errors//没有错误
 1 - file read error//文件读取失败
 2 - file is too small to be an Excel file//做为excel文件来说，他太小了（不是excel文件）
 3 - Excel file head read error//EXCEL文件读取错误
 4 - file read error//文件读取错误
 5 - not Excel file or Excel version earlier than Excel 5.0//没有excel文件或是他的版本太低
 6 - corrupted file//文件损坏
 7 - data not found//数据没有找到
 8 - unknown file version//不知道文件版本

Note: Error 7 is displayed when no Excel data is found in OLE2 file format (like MS Word)

OBJECT FIELDS
//好像是成员变量的意思吧
--------------

int $excel->biff_version
Excel file BIFF version (7 = Excel 5-7, 8 = 2000, 10 = XP)
//这个execl文件的版本号

array $excel->worksheet
An array, containing lists data
//返回列表数据

array $excel->format
An array, containing data about the styles used to format cell
//返回数组，定制数据格式（可能是定义字段或是什么取得数据吧）

TABLES
------

$worksheet_number = Excel worksheet number - to view the quantity of accessible worksheets,
use count($excel->worksheet['name'])

boolean $excel->worksheet['unicode'][$worksheet_number]
If the data is saved in uncompressed unicode, then ithis field has TRUE value, FALSE is used for compressed unicode

string $excel->worksheet['name'][$worksheet_number]
Worksheet name in compressed or uncompressed unicode

int $excel->worksheet['data'][$worksheet_number]['biff_version']
BIFF list version

COLUMNS
-------

array $exc->worksheet['data'][$worksheet_number]['cell']
An array containing the cells data for the chosen worksheet.

$row = row number (begins from 0)
$col = column number (begins from 0)
In Excel the columns have names as 'A', 'B', 'C', etc

int $exc->worksheet['data'][$worksheet_number]['max_row']
Maximum row number (! but not maximum row quantity!). For example, the list has data in rows 1,3,8 - maximum value 8,

quantity of rows- 3

int $exc->worksheet['data'][$worksheet_number]['max_col']
Maximum column number (the same as for rows, see supra)

int $exc->worksheet['data'][$worksheet_number]['cell'][$row][$col]['type']
The data type, contained in the cell:

0 - string
1 - integer
2 - float
3 - date

mixed $exc->worksheet['data'][$worksheet_number]['cell'][$row][$col]['data']
if data type is 0, cell contains string index in SST
if data type is 1, cell contains integer
if data type is 2, cell contains float
if data type is 3, cell contains date in Excel presentation

int $exc->worksheet['data'][$worksheet_number]['cell'][$row][$col]['font'] -
contains the index of font used in the cell

FONTS
-----

The fonts that are used in workbook are stored in $excel->fonts array.
They look in the following way:

$font = $excel->fonts[$index];

$font['size'] - font size in points
$font['italic']   - is font italic true/false
$font['strikeout'] is font strikeout true/false
$font['bold']      is font bold true/false  
$font['script']  -  may have the following constant values:
   XF_SCRIPT_NONE - normal font.
   XF_SCRIPT_SUPERSCRIPT - SUPERSCRIPT inscription is set.
   XF_SCRIPT_SUBSCRIPT - SUPERSCRIPT inscription is set.
    
$font['underline']  - may have the following constant values:
   XF_UNDERLINE_NONE - normal font.
   XF_UNDERLINE_SINGLE - single underlining is set.
   XF_UNDERLINE_DOUBLE - double underlining is set.
    XF_UNDERLINE_SINGLE_ACCOUNTING - underline single accounting is set.
   XF_UNDERLINE_DOUBLE_ACCOUNTING - underline double accounting is set.
$font['name']    - fonts name.

Shared String Table (SST):
--------------------------
All string data is saved in this table to optimize the memory use of computer. The cells do not contain the strings itself,

but the strings indexs in this table.

The access to the indexs is performed by:

if( $excel->worksheet['data'][$worksheet_number]['cell'][$row][$col]['type'] == 0 )
{
$ind = $exc->worksheet['data'][$worksheet_number]['cell'][$row][$col]['data'];
}

array $excel->sst
An array, containing strings

boolean $excel->sst['unicode'][$ind]
Logical value, showing whether the data is presented in uncompressed
(TRUE) or compressed (FALSE) unicode

string $excel->sst['data'][$ind]
String data

DATE
----

The date is saved in Excel format - (the number of days starting from year 1900)
and might be converted in timestamp

$excel->xls2tstamp($xlsdate)

You may work with returned data using common unix timestamp
and format it with standart toolset for date in PHP.
Because on the Windows platform the minimum timestamp value
(null second) is 1,1,1970 this function processes correctly only
the following dates.

If you need to process the earlier data, then use the function:

$ret = $excel->getDateArray($xlsdate);

where:

$ret['day']   = day of month.
$ret['month'] = month.
$ret['year']  = year.

DEBUG
------
In order to make parser to write a logfile - the class must be created with the following parameters:
ExcelFileParser('logfile.txt',LOG_LEVEL);

LOG_LEVEL may have the following values:
 
ABC_CRITICAL
ABC_ERROR  
ABC_ALERT
ABC_WARNING
ABC_NOTICE
ABC_INFO
ABC_DEBUG
ABC_TRACE
ABC_VAR_DUMP

The lower the level, the more messages will be put in log by parser.

With ABC_NO_LOG - no logging will performed.

EXAMPLE
-------

 See sample.php file for working example.

THINGS MISSED IN THIS RELEASE
-----------------------------

There is some restrictions in parser. In this version hidden flag of columns,
rows and worksheets are not processed. Parser not understanding some cell formats
for now. Author plans to add this things in future versions.

BUGS
----
Waiting for your comments :)