From ead062f704277224af51e7efb4000a0e0f0510d8 Mon Sep 17 00:00:00 2001 From: Pierre Joye Date: Fri, 11 Aug 2006 17:27:59 +0000 Subject: [PATCH] - Add documentation for the new Zip extension (add new OO interface) - Update the installation and reference pages (pecl, php4, 5.2+) git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@217987 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/zip/configure.xml | 75 ++- reference/zip/constants.xml | 516 ++++++++++++++++++ .../zip/functions/ziparchive-addfile.xml | 95 ++++ .../functions/ziparchive-addfromstring.xml | 108 ++++ reference/zip/functions/ziparchive-close.xml | 46 ++ .../zip/functions/ziparchive-deleteindex.xml | 80 +++ .../zip/functions/ziparchive-deletename.xml | 80 +++ .../zip/functions/ziparchive-extractto.xml | 115 ++++ .../ziparchive-getarchivecomment.xml | 66 +++ .../functions/ziparchive-getcommentindex.xml | 89 +++ .../functions/ziparchive-getcommentname.xml | 89 +++ .../zip/functions/ziparchive-getfromindex.xml | 101 ++++ .../zip/functions/ziparchive-getfromname.xml | 125 +++++ .../zip/functions/ziparchive-getnameindex.xml | 60 ++ .../zip/functions/ziparchive-getstream.xml | 118 ++++ .../zip/functions/ziparchive-locatename.xml | 121 ++++ reference/zip/functions/ziparchive-open.xml | 188 +++++++ .../zip/functions/ziparchive-renameindex.xml | 89 +++ .../zip/functions/ziparchive-renamename.xml | 89 +++ .../ziparchive-setarchivecomment.xml | 82 +++ .../functions/ziparchive-setcommentindex.xml | 90 +++ .../functions/ziparchive-setcommentname.xml | 90 +++ .../zip/functions/ziparchive-statindex.xml | 111 ++++ .../zip/functions/ziparchive-statname.xml | 129 +++++ .../zip/functions/ziparchive-unchangeall.xml | 45 ++ .../functions/ziparchive-unchangearchive.xml | 46 ++ .../functions/ziparchive-unchangeindex.xml | 60 ++ .../zip/functions/ziparchive-unchangename.xml | 61 +++ reference/zip/reference.xml | 145 +++-- 29 files changed, 3058 insertions(+), 51 deletions(-) create mode 100644 reference/zip/constants.xml create mode 100644 reference/zip/functions/ziparchive-addfile.xml create mode 100644 reference/zip/functions/ziparchive-addfromstring.xml create mode 100644 reference/zip/functions/ziparchive-close.xml create mode 100644 reference/zip/functions/ziparchive-deleteindex.xml create mode 100644 reference/zip/functions/ziparchive-deletename.xml create mode 100644 reference/zip/functions/ziparchive-extractto.xml create mode 100644 reference/zip/functions/ziparchive-getarchivecomment.xml create mode 100644 reference/zip/functions/ziparchive-getcommentindex.xml create mode 100644 reference/zip/functions/ziparchive-getcommentname.xml create mode 100644 reference/zip/functions/ziparchive-getfromindex.xml create mode 100644 reference/zip/functions/ziparchive-getfromname.xml create mode 100644 reference/zip/functions/ziparchive-getnameindex.xml create mode 100644 reference/zip/functions/ziparchive-getstream.xml create mode 100644 reference/zip/functions/ziparchive-locatename.xml create mode 100644 reference/zip/functions/ziparchive-open.xml create mode 100644 reference/zip/functions/ziparchive-renameindex.xml create mode 100644 reference/zip/functions/ziparchive-renamename.xml create mode 100644 reference/zip/functions/ziparchive-setarchivecomment.xml create mode 100644 reference/zip/functions/ziparchive-setcommentindex.xml create mode 100644 reference/zip/functions/ziparchive-setcommentname.xml create mode 100644 reference/zip/functions/ziparchive-statindex.xml create mode 100644 reference/zip/functions/ziparchive-statname.xml create mode 100644 reference/zip/functions/ziparchive-unchangeall.xml create mode 100644 reference/zip/functions/ziparchive-unchangearchive.xml create mode 100644 reference/zip/functions/ziparchive-unchangeindex.xml create mode 100644 reference/zip/functions/ziparchive-unchangename.xml diff --git a/reference/zip/configure.xml b/reference/zip/configure.xml index dd137ce18e..9fd6f7182b 100644 --- a/reference/zip/configure.xml +++ b/reference/zip/configure.xml @@ -1,5 +1,5 @@ - +
&reftitle.install; @@ -7,24 +7,61 @@ &pecl.info; &url.pecl.package;zip. - - &pecl.source.4; - In order to use these functions you must compile PHP with zip support - by using the - configure option. - - - Windows users will enable php_zip.dll inside - of &php.ini; in order to use these functions. - &pecl.windows.4; - &pecl.windows.download; - - - - Zip support before PHP 4.1.0 is experimental. This section - reflects the Zip extension as it exists in PHP 4.1.0 and later. - - +
+ Installation on Linux +
+ Installation when bundled with PHP4 + + In order to use these functions you must compile PHP with zip support + by using the + configure option, where [DIR] is the prefix of the ZZIPlib library install. + +
+
+ Installation with PECL or bundled with PHP 5.2 or earlier + + In order to use these functions you must compile PHP with zip support + by using the + configure option. It does require any external library. + + + + You can use the PECL version with PHP4. In order to do it you + have to disable the bundled Zip extension or recompile PHP without + it. + + +
+
+ +
+ Installation on Windows +
+ Installation when bundled with PHP4 + + Windows users will enable php_zip.dll inside + of &php.ini; in order to use these functions. + &pecl.windows.4; + &pecl.windows.download; + + + + Zip support before PHP 4.1.0 is experimental. This section + reflects the Zip extension as it exists in PHP 4.1.0 and later. + + +
+
+ Installation with PECL or bundled with PHP 5.2 or earlier + + Windows users will enable php_zip.dll inside + of &php.ini; in order to use these functions. + &pecl.windows.4; + &pecl.windows.download; + +
+
+ +
+ &reftitle.constants; + &extension.constants; + + + ZipArchive uses class constants. There is three types of constants, + Flags (FL_) errors (ER_) or mode (no prefix). + + + + + + ZIPARCHIVE::CREATE + (integer) + + + + Create the archive if it does not exist. + + + + + + + ZIPARCHIVE::EXCL + (integer) + + + + Error if archive already exists. + + + + + + ZIPARCHIVE::CHECKCONS + (integer) + + + + Perform additional consistency checks on the archive, and error if they fail. + + + + + + ZIPARCHIVE::FL_NOCASE + (integer) + + + + Ignore case on name lookup + + + + + + ZIPARCHIVE::FL_NODIR + (integer) + + + + Ignore directory component + + + + + + ZIPARCHIVE::FL_COMPRESSED + (integer) + + + + Read compressed data + + + + + + ZIPARCHIVE::FL_UNCHANGED + (integer) + + + + Use original data, ignoring changes. + + + + + + + ZIPARCHIVE::CM_DEFAULT + (integer) + + + + better of deflate or store. + + + + + + ZIPARCHIVE::CM_STORE + (integer) + + + + stored (uncompressed). + + + + + + ZIPARCHIVE::CM_SHRINK + (integer) + + + + shrunk + + + + + + ZIPARCHIVE::CM_REDUCE_1 + (integer) + + + + reduced with factor 1 + + + + + + ZIPARCHIVE::CM_REDUCE_2 + (integer) + + + + reduced with factor 2 + + + + + + ZIPARCHIVE::CM_REDUCE_3 + (integer) + + + + reduced with factor 3 + + + + + + ZIPARCHIVE::CM_REDUCE_4 + (integer) + + + + reduced with factor 4 + + + + + + ZIPARCHIVE::CM_IMPLODE + (integer) + + + + imploded + + + + + + ZIPARCHIVE::CM_DEFLATE + (integer) + + + + deflated64 + + + + + + ZIPARCHIVE::CM_DEFLATE64 + (integer) + + + + deflated64 + + + + + + ZIPARCHIVE::CM_PKWARE_IMPLODE + (integer) + + + + PKWARE imploding + + + + + + ZIPARCHIVE::CM_BZIP2 + (integer) + + + + BZIP2 algorithm + + + + + + + ZIPARCHIVE::ER_OK + (integer) + + + + No error. + + + + + + ZIPARCHIVE::ER_MULTIDISK + (integer) + + + + + + + + + + ZIPARCHIVE::ER_RENAME + (integer) + + + + Multi-disk zip archives not supported. + + + + + + ZIPARCHIVE::ER_CLOSE + (integer) + + + + Closing zip archive failed + + + + + + ZIPARCHIVE::ER_SEEK + (integer) + + + + Seek error + + + + + + ZIPARCHIVE::ER_READ + (integer) + + + + Read error + + + + + + + ZIPARCHIVE::ER_WRITE + (integer) + + + + Write error + + + + + + ZIPARCHIVE::ER_CRC + (integer) + + + + CRC error + + + + + + ZIPARCHIVE::ER_ZIPCLOSED + (integer) + + + + Containing zip archive was closed + + + + + + ZIPARCHIVE::ER_NOENT + (integer) + + + + No such file. + + + + + + ZIPARCHIVE::ER_EXISTS + (integer) + + + + File already exists + + + + + + ZIPARCHIVE::ER_OPEN + (integer) + + + + Can't open file + + + + + + ZIPARCHIVE::ER_TMPOPEN + (integer) + + + + Failure to create temporary file. + + + + + + ZIPARCHIVE::ER_ZLIB + (integer) + + + + Zlib error + + + + + + + ZIPARCHIVE::ER_MEMORY + (integer) + + + + Memory allocation failure + + + + + + + ZIPARCHIVE::ER_CHANGED + (string) + + + + Entry has been changed + + + + + + + ZIPARCHIVE::ER_COMPNOTSUPP + (integer) + + + + Compression method not supported. + + + + + + ZIPARCHIVE::ER_EOF + (integer) + + + + Premature EOF + + + + + + ZIPARCHIVE::ER_INVAL + (integer) + + + + Invalid argument + + + + + + ZIPARCHIVE::ER_NOZIP + (integer) + + + + Not a zip archive + + + + + + ZIPARCHIVE::ER_INTERNAL + (integer) + + + + Internal error + + + + + + ZIPARCHIVE::ER_INCONS + (integer) + + + + + + + + + + ZIPARCHIVE::ER_REMOVE + (integer) + + + + Zip archive inconsistent + + + + + + ZIPARCHIVE::ER_DELETED + (integer) + + + + Entry has been deleted + + + + +
+ + diff --git a/reference/zip/functions/ziparchive-addfile.xml b/reference/zip/functions/ziparchive-addfile.xml new file mode 100644 index 0000000000..2f202ae53d --- /dev/null +++ b/reference/zip/functions/ziparchive-addfile.xml @@ -0,0 +1,95 @@ + + + + + ZipArchive::addFile + Adds a file to a ZIP archive from the given path + + + &reftitle.description; + + booleanZipArchive::addFile + stringfilename + stringlocalname + + + Adds a file to a ZIP archive from a given path + + + + &reftitle.parameters; + + + + filename + + + The path to the file to add. + + + + + localname + + + local name inside ZIP archive. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + This example opens a ZIP file archive, reads each file in the + archive and prints out its contents. The + test.zip archive used in this example is + one of the test archives in the ext/zip/examples directory. + + + Open and extract + +open('test.zip')) { + $zip->addFile('/path/to/index.txt'), 'newname.txt'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-addfromstring.xml b/reference/zip/functions/ziparchive-addfromstring.xml new file mode 100644 index 0000000000..0fddd411dc --- /dev/null +++ b/reference/zip/functions/ziparchive-addfromstring.xml @@ -0,0 +1,108 @@ + + + + + ZipArchive::addFromString + Add a file to a ZIP archive using its contents + + + &reftitle.description; + + booleanZipArchive::addFromString + stringlocalname + stringcontents + + + Add a file to a ZIP archive using its contents. + + + + &reftitle.parameters; + + + + localname + + + The name of the entry to create. + + + + + contents + + + The contents to use to create the entry. It is used in a binary + safe mode. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Add an entry to a new archive + +open('test.zip', ZipArchive::CREATE); +if ($res) { + $zip->addFromString('test.txt', 'file content goes here'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + Add file to a directory inside an archive + +open(realpath('test.zip'))) { + $zip->addFromString('dir/test.txt', 'file content goes here'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-close.xml b/reference/zip/functions/ziparchive-close.xml new file mode 100644 index 0000000000..48e645ac92 --- /dev/null +++ b/reference/zip/functions/ziparchive-close.xml @@ -0,0 +1,46 @@ + + + + + ZipArchive::close + Close the active archive (opened or newly created) + + + &reftitle.description; + + booleanZipArchive::close + + + + Close opened or created archive and save changes. This method is + automatically called at the end of the script. + + + + &reftitle.returnvalues; + + &return.success; + + + + + diff --git a/reference/zip/functions/ziparchive-deleteindex.xml b/reference/zip/functions/ziparchive-deleteindex.xml new file mode 100644 index 0000000000..2a183a59a1 --- /dev/null +++ b/reference/zip/functions/ziparchive-deleteindex.xml @@ -0,0 +1,80 @@ + + + + + ZipArchive::deleteIndex + delete an entry in the archive using its index + + + &reftitle.description; + + booleanZipArchive::deleteIndex + integerindex + + + Delete an entry in the archive using its index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry to delete. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Delete file from archive using its index + +open(realpath('test.zip'))) { + $zip->deleteIndex(2); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-deletename.xml b/reference/zip/functions/ziparchive-deletename.xml new file mode 100644 index 0000000000..05d2aacefa --- /dev/null +++ b/reference/zip/functions/ziparchive-deletename.xml @@ -0,0 +1,80 @@ + + + + + ZipArchive::deleteName + delete an entry in the archive using its name + + + &reftitle.description; + + booleanZipArchive::deleteName + stringname + + + Delete an entry in the archive using its name. + + + + &reftitle.parameters; + + + + name + + + Name of the entry to delete. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Delete file from archive using its name + +open(realpath('test1.zip'))) { + $zip->deleteName('testfromfile.php'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-extractto.xml b/reference/zip/functions/ziparchive-extractto.xml new file mode 100644 index 0000000000..19bcfb471f --- /dev/null +++ b/reference/zip/functions/ziparchive-extractto.xml @@ -0,0 +1,115 @@ + + + + + ZipArchive::extractTo + Extract the archive contents + + + &reftitle.description; + + mixedZipArchive::extractTo + stringdestination + mixedentries + + + Extract the complete archive or the given files to the specified + destination. + + + + &reftitle.parameters; + + + + destination + + + Location where to extract the files. + + + + + entries + + + The entries to extract. It accepts either a single entry name or + an array of names. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + This example opens a ZIP file archive, reads each file in the + archive and prints out its contents. The + test2.zip archive used in this example is + one of the test archives in the ZZIPlib source distribution. + + + Extract all entries + +open('test.zip')) { + $zip->extractTo('/my/destination/dir/'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + Extract only tow entries + +open('test_im.zip'); +if ($res === TRUE) { + $zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php')); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-getarchivecomment.xml b/reference/zip/functions/ziparchive-getarchivecomment.xml new file mode 100644 index 0000000000..3e3b48e0bd --- /dev/null +++ b/reference/zip/functions/ziparchive-getarchivecomment.xml @@ -0,0 +1,66 @@ + + + + + ZipArchive::getArchiveComment + Returns the Zip archive comment + + + &reftitle.description; + + mixedZipArchive::getArchiveComment + + + + Returns the Zip archive comment or false on failure. + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Dump an archive comment + +open('test_with_comment.zip') +if ($res === TRUE) { + var_dump($zip->getArchiveComment()); + /* Or using the archive property */ + var_dump($zip->comment); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + + + + \ No newline at end of file diff --git a/reference/zip/functions/ziparchive-getcommentindex.xml b/reference/zip/functions/ziparchive-getcommentindex.xml new file mode 100644 index 0000000000..9a216a0a0f --- /dev/null +++ b/reference/zip/functions/ziparchive-getcommentindex.xml @@ -0,0 +1,89 @@ + + + + + ZipArchive::getCommentIndex + Returns the comment of an entry using the entry index + + + &reftitle.description; + + mixedZipArchive::getCommentIndex + integerindex + integerflags + + + Returns the comment of an entry using the entry index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry + + + + + flags + + + If flags is set to ZIPARCHIVE::FL_UNCHANGED, the original unchanged + comment is returned. + + + + + + + + &reftitle.returnvalues; + + Returns the comment on success or &false; on failure. + + + + &reftitle.examples; + + Dump an entry comment + +open('test1.zip') +if ($res === TRUE) { + var_dump($zip->getCommentIndex(1)); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-getcommentname.xml b/reference/zip/functions/ziparchive-getcommentname.xml new file mode 100644 index 0000000000..d729f2247d --- /dev/null +++ b/reference/zip/functions/ziparchive-getcommentname.xml @@ -0,0 +1,89 @@ + + + + + ZipArchive::getCommentName + Returns the comment of an entry using the entry name + + + &reftitle.description; + + mixedZipArchive::getCommentName + stringname + integerflags + + + Returns the comment of an entry using the entry name. + + + + &reftitle.parameters; + + + + name + + + Name of the entry + + + + + flags + + + If flags is set to ZIPARCHIVE::FL_UNCHANGED, the original unchanged + comment is returned. + + + + + + + + &reftitle.returnvalues; + + Returns the comment on success or &false; on failure. + + + + &reftitle.examples; + + Dump an entry comment + +open('test1.zip') +if ($res === TRUE) { + var_dump($zip->getCommentName('test/entry1.txt')); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-getfromindex.xml b/reference/zip/functions/ziparchive-getfromindex.xml new file mode 100644 index 0000000000..66b164f138 --- /dev/null +++ b/reference/zip/functions/ziparchive-getfromindex.xml @@ -0,0 +1,101 @@ + + + + + ZipArchive::getFromIndex + Returns the entry contents using its index. + + + &reftitle.description; + + mixedZipArchive::getFromIndex + integerindex + integerflags + + + Returns the entry contents using its index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry + + + + + flags + + + The flags to use to open the archive. the following values may + be ORed to it. + + + + ZIPARCHIVE::FL_UNCHANGED + + + + + ZIPARCHIVE::FL_COMPRESSED + + + + + + + + + + + &reftitle.returnvalues; + + Returns the contents of the entry on success or &false; on failure. + + + + &reftitle.examples; + + Get the file contents + +open(realpath('test.zip'))) { + echo $zip->getFromIndex(2); + $zip->close(); +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-getfromname.xml b/reference/zip/functions/ziparchive-getfromname.xml new file mode 100644 index 0000000000..c8c8e6f867 --- /dev/null +++ b/reference/zip/functions/ziparchive-getfromname.xml @@ -0,0 +1,125 @@ + + + + + ZipArchive::getFromName + Returns the entry contents using its name. + + + &reftitle.description; + + mixedZipArchive::getFromName + stringname + integerflags + + + Returns the entry contents using its name. + + + + &reftitle.parameters; + + + + name + + + Name of the entry + + + + + flags + + + The flags to use to open the archive. the following values may + be ORed to it. + + + + ZIPARCHIVE::FL_NOCASE + + + + + ZIPARCHIVE::FL_NODIR + + + + + ZIPARCHIVE::FL_UNCHANGED + + + + + ZIPARCHIVE::FL_COMPRESSED + + + + + + + + + + + &reftitle.returnvalues; + + Returns &true; on success or &false; on failure. + + + + &reftitle.examples; + + Get the file contents + +open(realpath('test1.zip'))) { + echo $zip->getFromName('testfromfile.php'); + $zip->close(); +} else { + echo 'failed'; +} +?> +]]> + + + + Convert an image from a zip entry + +open(dirname(__FILE__) . '/test_im.zip'); +$im_string = $z->getFromName("pear_item.gif"); +$im = imagecreatefromstring($im_string); +imagepng($im, 'b.png'); +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-getnameindex.xml b/reference/zip/functions/ziparchive-getnameindex.xml new file mode 100644 index 0000000000..ef82d458b6 --- /dev/null +++ b/reference/zip/functions/ziparchive-getnameindex.xml @@ -0,0 +1,60 @@ + + + + + ZipArchive::getNameIndex + Returns the name of an entry using its index + + + &reftitle.description; + + mixedZipArchive::getNameIndex + integerindex + + + Returns the name of an entry using its index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry. + + + + + + + + &reftitle.returnvalues; + + Returns the name on success or &false; on failure. + + + + + diff --git a/reference/zip/functions/ziparchive-getstream.xml b/reference/zip/functions/ziparchive-getstream.xml new file mode 100644 index 0000000000..228fb7e56e --- /dev/null +++ b/reference/zip/functions/ziparchive-getstream.xml @@ -0,0 +1,118 @@ + + + + + ZipArchive::getStream + Get a file handler to the entry defined by its name (read only). + + + &reftitle.description; + + mixedZipArchive::getStream + stringname + + + Get a file handler to the entry defined by its name. For now it only + supports read operations. + + + + &reftitle.parameters; + + + + name + + + The name of the entry to use. + + + + + + + + &reftitle.returnvalues; + + Returns a file pointer (resource) on success or &false; on failure. + + + + &reftitle.examples; + + Get the entry contents with fread and store it. + +open(dirname(__FILE__) . '/test.zip'); +$fp = $z->getStream('test'); +if(!$fp) exit("failed\n"); + +while (!feof($fp)) { + $contents .= fread($fp, 2); +} + +fclose($fp); +file_put_contents('t',$contents); +echo "done.\n"; +?> +]]> + + + + Same as the previous example but with fopen and the zip + stream wrapper + + +]]> + + + + Stream wrapper and image, can be used with the xml function + as well + + +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-locatename.xml b/reference/zip/functions/ziparchive-locatename.xml new file mode 100644 index 0000000000..42b26d525f --- /dev/null +++ b/reference/zip/functions/ziparchive-locatename.xml @@ -0,0 +1,121 @@ + + + + + ZipArchive::locateName + Open a ZIP file archive + + + &reftitle.description; + + mixedZipArchive::locateName + stringname + integerflags + + + Locates an entry using its name. + + + + &reftitle.parameters; + + + + name + + + The name of the entry to look up + + + + + flags + + + The function returns the index of the file named fname in + archive. The flags are specified by ORing the following values, + or 0 for none of them. + + + + ZIPARCHIVE::FL_NOCASE + + + + + ZIPARCHIVE::FL_NODIR + + + + + + + + + + + &reftitle.returnvalues; + + Returns the index of the entry on success or &false; on failure. + + + + &reftitle.examples; + + Create an archive and then use it with locateName + +open($file, ZIPARCHIVE::CREATE) !== TRUE) { + exit('failed'); +} + +$zip->addFromString('entry1.txt', 'entry #1'); +$zip->addFromString('entry2.txt', 'entry #2'); +$zip->addFromString('dir/entry2d.txt', 'entry #2'); + +if (!$zip->status == ZIPARCHIVE::ER_OK) { + echo "failed to write zip\n"; +} +$zip->close(); + +if ($zip->open($file) === TRUE) { + exit('failed'); +} + +echo $zip->locateName('entry1.txt') . "\n"; +echo $zip->locateName('eNtry2.txt') . "\n"; +echo $zip->locateName('eNtry2.txt', ZIPARCHIVE::FL_NOCASE) . "\n"; +echo $zip->locateName('enTRy2d.txt', ZIPARCHIVE::FL_NOCASE|ZIPARCHIVE::FL_NODIR) . "\n"; +$zip->close(); + +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-open.xml b/reference/zip/functions/ziparchive-open.xml new file mode 100644 index 0000000000..7f6857fa06 --- /dev/null +++ b/reference/zip/functions/ziparchive-open.xml @@ -0,0 +1,188 @@ + + + + + ZipArchive::open + Open a ZIP file archive + + + &reftitle.description; + + mixedZipArchive::open + stringfilename + integerflags + + + Opens a new zip archive for reading, writing or modifying. + + + + &reftitle.parameters; + + + + filename + + + The file name of the ZIP archive to open. + + + + + flags + + + The mode to use to open the archive. + + + + ZIPARCHIVE::CREATE + + + + + ZIPARCHIVE::EXCL + + + + + ZIPARCHIVE::CHECKCONS + + + + + + + + + + + &reftitle.returnvalues; + + + + Error codes + + + Returns &true; on success or the error code. + + + + ZIPARCHIVE::ER_EXISTS + + + + + ZIPARCHIVE::ER_INCONS + + + + + ZIPARCHIVE::ER_INVAL + + + + + ZIPARCHIVE::ER_MEMORY + + + + + ZIPARCHIVE::ER_NOENT + + + + + ZIPARCHIVE::ER_NOZIP + + + + + ZIPARCHIVE::ER_OPEN + + + + + ZIPARCHIVE::ER_READ + + + + + ZIPARCHIVE::ER_SEEK + + + + + + + + + + + &reftitle.examples; + + This example opens a ZIP file archive, reads each file in the + archive and prints out its contents. The + test2.zip archive used in this example is + one of the test archives in the ZZIPlib source distribution. + + + Open and extract + +open('test.zip') +if ($res === TRUE) { + echo 'ok'; + $zip->extractTo('test'); + $zip->close(); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + + Create an archive + +open('test.zip', ZipArchive::CREATE); +if ($res === TRUE) { + $zip->addFromString('test.txt', 'file content goes here'); + $zip->addFile('data.txt', 'entryname.txt'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-renameindex.xml b/reference/zip/functions/ziparchive-renameindex.xml new file mode 100644 index 0000000000..db3c80a1e7 --- /dev/null +++ b/reference/zip/functions/ziparchive-renameindex.xml @@ -0,0 +1,89 @@ + + + + + ZipArchive::renameIndex + Renames an entry defined by its index + + + &reftitle.description; + + booleanZipArchive::renameIndex + integerindex + stringnewname + + + Renames an entry defined by its index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry to rename. + + + + + newname + + + New name. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Rename one entry + +open('test.zip') +if ($res === TRUE) { + $zip->renameIndex(2,'newname.txt'); + $zip->close(); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-renamename.xml b/reference/zip/functions/ziparchive-renamename.xml new file mode 100644 index 0000000000..dda710f88a --- /dev/null +++ b/reference/zip/functions/ziparchive-renamename.xml @@ -0,0 +1,89 @@ + + + + + ZipArchive::renameName + Renames an entry defined by its name + + + &reftitle.description; + + booleanZipArchive::renameName + stringname + stringnewname + + + Renames an entry defined by its index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry to rename. + + + + + newname + + + New name. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Rename one entry + +open('test.zip') +if ($res === TRUE) { + $zip->renameIndex('currentname.txt','newname.txt'); + $zip->close(); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-setarchivecomment.xml b/reference/zip/functions/ziparchive-setarchivecomment.xml new file mode 100644 index 0000000000..8720a1ed71 --- /dev/null +++ b/reference/zip/functions/ziparchive-setarchivecomment.xml @@ -0,0 +1,82 @@ + + + + + ZipArchive::setArchiveComment + Set the comment of a ZIP archive + + + &reftitle.description; + + mixedZipArchive::setArchiveComment + stringcomment + + + Set the comment of a ZIP archive. + + + + &reftitle.parameters; + + + + comment + + + The contents of the comment. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Create an archive and set a comment + +open('test.zip', ZipArchive::CREATE); +if ($res === TRUE) { + $zip->addFromString('test.txt', 'file content goes here'); + $z->setArchiveComment('new archive comment'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-setcommentindex.xml b/reference/zip/functions/ziparchive-setcommentindex.xml new file mode 100644 index 0000000000..62f10b1d4f --- /dev/null +++ b/reference/zip/functions/ziparchive-setcommentindex.xml @@ -0,0 +1,90 @@ + + + + + ZipArchive::setCommentIndex + Set the comment of an entry defined by its index + + + &reftitle.description; + + mixedZipArchive::setCommentIndex + integerindex + stringcomment + + + Set the comment of an entry defined by its index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry. + + + + + comment + + + The contents of the comment. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Open an archive and set a comment for an entry + +open('test.zip'); +if ($res === TRUE) { + $z->setCommentIndex(2, 'new entry comment'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-setcommentname.xml b/reference/zip/functions/ziparchive-setcommentname.xml new file mode 100644 index 0000000000..d4cfca91ce --- /dev/null +++ b/reference/zip/functions/ziparchive-setcommentname.xml @@ -0,0 +1,90 @@ + + + + + ZipArchive::setCommentName + Set the comment of an entry defined by its name + + + &reftitle.description; + + mixedZipArchive::setCommentIndex + stringname + stringcomment + + + Set the comment of an entry defined by its name. + + + + &reftitle.parameters; + + + + name + + + Name of the entry. + + + + + comment + + + The contents of the comment. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.examples; + + Open an archive and set a comment for an entry + +open('test.zip'); +if ($res === TRUE) { + $z->setCommentName('entry1.txt', 'new entry comment'); + $zip->close(); + echo 'ok'; +} else { + echo 'failed'; +} +?> +]]> + + + + + + diff --git a/reference/zip/functions/ziparchive-statindex.xml b/reference/zip/functions/ziparchive-statindex.xml new file mode 100644 index 0000000000..147f8853bf --- /dev/null +++ b/reference/zip/functions/ziparchive-statindex.xml @@ -0,0 +1,111 @@ + + + + + ZipArchive::statIndex + Get the details of an entry defined by its index. + + + &reftitle.description; + + mixedZipArchive::statIndex + integerindex + integerflags + + + The function obtains information about the entry defined by its + index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry + + + + + flags + + + ZIPARCHIVE::FL_UNCHANGED may be ORed to it to request + information about the original file in the archive, + ignoring any changes made. + + + + + + + + &reftitle.returnvalues; + + Returns an array containing the entry details or false on failure. + + + + &reftitle.examples; + + Dump the stat info of an entry + +open('test.zip') +if ($res === TRUE) { + print_r($zip->statIndex(3)); + $zip->close(); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + This example will output : + + + foobar/baz + [index] => 3 + [crc] => 499465816 + [size] => 27 + [mtime] => 1123164748 + [comp_size] => 24 + [comp_method] => 8 +) +]]> + + + + + + + + diff --git a/reference/zip/functions/ziparchive-statname.xml b/reference/zip/functions/ziparchive-statname.xml new file mode 100644 index 0000000000..89a2e2f36a --- /dev/null +++ b/reference/zip/functions/ziparchive-statname.xml @@ -0,0 +1,129 @@ + + + + + ZipArchive::statName + Get the details of an entry defined by its name. + + + &reftitle.description; + + mixedZipArchive::statName + namename + integerflags + + + The function obtains information about the entry defined by its + name. + + + + &reftitle.parameters; + + + + index + + + Index of the entry + + + + + flags + + + The flags argument specifies how the name lookup should be done. + Also, ZIPARCHIVE::FL_UNCHANGED may be ORed to it to request + information about the original file in the archive, + ignoring any changes made. + + + + ZIPARCHIVE::FL_NOCASE + + + + + ZIPARCHIVE::FL_NODIR + + + + + ZIPARCHIVE::FL_UNCHANGED + + + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing the entry details or false on failure. + + + + &reftitle.examples; + + Dump the stat info of an entry + +open('test.zip') +if ($res === TRUE) { + print_r($zip->statName('foobar/baz')); + $zip->close(); +} else { + echo 'failed, code:' . $res; +} +?> +]]> + + + This example will output : + + + foobar/baz + [index] => 3 + [crc] => 499465816 + [size] => 27 + [mtime] => 1123164748 + [comp_size] => 24 + [comp_method] => 8 +) +]]> + + + + + + + + diff --git a/reference/zip/functions/ziparchive-unchangeall.xml b/reference/zip/functions/ziparchive-unchangeall.xml new file mode 100644 index 0000000000..2a24cc54bc --- /dev/null +++ b/reference/zip/functions/ziparchive-unchangeall.xml @@ -0,0 +1,45 @@ + + + + + ZipArchive::unchangeAll + Undo all changes done in the archive. + + + &reftitle.description; + + mixedZipArchive::unchangeAll + + + + Undo all changes done in the archive. + + + + &reftitle.returnvalues; + + &return.success; + + + + + diff --git a/reference/zip/functions/ziparchive-unchangearchive.xml b/reference/zip/functions/ziparchive-unchangearchive.xml new file mode 100644 index 0000000000..ab5c34e28c --- /dev/null +++ b/reference/zip/functions/ziparchive-unchangearchive.xml @@ -0,0 +1,46 @@ + + + + + ZipArchive::unchangeArchive + Revert all global changes done in the archive. + + + &reftitle.description; + + mixedZipArchive::unchangeArchive + + + + Revert all global changes to the archive archive. For now, this + only reverts archive comment changes. + + + + &reftitle.returnvalues; + + &return.success; + + + + + diff --git a/reference/zip/functions/ziparchive-unchangeindex.xml b/reference/zip/functions/ziparchive-unchangeindex.xml new file mode 100644 index 0000000000..3a7e3cff43 --- /dev/null +++ b/reference/zip/functions/ziparchive-unchangeindex.xml @@ -0,0 +1,60 @@ + + + + + ZipArchive::unchangeIndex + Revert all changes done to an entry at the given index. + + + &reftitle.description; + + mixedZipArchive::unchangeIndex + integerindex + + + Revert all changes done to an entry at the given index. + + + + &reftitle.parameters; + + + + index + + + Index of the entry. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + diff --git a/reference/zip/functions/ziparchive-unchangename.xml b/reference/zip/functions/ziparchive-unchangename.xml new file mode 100644 index 0000000000..cd43bf8d60 --- /dev/null +++ b/reference/zip/functions/ziparchive-unchangename.xml @@ -0,0 +1,61 @@ + + + + + + ZipArchive::unchangeName + Revert all changes done to an entry with the given name. + + + &reftitle.description; + + mixedZipArchive::unchangeName + stringname + + + Revert all changes done to an entry. + + + + &reftitle.parameters; + + + + name + + + Name of the entry. + + + + + + + + &reftitle.returnvalues; + + Returns &false; on success or &false; on failure. + + + + + diff --git a/reference/zip/reference.xml b/reference/zip/reference.xml index 2aa1ab8af6..811e4032e8 100644 --- a/reference/zip/reference.xml +++ b/reference/zip/reference.xml @@ -1,42 +1,49 @@ - + - Zip File Functions (Read Only Access) + Zip File Functions Zip
&reftitle.intro; - This module enables you to transparently read ZIP compressed + This module enables you to transparently read or write ZIP compressed archives and the files inside them.
- +
&reftitle.required; +
+ PHP4 Bundled + + The initial version is bundled in PHP 4 and is available in PECL + as version 1.0, see + &url.pecl.package;zip. It can only read Zip Archives. + + + This version uses the functions of the ZZIPlib library by Guido Draheim. + You need ZZIPlib version >= 0.10.6. + +
+ +
+ PECL and PHP 5.2 or earlier - This module uses the functions of the ZZIPlib library by Guido Draheim. - You need ZZIPlib version >= 0.10.6. - - - The PECL package version 1.1.0 and up does not require any external - library. It also provides a write mode (creations and modifications). - The new features are not yet documented, please check the examples - included in the releases. - - - Note that ZZIPlib only provides a subset of functions - provided in a full implementation of the ZIP compression algorithm - and can only read ZIP file archives. A normal ZIP utility is - needed to create the ZIP file archives read by this library. + The newest version is bundled in PHP 5.2.0 or earlier and + available in PECL, as version 1.1.0 or earlier. It does not + require any external library. It can read and write Zip archives + when used with PHP 5.1 or ealier and can only read them when used + with PHP4. +
- + &reference.zip.configure;
@@ -46,21 +53,98 @@
&reftitle.resources; - &no.resource; + + There are two resource types used in the Zip module. The first one + is the Zip directory for the Zip archive, the second Zip Entry for + the archive entries. +
-
- &reftitle.constants; - &no.constants; -
+ &reference.zip.constants;
&reftitle.examples; + + Create a Zip archive + +open($filename, ZIPARCHIVE::CREATE)!==TRUE) { + exit("cannot open <$filename>\n"); +} + +$zip->addFromString("testfilephp.txt" . time(), "#1 This is a test string added as testfilephp.txt.\n"); +$zip->addFromString("testfilephp2.txt" . time(), "#2 This is a test string added as testfilephp2.txt.\n"); +$zip->addFile($thisdir . "/too.php","/testfromfile.php"); +echo "numfiles: " . $zip->numFiles . "\n"; +echo "status:" . $zip->status . "\n"; +$zip->close(); +?> +]]> + + + + Dump the archive details and listing + +open('test_with_comment.zip'); +print_r($za); +var_dump($za); +echo "numFiles: " . $za->numFiles . "\n"; +echo "status: " . $za->status . "\n"; +echo "statusSys: " . $za->statusSys . "\n"; +echo "filename: " . $za->filename . "\n"; +echo "comment: " . $za->comment . "\n"; + +for ($i=0; $i<$za->numFiles;$i++) { + echo "index: $i\n"; + print_r($za->statIndex($i)); +} +echo "numFile:" . $za->numFiles . "\n"; +?> +]]> + + + + Zip stream wrapper, read an OpenOffice meta info + +open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml'); +$odt_meta = array(); +while ($reader->read()) { + if ($reader->nodeType == XMLREADER::ELEMENT) { + $elm = $reader->name; + } else { + if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') { + break; + } + if (!trim($reader->value)) { + continue; + } + $odt_meta[$elm] = $reader->value; + } +} +print_r($odt_meta); +?> +]]> + + - This example opens a ZIP file archive, reads each file in the - archive and prints out its contents. The - test2.zip archive used in this example is - one of the test archives in the ZZIPlib source distribution. + This example uses the old API (PHP 4), it opens a ZIP file + archive, reads each file in the archive and prints out its + contents. The test2.zip archive used in this + example is one of the test archives in the ZZIPlib source + distribution. Zip Usage Example @@ -71,7 +155,6 @@ $zip = zip_open("/tmp/test2.zip"); if ($zip) { - while ($zip_entry = zip_read($zip)) { echo "Name: " . zip_entry_name($zip_entry) . "\n"; echo "Actual Filesize: " . zip_entry_filesize($zip_entry) . "\n"; @@ -92,7 +175,6 @@ if ($zip) { zip_close($zip); } - ?> ]]> @@ -101,7 +183,6 @@ if ($zip) { &reference.zip.functions; -