每一个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版中有介绍)