yana

Description
  Class trees
  Index of elements
  Todo List
core
  Classes
    FormCreator
    Index
    Language
    Object
    Plugin
    PluginManager
    Singleton
    SmartTemplate
    SmartView
    Utility
    Yana
database
  Classes
    DbBlob
    DbCreator
    DbDesigner4
    DbExtractor
    DbQuery
    DbQueryParser
    DbServer
    DbStream
    DbStructure
    FileDb
error_reporting
  Classes
    Alert
    Error
    ErrorUtility
    Log
    Message
    Report
    Warning
file_system
  Classes
    DatFile
    Dir
    Executeable
    File
    FileReadonly
    FileSystemResource
    SML
javascript
  Classes
    AjaxRequest
  Functions
    preview
    yanaAddEventListener
    yanaAddIcon
    yanaCheckEmbTags
    yanaCloseAll
    yanaGetCookie
    yanaGetElementsByClassName
    yanaMaxLength
    yanaMenu
    yanaMenuCookie
    yanaSetCookie
mail
  Classes
    FormMailer
    Mailer
plugins
  Classes
    plugin_blog
    plugin_check
    plugin_db_admin
    plugin_db_tools
    plugin_default_library
    plugin_diagnostics
    plugin_guestbook
    plugin_guestbook_admin
    plugin_ipblock
    plugin_ipblock_admin
    plugin_rss
    plugin_rss_admin
    plugin_sdk
    plugin_search
    plugin_search_admin
    plugin_user
    plugin_user_admin
utilities
  Classes
    Brush
    Counter
    Hashtable
    Image
    Microsummary
    RSS
    RSSitem
    String
  Functions
    checkArgumentList
    cloneArray
    dirlist
    qSearchArray
    untaintInput
    XMLencode
vdrive
  Classes
    Registry
    VDrive
zip
  Classes
    PclZip

phpDocumentor v 1.4.0

YANA Framework for PHPDocs For Class PclZip

### 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.

1. require_once('pclzip.lib.php');
2. $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:

1. require_once('pclzip.lib.php');
2. $archive = new PclZip('archive.zip');
3. $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:

1. $list = $archive->extract(PCLZIP_OPT_PATH, "folder",
2. PCLZIP_OPT_REMOVE_PATH, "data",
3. PCLZIP_CB_PRE_EXTRACT, "callback_pre_extract",
4. 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.

1. $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:

1. new PclZip($zipname)

Example:

1. include('pclzip.lib.php');
2. $archive = new PclZip('archive.zip');
3. $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):

1. $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):

1. $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:

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

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

- 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):

1. $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):

1. $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:

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

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

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

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:

1. 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):

1. $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):

1. $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:

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

The examples above extracts all files to the current directory

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

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):

1. $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):

1. $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:

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

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

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

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:

1. include_once('pclzip.lib.php');
3. $zip = new PclZip("test.zip");
5. if (($list = $zip->listContent()) == 0) {
6. die("Error : ".$zip->errorInfo(true));
7. }
9. for ($i=0; $i<sizeof($list); $i++)
10. {
11. for(reset($list[$i]); $key = key($list[$i]); next($list[$i]))
12. {
13. echo "File $i / [$key] = ".$list[$i][$key]."\n";
14. }
15. echo "\n";
16. }

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 Sun, 04 Jan 2009 03:49:15 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyerwww.yanaframework.net