Docs For Class PclZip

YANA Framework for PHP

Class PclZip

Description

Class : PclZip

PclZip is the class that represent a Zip archive. The public methods allow the manipulation of the archive.

--------------------------------------------------------------------------------

Internal representation of a PKZIP archive

--------------------------------------------------------------------------------

Each PKZIP archive is represented by an object of class PclZip. When creating a PclZip archive (on object of class PclZip), the name of the archive file is associated to the object. At this time the file is not checked, nor read, it can even don't exist at this time.

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

The archive is then manipulated by using the public methods associated with PclZip object. To create an archive, when it does not already exist, the method 'create()' must be used, with a list of files and/or folders to archive as parameter. If the archive already exist, its content can be read by access methods like 'listContent()' or 'extract()'.

--------------------------------------------------------------------------------

Parameters and arguments

--------------------------------------------------------------------------------

Each method has its own arguments which are described in the synopsis of the method. These arguments can be mandatory or optional.

Example:

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

Here the first parameter 'dev/file.txt' is mandatory, while 'PCLZIP_OPT_REMOVE_PATH, ...' is optional.

Some methods can also be called only with a variable list of optional arguments:

$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");

Here the files are extracted in 'folder', and the 'data' path, when present in the archive, is removed. Also, before each extraction of a single file from the archive, a callback function, which name is provided by the user (here ' callback_pre_extract()'), is called. This function gives the ability to change the path and the filename that is in the extraction process, or to skip the extraction of this particular file. At the end of the extraction of the file an other call-back function is called, giving the ability to the user to perform specific actions on the file before extracting the next one.

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

Here the files are extracted in the directory 'folder' and all the memorized path of the files are removed, even if they are different. By this feature the user does not have to specify the exact value of a path to remove.

These small examples shows how the variable list of options works. They offer better features (with the cost of a little more complexity). They will also ease the introduction of new features without changing the synopsis of all the methods.

The defined arguments, their usage and restrictions are described in the section "Optional Variable Parameters". In the description of each method, the list of available optional parameters are indicated.

--------------------------------------------------------------------------------

Return values

--------------------------------------------------------------------------------

Return values may be different from methods to methods. They are described in each method synopsis. However most of the methods returns 0 on error (and set the error flag), or an array describing each file on success. Each entry of this array describe a file or folder, some of its properties and the specific status of the last action on the file.

Each file is described by the following arguments:

filename: Name of the file. For an add, it is the name given when calling the method. For extraction it is the real name of the extracted file (not the name stored in the archive).
stored_filename: Stored name of the file.
size: Real size of the file.
compressed_size: Compressed size in the archive (without header overhead)
mtime: Last modification date and time of the file (UNIX timestamp)
comment: Comments associated with the file.
folder: true | false. Indicates if the name if the name of a file or a folder.
index: Index of the file in the archive (when set).
content: Content of the extracted file. This row is present only when the option argument PCLZIP_OPT_EXTRACT_IN_STRING is set.
status: Result of the action (depend on the action type). Values are:
- ok
- filtered - the file/folder was not extracted (filtered by the user).
- already_a_directory - the file was not extracted because a folder with same name already exists.
- write_protected - the file was not extracted because a file with same name already exists and is write protected.
- newer_exist - the file was not extracted because a more recent file exists.
- path_creation_fail - the file was not extracted because an error occurs while creating its path.
- write_error - the file was not extracted because a write error occur
- read_error - the file was not extracted because a read error occured
- invalid_header - the file was not extracted because of a bad header
- skipped - the file was not extracted or added because a user call-back function request to skip it. (Introduced in version 1.3)
- filename_too_long - the file was not added in the archive because the filename is too long (maximum 255 caracters). (Introduced in version 1.3)

author: Vincent Blavet

Method Summary

PclZip PclZip (string $p_zipname)
array add (mixed $p_filelist)
array create (mixed $p_filelist)
array delete ()
void deleteByIndex (scalar $p_index)
int duplicate (string|PCLZip $p_archive)
array extract ()
array extractByIndex (scalar $p_index)
array listContent ()
int merge (string|PCLZip $p_archive_to_add)
array properties ()

Methods

constructor

PclZip PclZip (

string $p_zipname

)

List of parameters:

Name	Type	Description
$p_zipname	string	name of ZIP archive

Description:

Creates a PclZip object and set the name of the associated Zip archive filename.

Note that no real action is taken. If the archive does not exist it is not created. Use create() for that.

Synopsis:

new PclZip($zipname)

Example:

