ZipTBS

version 2.3, 2010-11-29, by Skrol29

Introduction
Features
Limitations
Synopsis
Change-log
Contact and license

1. Introduction

TbsZip can read a zip archives, virtually modify the archive and create a new one without any temporary file. While this class is independent from other libraries, it has been first created for the OpenTBS project which is a plugin for the TinyButStrong Template Engine. OpenTBS makes TinyButStrong able to build OpenOffice and Ms Office documents with the technique of templates.

See the OpenTBS demo.
See other TinyButStrong plugins.

2. Features

can read a common zip archive, or start with an empty archive
can modify the content of files in the archive (replace, delete or add new file)
the new file content can come from a PHP string, or an external physical file
the modified archive can be released as a new physical file, an HTTP download, or a PHP string
the original archive is not modified
the class does not use temporary files: when the new archive is flushed, unmodified parts of the archives are directly streamed from the original archive, modified parts are streamed form their sources (external physical files, or PHP string)

3. Limitations

doesn't support Zip64 archives
doesn't support zip file comments (very rarely used, not editable in 7-Zip yet)
needs the Zlib extension only to compress or uncompress files in the archive (Zlib is commonly available in most of PHP installations)

4. Synopsis

Method or Property	Description
Open($ArchFile)	Open an original Zip archive (it can be an Open Office document, an MS Office document or any other Zip archive).
CreateNew()	Create a new empty Zip archive. The new archive is virtually prepared in the PHP memory, nothing is written at this point. Methods FileExists(), FileRead() and FileReplace() cannot be used when you work on an new archive created by CreateNew(), simply because the archive is empty. Versioning: method CreateNew() is supported since TbsZip version 2.1
FileExists($NameOrIdx)	Return true if the file exists in the original archive. $NameOrIdx must be the full name (including folder name inside the archive) or the index of an existing file in the archive.
FileRead($NameOrIdx, $Uncompress=true)	Return the contents of the file stored in the original archive. If $Uncompress is true, then TbsZip try to uncompressed the contents if needed. If the file is compressed but TbsZip cannot uncompress it then an error message is set to property Error. You can check if the result is compressed using property LastReadComp.
FileReplace($NameOrIdx, $Data, $DataType=TBSZIP_STRING, $Compress=true)	Replace or delete an existing file in the archive. Set $Data=false in order to delete the file. $DataType accepts TBSZIP_STRING and TBSZIP_FILE ($Data must then be the path of the external file to insert). $Compress can be true, false or an array with keys ('meth','len_u','crc32') which means that the data is already previously compressed. Note that the original archive is not modified, modifications will be provided as a new archive when you call the method Flush(). Return false if the file has not been replaced or deleted. Return true if the file has been successfully deleted. Return -1 if the file could not be compressed and has been stored uncompressed. Return 0 if the file has been stored uncompressed as expected. Return 1 if the file has been stored compressed has expected. Return 2 if the file has been stored as is with pre-compression as defined in the array $Compress. It's very interesting to know that when you add or replace a file in the archive with an external file (i.e. using option TBSZIP_FILE), then the contents of the file is not loaded immediately in PHP memory. It will be loaded, compressed and output on the fly and one by one when method Flush() is called. Thus, you can add lot of files in an archive without occupying the PHP memory.
FileAdd($Name, $Data, $DataType=TBSZIP_STRING, $Compress=true)	Add a new file in the archive, works like FileReplace(). Note that the original archive is not modified, modifications will be provided as a new archive when you call the method Flush(). If $Data is false then the previously add file with the given name is canceled if any.
FileCancelModif($NameOrIdx)	Cancel add, delete and replacements in the archive for the given file name. Return the number of cancels.
Flush($Render=TBSZIP_DOWNLOAD, $File='', $ContentType='')	Actually create the new archive with all modifications. External files to be inserted are loaded, compressed and output on the fly and one by one without staying in the PHP memory. $Render=TBSZIP_DOWNLOAD will provide the new archive as a download with HTTP headers. Use $File to customize the name of the downloaded file. Use $ContentType to customize the ContentType header. $Render=TBSZIP_DOWNLOAD + TBSZIP_NOHEADER will provide the new archive as a download without HTTP. $Render=TBSZIP_FILE will provide the new archive as a physical file on the server. Use $File to define the path of the physical file. $Render=TBSZIP_STRING will make method Flush() to return the new archive as a binary string
Debug()	Display information about the original archive.
Close()	Close the opened original archive.
ArchFile	Full path of the opened original archive.
CdFileLst	An array listing all existing files in the original archive with some technical information.
LastReadIdx	Index of the last file read by FileRead(). false means the file was not found in the archive,
LastReadComp	Compression information about of the last file read by FileRead(). false means the file was not found in the archive, -1 means the file was compressed and has been successfully uncompressed, 0 means the file was not compressed, 1 means the file was compressed but TbsZip was unable to uncompress.
Error	Last error message, or false if no error. Errors are not prompted; use this property in order to check errors.

5. Change log

Version 2.3, 2010-11-29
- minor bug fixed: an archive created with both methods CreateNew() and Flush(TBSZIP_DOWNLOAD) could be truncated because the final size of the archive was badly estimated.

Version 2.2, 2010-10-28
- major bug fixed: some added or modified files can be saved in the archive with a wrong CRC control code. This could make softwares to consider the file or the archive as corrupted. Only few CRC codes are wrongly saved, thus the bug is rare and can seem to appear randomly.

Version 2.1, 2010-07-01
- bug fixed: when adding a new file in the archive, the time of the file was wrong (date was ok)
- TbsZip now changes the date and time of a file in the archive when the file content is replaced
- new method CreateNew()

6. Contact and license

Author: Skrol29

License: LGLP