PclZip使用指南

关于PKZIP文档

每一个PKZIP文档都由一个PclZip对象表示，当创建一个PclZip文档时(基于PclZip对象)，文档的名称将和对象关联。这时候，文档还没有被检查，也没有被读取，它甚至还不存在。

require_once('pclzip.lib.php');
$archive = new PclZip("archive.zip");

接下来文档将被PclZip对象的公共方法操作。当文档不存在时，要创建一个文档，必须使用‘create()’方法，该文档包含的文件列表和相关文件夹将作为该方法的参数。

如果文档已经存在，它的内容可以通过方法‘listContent()’或者‘extract()’来读取。

参数与变量

每一个方法都拥有自己的参数，方法声明中有关于它们的描述。这次参数可能是强制的也可能是可选的。例如：

require_once('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$v_list = $archive->add('dev/file.txt',PCLZIP_OPT_REMOVE_PATH, 'dev');
 

这里的第一个参数'dev/file.txt'，是强制的，而‘PCLZIP_OPT_REMOVE_PATH, ...’则是可选的。

一些方法也可以仅仅只使用一些可选的参数：

$list  =  $archive->extract(PCLZIP_OPT_PATH, "folder",
PCLZIP_OPT_REMOVE_PATH, "data",
PCLZIP_CB_PRE_EXTRACT, "callback_pre_extract",
PCLZIP_CB_POST_EXTRACT, "callback_post_extract");

这里，文件将被解压缩到‘folder’目录，而'data'目录将被移除。

在从文档解压缩每一个单独的文件之前，你也可以调用一个用户自定义的回调函数，(这里是‘callback_pre_extract()’）。这个函数可以在解压缩过程中改变解压路径和文件名，或者跳过这个特定的文件（不解压该文件）。

在一个文件解压完毕时，另一个回调函数将被调用，该函数将使得在解压下一个文件之前，用户可以对当前文件采取某些操作。

$list = $archive->extract(PCLZIP_OPT_PATH, "folder" ,PCLZIP_OPT_REMOVE_ALL_PATH);

这里文件将被解压到'folder'目录，并且所有被存储的文件路径将被移除，即使它们是不同的路径。通过这个特性，用户不需要指定需要被移除的解 压路径。（即压缩文档中如果含有目录data，那么文件夹中的文件将被直接解压到folder目录，解压缩后data目录将被删除）

这些简单的例子展示了这些可选参数如何工作，他们还有更好的用处(当前会有点复杂)。他们可以让新特性的介绍变得很容易，而不用去改变方法声明。

预定义参数，他们的使用方法和相关限制在“可选参数” 一节有详细介绍。在对每个方法的描述中，将给出可选参数的列表。

返回值

每个方法的返回值可能不同，在方法声明中有描述。

但是绝大多数方法在错误时都返回0（设置了错误标识时），成功时返回一个包含文件信息的数组。

数组的每个数据都描述一个文件或者目录，一些的文件/目录的属性和最后一次操作文件/目录后的状态。

每个文件都通过以下参数来描述：

filename

文件的名称

它是方法被调用时所给予的名字。

解压缩时，它是文件被解压缩后的真实名称（而不是存储在文档中的名称）。

stored_filename

文件被存储的名称。

size

文件的真实大小

compressed_size

压缩文档中的大小

mtime

文档的最后修改日期和时间（UNIX timestamp）

comment

与文件相关的摘要

folder

true | false ：表明文件名是一个文件还是一个目录。

index

文件在文档中的索引（如果已设置）。

content

已解压文件的内容，只有当参数TPCLZIP_OPT_EXTRACT_IN_STRING 设置时呈现

status

操作导致的结果（依赖于操作类型）

可选值有：

ok

操作成功。

filtered

文件或目录没有被解压（被用户过滤）。

already_a_directory

文件没有被解压，因为一个同名文件夹已经存在。

newer_exist

文件没有被解压，因为一个同名文件已经存在并且被写保护。

write_protected

文本没有被解压，因为一个较新的文件存在。

path_creation_fail

文本没有被解压，因为当创建路径是发生错误。

write_error

文本没有被解压，因为在写操作时发送错误。

read_error

文本没有被解压，因为在读操作时发生错误。

invalid_header

文本没有被解压，因为文件头损坏。

skipped

文本没有被解压或添加，因为一个用户回调函数请求跳过它。
(1.3版中有介绍)

filename_too_long

文本没有被添加，因为文件名过长。（最大255个字符）。
(1.3版中有介绍)