001: // --------------------------------------------------------------------------------
002: // PclZip 2.8.2 - readme.txt
003: // --------------------------------------------------------------------------------
004: // License GNU/LGPL - August 2009
005: // Vincent Blavet - vincent@phpconcept.net
006: // http://www.phpconcept.net
007: // --------------------------------------------------------------------------------
008: // $Id: readme.txt,v 1.60 2009/09/30 20:35:21 vblavet Exp $
009: // --------------------------------------------------------------------------------
010:
011:
012:
013: 0 - Sommaire
014: ============
015: 1 - Introduction
016: 2 - What's new
017: 3 - Corrected bugs
018: 4 - Known bugs or limitations
019: 5 - License
020: 6 - Warning
021: 7 - Documentation
022: 8 - Author
023: 9 - Contribute
024:
025: 1 - Introduction
026: ================
027:
028: PclZip is a library that allow you to manage a Zip archive.
029:
030: Full documentation about PclZip can be found here : http://www.phpconcept.net/pclzip
031:
032: 2 - What's new
033: ==============
034:
035: Version 2.8.2 :
036: - PCLZIP_CB_PRE_EXTRACT and PCLZIP_CB_POST_EXTRACT are now supported with
037: extraction as a string (PCLZIP_OPT_EXTRACT_AS_STRING). The string
038: can also be modified in the post-extract call back.
039: **Bugs correction :
040: - PCLZIP_OPT_REMOVE_ALL_PATH was not working correctly
041: - Remove use of eval() and do direct call to callback functions
042: - Correct support of 64bits systems (Thanks to WordPress team)
043:
044: Version 2.8.1 :
045: - Move option PCLZIP_OPT_BY_EREG to PCLZIP_OPT_BY_PREG because ereg() is
046: deprecated in PHP 5.3. When using option PCLZIP_OPT_BY_EREG, PclZip will
047: automatically replace it by PCLZIP_OPT_BY_PREG.
048:
049: Version 2.8 :
050: - Improve extraction of zip archive for large files by using temporary files
051: This feature is working like the one defined in r2.7.
052: Options are renamed : PCLZIP_OPT_TEMP_FILE_ON, PCLZIP_OPT_TEMP_FILE_OFF,
053: PCLZIP_OPT_TEMP_FILE_THRESHOLD
054: - Add a ratio constant PCLZIP_TEMPORARY_FILE_RATIO to configure the auto
055: sense of temporary file use.
056: - Bug correction : Reduce filepath in returned file list to remove ennoying
057: './/' preambule in file path. 058:
059: Version 2.7 :
060: - Improve creation of zip archive for large files :
061: PclZip will now autosense the configured memory and use temporary files
062: when large file is suspected.
063: This feature can also ne triggered by manual options in create() and add()
064: methods. 'PCLZIP_OPT_ADD_TEMP_FILE_ON' force the use of temporary files,
065: 'PCLZIP_OPT_ADD_TEMP_FILE_OFF' disable the autosense technic, 066: 'PCLZIP_OPT_ADD_TEMP_FILE_THRESHOLD' allow for configuration of a size 067: threshold to use temporary files.
068: Using "temporary files" rather than "memory" might take more time, but
069: might give the ability to zip very large files :
070: Tested on my win laptop with a 88Mo file :
071: Zip "in-memory" : 18sec (max_execution_time=30, memory_limit=180Mo)
072: Zip "tmporary-files" : 23sec (max_execution_time=30, memory_limit=30Mo)
073: - Replace use of mktime() by time() to limit the E_STRICT error messages.
074: - Bug correction : When adding files with full windows path (drive letter)
075: PclZip is now working. Before, if the drive letter is not the default
076: path, PclZip was not able to add the file.
077:
078: Version 2.6 :
079: - Code optimisation
080: - New attributes PCLZIP_ATT_FILE_COMMENT gives the ability to
081: add a comment for a specific file. (Don't really know if this is usefull)
082: - New attribute PCLZIP_ATT_FILE_CONTENT gives the ability to add a string
083: as a file.
084: - New attribute PCLZIP_ATT_FILE_MTIME modify the timestamp associated with
085: a file.
086: - Correct a bug. Files archived with a timestamp with 0h0m0s were extracted
087: with current time
088: - Add CRC value in the informations returned back for each file after an
089: action.
090: - Add missing closedir() statement.
091: - When adding a folder, and removing the path of this folder, files were
092: incorrectly added with a '/' at the beginning. Which means files are
093: related to root in unix systems. Corrected.
094: - Add conditional if before constant definition. This will allow users
095: to redefine constants without changing the file, and then improve
096: upgrade of pclzip code for new versions.
097:
098: Version 2.5 :
099: - Introduce the ability to add file/folder with individual properties (file descriptor).
100: This gives for example the ability to change the filename of a zipped file.
101: . Able to add files individually
102: . Able to change full name
103: . Able to change short name
104: . Compatible with global options
105: - New attributes : PCLZIP_ATT_FILE_NAME, PCLZIP_ATT_FILE_NEW_SHORT_NAME, PCLZIP_ATT_FILE_NEW_FULL_NAME
106: - New error code : PCLZIP_ERR_INVALID_ATTRIBUTE_VALUE
107: - Add a security control feature. PclZip can extract any file in any folder
108: of a system. People may use this to upload a zip file and try to override
109: a system file. The PCLZIP_OPT_EXTRACT_DIR_RESTRICTION will give the
110: ability to forgive any directory transversal behavior.
111: - New PCLZIP_OPT_EXTRACT_DIR_RESTRICTION : check extraction path
112: - New error code : PCLZIP_ERR_DIRECTORY_RESTRICTION
113: - Modification in PclZipUtilPathInclusion() : dir and path beginning with ./ will be prepend
114: by current path (getcwd())
115:
116: Version 2.4 :
117: - Code improvment : try to speed up the code by removing unusefull call to pack()
118: - Correct bug in delete() : delete() should be called with no argument. This was not
119: the case in 2.3. This is corrected in 2.4.
120: - Correct a bug in path_inclusion function. When the path has several '../../', the
121: result was bad.
122: - Add a check for magic_quotes_runtime configuration. If enabled, PclZip will
123: disable it while working and det it back to its original value.
124: This resolve a lots of bad formated archive errors.
125: - Bug correction : PclZip now correctly unzip file in some specific situation,
126: when compressed content has same size as uncompressed content.
127: - Bug correction : When selecting option 'PCLZIP_OPT_REMOVE_ALL_PATH',
128: directories are not any more created.
129: - Code improvment : correct unclosed opendir(), better handling of . and .. in
130: loops.
131:
132:
133: Version 2.3 :
134: - Correct a bug with PHP5 : affecting the value 0xFE49FFE0 to a variable does not
135: give the same result in PHP4 and PHP5 ....
136:
137: Version 2.2 :
138: - Try development of PCLZIP_OPT_CRYPT .....
139: However this becomes to a stop. To crypt/decrypt I need to multiply 2 long integers,
140: the result (greater than a long) is not supported by PHP. Even the use of bcmath
141: functions does not help. I did not find yet a solution ...;
142: - Add missing '/' at end of directory entries
143: - Check is a file is encrypted or not. Returns status 'unsupported_encryption' and/or
144: error code PCLZIP_ERR_UNSUPPORTED_ENCRYPTION.
145: - Corrected : Bad "version need to extract" field in local file header
146: - Add private method privCheckFileHeaders() in order to check local and central
147: file headers. PclZip is now supporting purpose bit flag bit 3. Purpose bit flag bit 3 gives
148: the ability to have a local file header without size, compressed size and crc filled.
149: - Add a generic status 'error' for file status
150: - Add control of compression type. PclZip only support deflate compression method.
151: Before v2.2, PclZip does not check the compression method used in an archive while
152: extracting. With v2.2 PclZip returns a new error status for a file using an unsupported
153: compression method. New status is "unsupported_compression". New error code is
154: PCLZIP_ERR_UNSUPPORTED_COMPRESSION.
155: - Add optional attribute PCLZIP_OPT_STOP_ON_ERROR. This will stop the extract of files
156: when errors like 'a folder with same name exists' or 'a newer file exists' or
157: 'a write protected file' exists, rather than set a status for the concerning file 158: and resume the extract of the zip.
159: - Add optional attribute PCLZIP_OPT_REPLACE_NEWER. This will force, during an extract' the
160: replacement of the file, even if a newer version of the file exists.
161: Note that today if a file with the same name already exists but is older it will be
162: replaced by the extracted one.
163: - Improve PclZipUtilOption()
164: - Support of zip archive with trailing bytes. Before 2.2, PclZip checks that the central
165: directory structure is the last data in the archive. Crypt encryption/decryption of
166: zip archive put trailing 0 bytes after decryption. PclZip is now supporting this.
167:
168: Version 2.1 :
169: - Add the ability to abort the extraction by using a user callback function.
170: The user can now return the value '2' in its callback which indicates to stop the
171: extraction. For a pre call-back extract is stopped before the extration of the current
172: file. For a post call back, the extraction is stopped after.
173: - Add the ability to extract a file (or several files) directly in the standard output.
174: This is done by the new parameter PCLZIP_OPT_EXTRACT_IN_OUTPUT with method extract().
175: - Add support for parameters PCLZIP_OPT_COMMENT, PCLZIP_OPT_ADD_COMMENT,
176: PCLZIP_OPT_PREPEND_COMMENT. This will create, replace, add, or prepend comments
177: in the zip archive.
178: - When merging two archives, the comments are not any more lost, but merged, with a
179: blank space separator.
180: - Corrected bug : Files are not deleted when all files are asked to be deleted.
181: - Corrected bug : Folders with name '0' made PclZip to abort the create or add feature.
182:
183:
184: Version 2.0 :
185: ***** Warning : Some new features may break the backward compatibility for your scripts.
186: Please carefully read the readme file.
187: - Add the ability to delete by Index, name and regular expression. This feature is
188: performed by the method delete(), which uses the optional parameters
189: PCLZIP_OPT_BY_INDEX, PCLZIP_OPT_BY_NAME, PCLZIP_OPT_BY_EREG or PCLZIP_OPT_BY_PREG.
190: - Add the ability to extract by regular expression. To extract by regexp you must use the method
191: extract(), with the option PCLZIP_OPT_BY_EREG or PCLZIP_OPT_BY_PREG
192: (depending if you want to use ereg() or preg_match() syntax) followed by the
193: regular expression pattern.
194: - Add the ability to extract by index, directly with the extract() method. This is a
195: code improvment of the extractByIndex() method.
196: - Add the ability to extract by name. To extract by name you must use the method
197: extract(), with the option PCLZIP_OPT_BY_NAME followed by the filename to
198: extract or an array of filenames to extract. To extract all a folder, use the folder
199: name rather than the filename with a '/' at the end.
200: - Add the ability to add files without compression. This is done with a new attribute
201: which is PCLZIP_OPT_NO_COMPRESSION.
202: - Add the attribute PCLZIP_OPT_EXTRACT_AS_STRING, which allow to extract a file directly
203: in a string without using any file (or temporary file).
204: - Add constant PCLZIP_SEPARATOR for static configuration of filename separators in a single string.
205: The default separator is now a comma (,) and not any more a blank space.
206: THIS BREAK THE BACKWARD COMPATIBILITY : Please check if this may have an impact with
207: your script.
208: - Improve algorythm performance by removing the use of temporary files when adding or
209: extracting files in an archive.
210: - Add (correct) detection of empty filename zipping. This can occurs when the removed
211: path is the same
212: as a zipped dir. The dir is not zipped (['status'] = filtered), only its content.
213: - Add better support for windows paths (thanks for help from manus@manusfreedom.com).
214: - Corrected bug : When the archive file already exists with size=0, the add() method
215: fails. Corrected in 2.0.
216: - Remove the use of OS_WINDOWS constant. Use php_uname() function rather.
217: - Control the order of index ranges in extract by index feature.
218: - Change the internal management of folders (better handling of internal flag).
219:
220:
221: Version 1.3 :
222: - Removing the double include check. This is now done by include_once() and require_once()
223: PHP directives.
224: - Changing the error handling mecanism : Remove the use of an external error library.
225: The former PclError...() functions are replaced by internal equivalent methods.
226: By changing the environment variable PCLZIP_ERROR_EXTERNAL you can still use the former library.
227: Introducing the use of constants for error codes rather than integer values. This will help
228: in futur improvment.
229: Introduction of error handling functions like errorCode(), errorName() and errorInfo().
230: - Remove the deprecated use of calling function with arguments passed by reference.
231: - Add the calling of extract(), extractByIndex(), create() and add() functions
232: with variable options rather than fixed arguments.
233: - Add the ability to remove all the file path while extracting or adding,
234: without any need to specify the path to remove.
235: This is available for extract(), extractByIndex(), create() and add() functionS by using
236: the new variable options parameters :
237: - PCLZIP_OPT_REMOVE_ALL_PATH : by indicating this option while calling the fct.
238: - Ability to change the mode of a file after the extraction (chmod()).
239: This is available for extract() and extractByIndex() functionS by using
240: the new variable options parameters.
241: - PCLZIP_OPT_SET_CHMOD : by setting the value of this option.
242: - Ability to definition call-back options. These call-back will be called during the adding,
243: or the extracting of file (extract(), extractByIndex(), create() and add() functions) :
244: - PCLZIP_CB_PRE_EXTRACT : will be called before each extraction of a file. The user
245: can trigerred the change the filename of the extracted file. The user can triggered the
246: skip of the extraction. This is adding a 'skipped' status in the file list result value.
247: - PCLZIP_CB_POST_EXTRACT : will be called after each extraction of a file.
248: Nothing can be triggered from that point.
249: - PCLZIP_CB_PRE_ADD : will be called before each add of a file. The user
250: can trigerred the change the stored filename of the added file. The user can triggered the
251: skip of the add. This is adding a 'skipped' status in the file list result value.
252: - PCLZIP_CB_POST_ADD : will be called after each add of a file.
253: Nothing can be triggered from that point.
254: - Two status are added in the file list returned as function result : skipped & filename_too_long
255: 'skipped' is used when a call-back function ask for skipping the file. 256: 'filename_too_long' is used while adding a file with a too long filename to archive (the file is 257: not added)
258: - Adding the function PclZipUtilPathInclusion(), that check the inclusion of a path into
259: a directory.
260: - Add a check of the presence of the archive file before some actions (like list, ...)
261: - Add the initialisation of field "index" in header array. This means that by
262: default index will be -1 when not explicitly set by the methods.
263:
264: Version 1.2 :
265: - Adding a duplicate function.
266: - Adding a merge function. The merge function is a "quick merge" function,
267: it just append the content of an archive at the end of the first one. There
268: is no check for duplicate files or more recent files.
269: - Improve the search of the central directory end.
270:
271: Version 1.1.2 :
272:
273: - Changing the license of PclZip. PclZip is now released under the GNU / LGPL license
274: (see License section).
275: - Adding the optional support of a static temporary directory. You will need to configure
276: the constant PCLZIP_TEMPORARY_DIR if you want to use this feature.
277: - Improving the rename() function. In some cases rename() does not work (different
278: Filesystems), so it will be replaced by a copy() + unlink() functions.
279:
280: Version 1.1.1 :
281:
282: - Maintenance release, no new feature.
283:
284: Version 1.1 :
285:
286: - New method Add() : adding files in the archive
287: - New method ExtractByIndex() : partial extract of the archive, files are identified by
288: their index in the archive
289: - New method DeleteByIndex() : delete some files/folder entries from the archive,
290: files are identified by their index in the archive.
291: - Adding a test of the zlib extension presence. If not present abort the script.
292:
293: Version 1.0.1 :
294:
295: - No new feature
296:
297:
298: 3 - Corrected bugs
299: ==================
300:
301: Corrected in Version 2.0 :
302: - Corrected : During an extraction, if a call-back fucntion is used and try to skip
303: a file, all the extraction process is stopped.
304:
305: Corrected in Version 1.3 :
306: - Corrected : Support of static synopsis for method extract() is broken.
307: - Corrected : invalid size of archive content field (0xFF) should be (0xFFFF).
308: - Corrected : When an extract is done with a remove_path parameter, the entry for
309: the directory with exactly the same path is not skipped/filtered.
310: - Corrected : extractByIndex() and deleteByIndex() were not managing index in the
311: right way. For example indexes '1,3-5,11' will only extract files 1 and 11. This
312: is due to a sort of the index resulting table that puts 11 before 3-5 (sort on
313: string and not interger). The sort is temporarilly removed, this means that
314: you must provide a sorted list of index ranges.
315:
316: Corrected in Version 1.2 :
317:
318: - Nothing.
319:
320: Corrected in Version 1.1.2 :
321:
322: - Corrected : Winzip is unable to delete or add new files in a PclZip created archives.
323:
324: Corrected in Version 1.1.1 :
325:
326: - Corrected : When archived file is not compressed (0% compression), the
327: extract method fails.
328:
329: Corrected in Version 1.1 :
330:
331: - Corrected : Adding a complete tree of folder may result in a bad archive
332: creation.
333:
334: Corrected in Version 1.0.1 :
335:
336: - Corrected : Error while compressing files greater than PCLZIP_READ_BLOCK_SIZE (default=1024).
337:
338:
339: 4 - Known bugs or limitations
340: =============================
341:
342: Please publish bugs reports in SourceForge :
343: http://sourceforge.net/tracker/?group_id=40254&atid=427564
344:
345: In Version 2.x :
346: - PclZip does only support file uncompressed or compressed with deflate (compression method 8)
347: - PclZip does not support password protected zip archive
348: - Some concern were seen when changing mtime of a file while archiving.
349: Seems to be linked to Daylight Saving Time (PclTest_changing_mtime).
350:
351: In Version 1.2 :
352:
353: - merge() methods does not check for duplicate files or last date of modifications.
354:
355: In Version 1.1 :
356:
357: - Limitation : Using 'extract' fields in the file header in the zip archive is not supported.
358: - WinZip is unable to delete a single file in a PclZip created archive. It is also unable to
359: add a file in a PclZip created archive. (Corrected in v.1.2)
360:
361: In Version 1.0.1 :
362:
363: - Adding a complete tree of folder may result in a bad archive
364: creation. (Corrected in V.1.1).
365: - Path given to methods must be in the unix format (/) and not the Windows format (\).
366: Workaround : Use only / directory separators.
367: - PclZip is using temporary files that are sometime the name of the file with a .tmp or .gz
368: added suffix. Files with these names may already exist and may be overwritten.
369: Workaround : none.
370: - PclZip does not check if the zlib extension is present. If it is absent, the zip
371: file is not created and the lib abort without warning.
372: Workaround : enable the zlib extension on the php install
373:
374: In Version 1.0 :
375:
376: - Error while compressing files greater than PCLZIP_READ_BLOCK_SIZE (default=1024).
377: (Corrected in v.1.0.1)
378: - Limitation : Multi-disk zip archive are not supported.
379:
380:
381: 5 - License
382: ===========
383:
384: Since version 1.1.2, PclZip Library is released under GNU/LGPL license.
385: This library is free, so you can use it at no cost.
386:
387: HOWEVER, if you release a script, an application, a library or any kind of
388: code using PclZip library (or a part of it), YOU MUST :
389: - Indicate in the documentation (or a readme file), that your work
390: uses PclZip Library, and make a reference to the author and the web site
391: http://www.phpconcept.net
392: - Gives the ability to the final user to update the PclZip libary.
393:
394: I will also appreciate that you send me a mail (vincent@phpconcept.net), just to
395: be aware that someone is using PclZip.
396:
397: For more information about GNU/LGPL license : http://www.gnu.org
398:
399: 6 - Warning
400: =================
401:
402: This library and the associated files are non commercial, non professional work.
403: It should not have unexpected results. However if any damage is caused by this software
404: the author can not be responsible.
405: The use of this software is at the risk of the user.
406:
407: 7 - Documentation
408: =================
409: PclZip User Manuel is available in English on PhpConcept : http://www.phpconcept.net/pclzip/man/en/index.php
410: A Russian translation was done by Feskov Kuzma : http://php.russofile.ru/ru/authors/unsort/zip/
411:
412: 8 - Author
413: ==========
414:
415: This software was written by Vincent Blavet (vincent@phpconcept.net) on its leasure time.
416:
417: 9 - Contribute
418: ==============
419: If you want to contribute to the development of PclZip, please contact vincent@phpconcept.net.
420: If you can help in financing PhpConcept hosting service, please go to
421: http://www.phpconcept.net/soutien.php
422: