PEAR Archive_Tar类中文文档
===================================
最后更新(译注:英文文档) : 2001-08-15
总览 :
----------
Archive_Tar类帮助创建和管理由GNU ZIP压缩或者非GNU ZIP压缩的GNU TAR格式文件.
该类提供了一些基本函数,象创建压缩包,在压缩包里加入文件,从压缩包中解出文件,以及列出压缩包内容.
它也提供了一些先进的函数允许用路径操作的方式添加和解压文件(译注:就是可以在添加和解压过程中,设定路径).
样例 :
--------
// ----- 创建对象(解压缩)
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
// ----- 创建压缩包
$v_list[0]="file.txt";
$v_list[1]="data/";
$v_list[2]="file.log";
$tar_object->create($v_list);
// ----- 加入文件
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->add($v_list);
// ----- 加入更多的文件
$tar_object->add("release/newfile.log
release/readme.txt");
// ----- 列出内容
if (($v_list = $tar_object->listContent())
!= 0)
for ($i=0;
$i<sizeof($v_list);
$i++)
{
echo "Filename
:'".$v_list[$i][filename]."'<br>";
echo " .size
:'".$v_list[$i][size]."'<br>";
echo " .mtime
:'".$v_list[$i][mtime]."'
(".date("l
dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>";
echo " .mode
:'".$v_list[$i][mode]."'<br>";
echo " .uid
:'".$v_list[$i][uid]."'<br>";
echo " .gid
:'".$v_list[$i][gid]."'<br>";
echo " .typeflag
:'".$v_list[$i][typeflag]."'<br>";
}
// ----- 解压缩到目录"install"
$tar_object->extract("install");
公共参数 :
------------------
无
公共方法 :
----------------
方法 : Archive_Tar($p_tarname, $p_compress = null)
描述 :
Archive_Tar类构造器.这个构造器的作用只是声明一个新的Archive_Tar对象,以tar文件的名称与之关联.
如果设置了compress参数,tar文件就会被读取或者被创建一个gzip或bz2压缩TAR文件.
参数 :
$p_tarname : A valid filename for the tar archive file.
$p_compress : 可以为null, 'gz' 或者 'bz2',出于兼容性上的原因,它也可以为true.该参数指明是否需要gzip或者bz2压缩.
返回值 :
Archive_Tar对象.
样例 :
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object_compressed =
new Archive_Tar("tarname.tgz",
true);
如何工作 :
初始化对象.
方法 : create($p_filelist)
描述 :
该方法创建压缩文件并加入$p_filelist所列的文件和目录.
如果文件是存在且可写的,那么将会被新的tar文件所替代.毕竟这是一个创建动作而不是添加动作.反之,如果文件存在且为只读或者是一个目录,那么它将不会被替代.该方法即返回false和一个PEAR错误文本.
$p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
参阅createModify()方法得到更多的细节.
参数 :
$p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
返回值 :
成功返回true,错误返回false.
样例 1 :
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->setErrorHandling(PEAR_ERROR_PRINT); //
可选的错误处理
$v_list[0]="file.txt";
$v_list[1]="data/";
(末尾'/'为可选)
$v_list[2]="file.log";
$tar_object->create($v_list);
?> 样例 2 :
<?php
$tar_object = new Archive_Tar("tarname.tar");
$tar_object->setErrorHandling(PEAR_ERROR_PRINT); //
可选的错误处理
$tar_object->create("file.txt
data/ file.log");
如何工作 :
用正确的参数调用createModify()方法.
方法 : createModify($p_filelist, $p_add_dir, $p_remove_dir = "")
描述 :
该方法创建一个压缩文件,并加入$p_filelist所列出的文件/目录.
如果文件是存在且可写的,那么将会被新的tar文件所替代.毕竟这是一个创建动作而不是添加动作.反之,如果文件存在且为只读或者是一个目录,那么它将不会被替代.该方法即返回false和一个PEAR错误文本.
$p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
如果存在的话,在$p_remove_dir中声明的路径将从每个列出来的文件/目录已记录路径中删除.默认没有任何东西被删除(空路径"").
在$p_add_dir中声明的路径将会加在每一个列出来的文件/目录的已记录路径的开始.但是它也可设为空"".路径的添加将会在路径的删除之前(译注:即先去掉$p_remove_dir,再加上$p_add_dir).
这种路径的添加/删除能力使得用户可以在一个不同的路径中准备好解压用的压缩包,而不是源文件所在.
参阅addModify()方法查看文件添加的特性.
参数 :
$p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
$p_add_dir : 一个字符串,包含欲加到列表中每一个元素的已记录路路径中的一个路径.
$p_remove_dir : 一个字符串,包含一个路径,如果关联的话,则从列表中每一个元素的已记录路径删除.
返回值 :
成功返回true,错误返回false.
样例 1 :
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->setErrorHandling(PEAR_ERROR_PRINT); //
可选的错误处理
$v_list[0]="file.txt";
$v_list[1]="data/";
(末尾'/'为可选)
$v_list[2]="file.log";
$tar_object->createModify($v_list,
"install");
// 存储在压缩包中的文件形如 :
// install/file.txt
// install/data
// install/data/file1.txt
// install/data/... 所有data下的文件和子目录/
// install/file.log
样例 2 :
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->setErrorHandling(PEAR_ERROR_PRINT); //
可选的错误处理
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
(末尾'/'为可选)
$v_list[2]="log/file.log";
$tar_object->createModify($v_list,
"install", "dev");
// 存储在压缩包中的文件形如 :
// install/file.txt
// install/data
// install/data/file1.txt
// install/data/... 所有data下的文件和子目录/
// install/log/file.log
如何工作 :
以可写的模式打开文件(如果已经存在,则擦除),调用_addList()方法,在一个空压缩包加入文件,加入尾部(512字节的区块),关闭tar文件.
方法 : addModify($p_filelist, $p_add_dir, $p_remove_dir="")
描述 :
该方法在已存在的压缩包的末尾加入$p_filelist所列的文件/目录.如果压缩包尚未存在,那么就被创建.
$p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
如果存在的话,在$p_remove_dir中声明的路径将从每个列出来的文件/目录已记录路径中删除.默认没有任何东西被删除(空路径"").
在$p_add_dir中声明的路径将会加在每一个列出来的文件/目录的已记录路径的开始.但是它也可设为空"".路径的添加将会在路径的删除之前(译注:即先去掉$p_remove_dir,再加上$p_add_dir).
这种路径的添加/删除能力使得用户可以在一个不同的路径中准备好解压用的压缩包,而不是源文件所在.
如果文件/目录已经存在于压缩包,它将只被加在压缩包的末尾.已存在的压缩的文件和路径并没有任何更新.但是,当解压时,最后的文件将会替代第一个.结果是压缩尺寸的未优化.
如果文件/目录不存在,该文件/目录就被忽略.但一个错误文本将会发送到PEAR错误里.
如果文件/目录不可读,该文件/目录就被忽略.但一个错误文件将会发送到PEAR错误里.
如果结果文件名/路径名(在添加/删除之后或者没有这些动作)字符串多于99个字符,该文件/目录将被忽略.但一个错误文本将会发送到PEAR错误里.
参数 :
$p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
$p_add_dir : 一个字符串,包含欲加到列表中每一个元素的已记录路路径中的一个路径.
$p_remove_dir : 一个字符串,包含一个路径,如果关联的话,则从列表中每一个元素的已记录路径删除.
返回值 :
成功返回true,错误返回false.
样例 1 :
$tar_object =
new Archive_Tar("tarname.tar");
[...]
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
(末尾'/'为可选)
$v_list[2]="log/file.log";
$tar_object->addModify($v_list,
"install");
// 存储在压缩包中的文件形如 :
// install/file.txt
// install/data
// install/data/file1.txt
// install/data/... 所有data下的文件和子目录/
// install/file.log
样例 2 :
$tar_object =
new Archive_Tar("tarname.tar");
[...]
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
(末尾'/'为可选)
$v_list[2]="log/file.log";
$tar_object->addModify($v_list,
"install", "dev");
// 存储在压缩包中的文件形如 :
// install/file.txt
// install/data
// install/data/file1.txt
// install/data/... 所有data下的文件和子目录/
// install/log/file.log
如何工作 :
如果压缩包不存在,则创建并加入文件.
如果压缩包确实存在但未被压缩,则打开它,跳到组后512字节空区块(tar脚部),并在该点加入文件.
如果压缩包确实存在且被压缩,将会创建一个临时拷贝文件.这个临时文件是以'gzip'方式一块接着一块直至最终空区块读取的结果.新的文件此时被加到压缩文件中.
文件的添加是通过遍历文件/目录列表,然后加进每个文件,以一个递规的方式遍历目录.每一次一个路径都需要添加/删除,在在压缩包写入文件头部之前完成这项工作.
方法 : add($p_filelist)
描述 :
该方法把$p_filelist里列出的文件/目录加入到已经存在的压缩包中去.如果压缩包尚未存在,则创建之.
$p_filelist参数可以是一组字符串,每个字符串代表一个文件名或者目录名,如果需要,则要带上它们的路径.该参数也可以是以空格分割开的文件或目录名组成的字符串.
参阅addModify()方法查看细节和限制.
参数 :
$p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
返回值 :
成功返回true,错误返回false.
样例 1 :
$tar_object =
new Archive_Tar("tarname.tar");
[...]
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
(末尾'/'为可选)
$v_list[2]="log/file.log";
$tar_object->add($v_list);
?> 样例 2 :
<?php
$tar_object = new Archive_Tar("tarname.tgz",
true);
[...]
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
(末尾'/'为可选)
$v_list[2]="log/file.log";
$tar_object->add($v_list);
如何工作 :
用正确的参数简单地调用addModify()方法.
方法 : addString($p_filename, $p_string)
描述 :
该方法在已存在压缩包末尾以文件的形式加入一单个字符串.如果压缩包尚未存在,则创建之.
参数 :
$p_filename : 一个字符串,包含将与该字符串相关联的文件全部路径.
$p_string : 加入到压缩包文件中的内容.
返回值 :
成功返回true,错误返回false.
样例 1 :
$v_archive =
& new Archive_Tar($p_filename);
$v_archive->setErrorHandling(PEAR_ERROR_PRINT);
$v_result =
$v_archive->addString('data/test.txt',
'这是字符串文本');
方法 : extract($p_path = "")
描述 :
该方法在一个由$p_path声明的目录中解出所有压缩包里的内容.$p_path是可选的,如果没有设置,压缩包就在当前目录被解压.
当解压一个文件时,如果目录路径不存在,则该目录路径会被创建.
查阅extractModify()查看细节和限制.
参数 :
$p_path : 可选的路径,为文件/目录需要解压到的地方.
返回值 :
成功返回true,错误返回false.
样例 :
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->extract();
如何工作 :
用恰当的参数简单的调用extractModify()方法.
方法 : extractModify($p_path, $p_remove_path)
描述 :
该方法在由$p_path声明的目录里解出压缩包所有内容.如果是关联的,文件/目录的已记录路径可以在文件/路径开头因删除了$p_remove_path路径而改变.
当解压一个文件时,如果目录路径不存在,则创建之.
当解压一个文件时,如果文件已经存在,那么不必查看最后修改日期即会被替代.
当解压一个文件时,如果一个文件已经存在且为写保护,则解压会被中止.
当解压一个文件时,如果具有同样名称的目录已经存在,则解压会被中止.
当解压一个目录时,如果具有同样名称的文件已经存在,则解压会被中止.
当解压一个文件/目录时,如果目标目录存在且为写保护,或者不存在但不能创建,则解压会被中止.
如果在解压之后,一个已解出文件与存储文件尺寸不一致,则解压会被中止.
当解压被中止时,一个PEAR文本会被发送,并且返回false.但是结果可能时需要手工清理的一部分解出的东西.
参数 :
$p_path : 为文件/目录需要解压到的地方.
$p_remove_path : 已记录路径的一部分,如果出现在文件/目录路径的开头,就可以被删除.
返回值 :
成功返回true,错误返回false.
样例 :
// 设想一个含下列文件的tarname.tar
:
// dev/data/file.txt
// dev/data/log.txt
// readme.txt
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->extractModify("install",
"dev");
// 文件将被解压到那里(译注:install目录下) :
// install/data/file.txt
// install/data/log.txt
// install/readme.txt
如何工作 :
打开压缩包,调用一个可以解压压缩包一部分或全部的更通用的函数.
查阅extractList()方法查看更多细节.
方法 : extractInString($p_filename)
描述 :
该方法从压缩包中解出一个由$p_filename声明的文件.
返回一个含文件内容的字符串或者错误时返回NULL.
参数 :
$p_filename : 要解出内容到一字符串的路径.
返回值 :
一个含文件内容的字符串或者NULL.
样例 :
// 设想一个含下列文件的tarname.tar
:
// dev/data/file.txt
// dev/data/log.txt
// dev/readme.txt
$v_archive =
& new Archive_Tar('tarname.tar');
$v_archive->setErrorHandling(PEAR_ERROR_PRINT);
$v_string =
$v_archive->extractInString('dev/readme.txt');
echo $v_string;
方法 : listContent()
描述 :
该方法返回一列数组(译注:即为二维数组),用来描述每一个在压缩包里的文件/目录.
该数组没有被排序,所以它可以示意文件在压缩包中的位置.
文件的信息有:
$file[filename] : 文件/目录的名称和路径.
$file[mode] : 文件权限(为fileperms()的结果)
$file[uid] : 用户id
$file[gid] : 用户组id
$file[size] : 文件尺寸
$file[mtime] : 最后修改时间(为filemtime()的结果)
$file[typeflag] : 对文件来说为"", 对目录来说为"5"
参数 :
返回值 :
一列数组或者错误返回0.
样例 :
$tar_object =
new Archive_Tar("tarname.tar");
if (($v_list = $tar_object->listContent())
!= 0)
for ($i=0;
$i<sizeof($v_list);
$i++)
{
echo "Filename
:'".$v_list[$i][filename]."'<br>";
echo " .size
:'".$v_list[$i][size]."'<br>";
echo " .mtime
:'".$v_list[$i][mtime]."'
(".
date("l
dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>";
echo " .mode
:'".$v_list[$i][mode]."'<br>";
echo " .uid
:'".$v_list[$i][uid]."'<br>";
echo " .gid
:'".$v_list[$i][gid]."'<br>";
echo " .typeflag
:'".$v_list[$i][typeflag]."'<br>";
}
如何工作 :
和extract调用同样的函数,但是带一个标记只遍历压缩包,并不解出文件.
方法 : extractList($p_filelist, $p_path = "", $p_remove_path = "")
描述 :
该方法只从压缩包中解出在$p_filelist声明的文件.这些文件被解到当前目录或者到一个由可选参数$p_path声明的目录里.
如果声明了$p_remove_path,那么可以和它在extractModify()方法里的用法一样应用.
参数 :
$p_filelist : 一组文件名和目录名,或者以单个空格分割开的文件或目录名组成的字符串.
$p_path : 为文件/目录需要解压到的地方.
$p_remove_path : 已记录路径的一部分,如果出现在文件/目录路径的开头,就可以被删除.
返回值 :
成功返回true,错误返回false.
样例 :
// 设想一个含下列文件的tarname.tar
:
// dev/data/file.txt
// dev/data/log.txt
// readme.txt
$tar_object =
new Archive_Tar("tarname.tar");
$tar_object->extractList("dev/data/file.txt
readme.txt", "install",
"dev");
// 文件将被解压到那里(译注:install目录下) :
// install/data/file.txt
// install/readme.txt
如何工作 :
遍历压缩包,只解压出列表中出现的文件.