include('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$archive->create('file.txt data/text.txt folder/');

access: public

add files to ZIP

array add (

mixed $p_filelist

)

List of parameters:

Name	Type	Description
$p_filelist	mixed	see param description for details

Description:

This method supports two synopsis. The first one is historical. This methods add the list of files in an existing archive. If a file with the same name already exists, it is added at the end of the archive, the first one is still present. If the archive does not exist, it is created.

Synopsis 1 (old):

$pclzip->add($p_filelist, $p_add_dir="", $p_remove_dir="");

Parameters:

$p_filelist : (same as above) An array containing file or directory names, or a string containing one filename or one directory name, or a string containing a list of filenames and/or directory names separated by spaces.
$p_add_dir : A path to add before the real path of the archived file, in order to have it memorized in the archive.
$p_remove_dir : A path to remove from the real path of the file to archive, in order to have a shorter path memorized in the archive. When $p_add_dir and $p_remove_dir are set, $p_remove_dir is removed first, before $p_add_dir is added.

Synopsis 2 (new):

$pclzip->add($p_filelist, $p_option, $p_option_value, ...);

Parameters:

$p_filelist : (same as above) An array containing file or directory names, or a string containing one filename or one directory name, or a string containing a list of filenames and/or directory names separated by spaces.
optionlist:
- PCLZIP_OPT_ADD_PATH
- PCLZIP_OPT_REMOVE_PATH
- PCLZIP_OPT_REMOVE_ALL_PATH
- PCLZIP_OPT_COMMENT
- PCLZIP_OPT_ADD_COMMENT
- PCLZIP_OPT_PREPEND_COMMENT
- PCLZIP_CB_PRE_ADD
- PCLZIP_CB_POST_ADD

Return Values:

0 on failure
The list of the added files, with a status of the add action. (see PclZip::listContent() for list entry format)

Examples:

include('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$archive->create('a_first_folder/');
$v_list = $archive->add('file.txt data/text.txt folder/');
if ($v_list == 0) {
die("Error : ".$archive->errorInfo(true));
}

include('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$v_list = $archive->add('data/file.txt data/text.txt',
PCLZIP_OPT_ADD_PATH, 'install',
PCLZIP_OPT_REMOVE_PATH, 'data');
if ($v_list == 0) {
die("Error : ".$archive->errorInfo(true));
}

since: 1.1
access: public

create new ZIP archive

array create (

mixed $p_filelist

)

List of parameters:

Name	Type	Description
$p_filelist	mixed	see param description for details

Description:

This method supports two different synopsis. The first one is historical. It creates a Zip Archive. The Zip file is created in the filesystem. The files and directories indicated in $p_filelist are added in the archive. See the parameters description for the supported format of $p_filelist. When a directory is in the list, the directory and its content is added in the archive. In this synopsis, the function takes an optional variable list of options. See bellow the supported options.

1st Synopsis (old):

$pclzip->create($p_filelist, $p_add_dir="", $p_remove_dir="");

Parameters:

$p_filelist : An array containing file or directory names, or a string containing one filename or one directory name, or a string containing a list of filenames and/or directory names separated by spaces.
$p_add_dir : A path to add before the real path of the archived file, in order to have it memorized in the archive.
$p_remove_dir : A path to remove from the real path of the file to archive, in order to have a shorter path memorized in the archive. When $p_add_dir and $p_remove_dir are set, $p_remove_dir is removed first, before $p_add_dir is added.

2nd Synopsis (new):

$pclzip->create($p_filelist, $p_option, $p_option_value, ...);

Parameters:

$p_filelist : (same as above) An array containing file or directory names, or a string containing one filename or one directory name, or a string containing a list of filenames and/or directory names separated by spaces.
optionlist:
- PCLZIP_OPT_ADD_PATH
- PCLZIP_OPT_REMOVE_PATH
- PCLZIP_OPT_REMOVE_ALL_PATH
- PCLZIP_OPT_COMMENT
- PCLZIP_CB_PRE_ADD
- PCLZIP_CB_POST_ADD

Return Values:

0 on failure
The list of the added files, with a status of the add action. (see PclZip::listContent() for list entry format)

Examples:

include_once('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$v_list = $archive->create('file.txt data/text.txt folder/');
if ($v_list == 0) {
die("Error : ".$archive->errorInfo(true));
}

The example above creates "archive.zip" and adds the files "file.txt", "data/text.txt" and the whole directory "folder/".

include_once('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$v_list = $archive->create('data/file.txt data/text.txt',
PCLZIP_OPT_ADD_PATH, 'install',
PCLZIP_OPT_REMOVE_PATH, 'data');
if ($v_list == 0) {
die("Error : ".$archive->errorInfo(true));
}

The example above creates "archive.zip", adds the files "file.txt" and "data/text.txt". The path "data/" is replaced by "install/". So the archive will contain the files: "install/file.txt" and "install/text.txt".

access: public

delete file in archive

array delete ()

Description:

This method removes files from the archive. If no parameters are given, then the whole archive is emptied.

Synopsis:

delete([$p_option, $p_option_value, ...])

Options:

PCLZIP_OPT_BY_INDEX
PCLZIP_OPT_BY_NAME
PCLZIP_OPT_BY_EREG
PCLZIP_OPT_BY_PREG

Return Values:

0 on failure
The list of the files which are still present in the archive. (see PclZip::listContent() for list entry format)

access: public
name: PclZip::delete()

delete a file by index

void deleteByIndex (

scalar $p_index

)

List of parameters:

Name	Type	Description
$p_index	scalar

Description:

Deprecated: delete(PCLZIP_OPT_BY_INDEX, $p_index) should be prefered.

see: PclZip::delete()
deprecated:
access: public

duplicate current archive

int duplicate (

string|PCLZip $p_archive

)

List of parameters:

Name	Type	Description
$p_archive	string\|PCLZip	The filename of a valid archive, or a valid PclZip object

Description:

This method creates an archive by copying the content of an other one. If the archive already exist, it is replaced by the new one without any warning.

Return Values:

1 on success.
0 or a negative value on error (error code).

access: public

extract files

array extract ()

Description:

This method supports two synopsis. The first one is historical.

This method extract all the files / directories from the archive to the folder indicated in $p_path. If you want to ignore the 'root' part of path of the memorized files you can indicate this in the optional $p_remove_path parameter. By default, if a newer file with the same name already exists, the file is not extracted.

If both PCLZIP_OPT_PATH and PCLZIP_OPT_ADD_PATH aoptions are used, the path indicated in PCLZIP_OPT_ADD_PATH is append at the end of the path value of PCLZIP_OPT_PATH.

1st Synopsis (old):

$pclzip->extract($p_path="./", $p_remove_path="");

Parameters:

$p_path : Path where the files and directories are to be extracted
$p_remove_path : First part ('root' part) of the memorized path (if any similar) to remove while extracting.

2nd Synopsis (new):

$pclzip->extract([$p_option, $p_option_value, ...]);

Options:

PCLZIP_OPT_PATH
PCLZIP_OPT_ADD_PATH
PCLZIP_OPT_REMOVE_PATH
PCLZIP_OPT_REMOVE_ALL_PATH
PCLZIP_CB_PRE_EXTRACT
PCLZIP_CB_POST_EXTRACT

Return Values:

0 or a negative value on failure
The list of the extracted files, with a status of the action. (see PclZip::listContent() for list entry format)

Examples:

include('pclzip.lib.php');
$archive = new PclZip('archive.zip');
if ($archive->extract() == 0) {
die("Error : ".$archive->errorInfo(true));
}

The examples above extracts all files to the current directory

include('pclzip.lib.php');
$archive = new PclZip('archive.zip');
if ($archive->extract(PCLZIP_OPT_PATH, 'data',
PCLZIP_OPT_REMOVE_PATH, 'install/release') == 0) {
die("Error : ".$archive->errorInfo(true));
}

This example extracts all files to the directory "data/". All files which have the prefix "install/release/" are extracted to "data/" rather than "data/install/release".

access: public

extract file by index number

array extractByIndex (

scalar $p_index

)

List of parameters:

Name	Type	Description
$p_index	scalar

Description:

This method supports two synopsis. The first one is historical. This method is doing a partial extract of the archive. The extracted files or folders are identified by their index in the archive (from 0 to n). Note that if the index identify a folder, only the folder entry is extracted, not all the files included in the archive.

1st Synopsis (old):

$pclzip->extractByIndex($p_index, $p_path="./", $p_remove_path="");

Parameters:

$p_index : A single index (integer) or a string of indexes of files to extract. The form of the string is "0,4-6,8-12" with only numbers and '-' for range or ',' to separate ranges. No spaces or ';' are allowed.
$p_path : Path where the files and directories are to be extracted
$p_remove_path : First part ('root' part) of the memorized path (if any similar) to remove while extracting.

2nd Synopsis (new):

$pclzip->extractByIndex($p_index, [$p_option, $p_option_value, ...]);

Options:

PCLZIP_OPT_PATH
PCLZIP_OPT_ADD_PATH
PCLZIP_OPT_REMOVE_PATH
PCLZIP_OPT_REMOVE_ALL_PATH
PCLZIP_OPT_EXTRACT_AS_STRING: The files are extracted as strings and not as files. The resulting content is in a new field 'content' in the file structure. This option must be used alone (any other options are ignored).
PCLZIP_CB_PRE_EXTRACT
PCLZIP_CB_POST_EXTRACT

Return Values:

0 on failure
The list of the extracted files, with a status of the action. (see PclZip::listContent() for list entry format)

Examples:

require_once('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$v_list = $archive->extractByIndex('1-3,5,8-10');
if ($v_list == 0) {
die("Error : ".$archive->errorInfo(true));
}

This example extracts the files or directories at indexes 1 through 3, 5, 8 through 10 to the current directory.

require_once('pclzip.lib.php');
$archive = new PclZip('archive.zip');
$v_list = $archive->extractByIndex('1-3,5,8-10',
PCLZIP_OPT_PATH, 'data',
PCLZIP_OPT_REMOVE_PATH, 'install/release');
if ($v_list == 0) {
die("Error : ".$archive->errorInfo(true));
}

This example extracts the files or directories at indexes 1 through 3, 5, 8 through 10 to the directory "data/". All files which have the prefix "install/release/" are extracted to "data/" rather than "data/install/release".

access: public

list archive contents

array listContent ()

Description:

This public method, gives the list of the files and directories, with their properties.

The properties of each entry in the list are (used also in other functions):

filename: Name of the file. For an add, it is the name given when calling the method. For extraction it is the real name of the extracted file (not the name stored in the archive).
stored_filename: Stored name of the file.
size: Real size of the file.
compressed_size: Compressed size in the archive (without header overhead)
mtime: Last modification date and time of the file (UNIX timestamp)
comment: Comments associated with the file.
folder: true | false. Indicates if the name if the name of a file or a folder.
index: Index of the file in the archive (when set).
content: Content of the extracted file. This row is present only when the option argument PCLZIP_OPT_EXTRACT_IN_STRING is set.
status: Result of the action (depend on the action type). Values are:
- ok
- filtered - the file/folder was not extracted (filtered by the user).
- already_a_directory - the file was not extracted because a folder with same name already exists.
- write_protected - the file was not extracted because a file with same name already exists and is write protected.
- newer_exist - the file was not extracted because a more recent file exists.
- path_creation_fail - the file was not extracted because an error occurs while creating its path.
- write_error - the file was not extracted because a write error occur
- read_error - the file was not extracted because a read error occured
- invalid_header - the file was not extracted because of a bad header
- skipped - the file was not extracted or added because a user call-back function request to skip it. (Introduced in version 1.3)
- filename_too_long - the file was not added in the archive because the filename is too long (maximum 255 caracters). (Introduced in version 1.3)

Note that each time a method can continue operating when there is an action error on a file, the error is only logged in the file status.

Return Values:

0 on an unrecoverable error
The list of the files in the archive.

Examples:

include_once('pclzip.lib.php');
$zip = new PclZip("test.zip");
if (($list = $zip->listContent()) == 0) {
die("Error : ".$zip->errorInfo(true));
}
for ($i=0; $i<sizeof($list); $i++)
{
for(reset($list[$i]); $key = key($list[$i]); next($list[$i]))
{
echo "File $i / [$key] = ".$list[$i][$key]."\n";
}
echo "\n";
}

An example for the output produce by the code above:

 File 0 / [filename] = data/file1.txt
 File 0 / [stored_filename] = data/file1.txt
 File 0 / [size] = 53
 File 0 / [compressed_size] = 36
 File 0 / [mtime] = 1010440428
 File 0 / [comment] =
 File 0 / [folder] = 0
 File 0 / [index] = 0
 File 0 / [status] = ok

 File 1 / [filename] = data/file2.txt
 File 1 / [stored_filename] = data/file2.txt
 File 1 / [size] = 54
 File 1 / [compressed_size] = 53
 File 1 / [mtime] = 1011197724
 File 1 / [comment] =
 File 1 / [folder] = 0
 File 1 / [index] = 1
 File 1 / [status] = ok

access: public
name: PclZip::listContent()

merge with another archive

int merge (

string|PCLZip $p_archive_to_add

)

List of parameters:

Name	Type	Description
$p_archive_to_add	string\|PCLZip	The filename of a valid archive, or a valid PclZip object

Description:

This method merge the $p_archive_to_add archive at the end of the current one ($this). If the archive ($this) does not exist, the merge becomes a duplicate. If the $p_archive_to_add archive does not exist, the merge is a success.

Return Values:

1 on success.
0 or a negative value on error (error code).

access: public

get archive properties

array properties ()

Description:

This method gives the properties of the archive.

The properties are:

nb: Number of files in the archive
comment: Comment associated with the archive file
status: not_exist, ok

Return Values :

0 on failure
An array with the archive properties. (see above)

access: public

Documentation generated on Sat, 03 Jan 2009 22:22:38 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyer Homepage: www.yanaframework.net