-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathtbszip_help.html
395 lines (382 loc) · 18 KB
/
tbszip_help.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="application/xhtml+xml; charset=utf-8" />
<title>TbsZip - a zip modifier for PHP</title>
<style type="text/css">
<!--
body,td,th {
font-family: Arial, sans-serif;
font-size: 13px;
}
.special {
background-color: #E6E6FF;
border: 1px solid #036;
padding: 3px;
margin-left: 10px;
}
.code {
font-family: "Courier New", Courier, monospace;
font-size: 12px;
margin-left: 10px;
color: #036;
background-color: #E1EBFF;
padding: 3px;
}
.versioning {
font-style: italic;
color: #060;
}
.note {
margin-left: 10px;
padding: 3px;
}
.warning {
color: #F30;
}
.value {
color: #036;
font-family: "Courier New", Courier, monospace;
font-size: 12px;
}
-->
</style></head>
<body>
<h1>TbsZip - a zip modifier for PHP</h1>
<div>version 2.17, 2023-09-17, by Skrol29<br />
document updated on 2024-03-06</div>
<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#features">Features</a></li>
<li><a href="#limitations">Limitations</a></li>
<li><a href="#example">Example</a></li>
<li><a href="#synopsis">Synopsis</a></li>
<li><a href="#misc">Contact and license</a></li>
</ol>
<h2><a name="intro" id="intro"></a>1. Introduction</h2>
<p><strong>TbsZip</strong> is a PHP class which can read a zip archive, and
even edit sub-files in the archive and then create a new archive. It works
without any temporary file.</p>
<p> While this class is independent from other libraries, it has been first
created for the <a href="http://www.tinybutstrong.com/plugins/opentbs/demo/demo.html">OpenTBS</a>
project which is a plugin for the <a href="http://www.tinybutstrong.com/">TinyButStrong</a>
Template Engine. OpenTBS makes TinyButStrong able to build OpenOffice and
Ms Office documents with the technique of templates.</p>
<p> See the <a href="http://www.tinybutstrong.com/plugins/opentbs/demo/demo.html">OpenTBS
demo</a>.<br />
See other <a href="http://www.tinybutstrong.com/plugins.php">TinyButStrong
plugins</a>.<br />
</p>
<h2><a name="features" id="intro2"></a>2. Features</h2>
<ul>
<li> can read a common zip archive, or start with an empty archive</li>
<li> can modify the content of files in the archive (replace, delete or
add new file)</li>
<li> the new file content can come from a PHP string, or an external
physical file</li>
<li> the modified archive can be released as a new physical file, an HTTP
download, or a PHP string</li>
<li> the original archive is not modified</li>
<li> 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) </li>
</ul>
<h2><a name="limitations" id="intro3"></a>3. Limitations</h2>
<ul>
<li>doesn't support Zip64 archives</li>
<li> doesn't support zip file comments (very rarely used, not editable in
7-Zip yet)</li>
<li> needs the <a href="http://www.php.net/manual/en/book.zlib.php">Zlib
extension</a> only to compress or uncompress files in the archive
(Zlib is commonly available in most of PHP installations)</li>
</ul>
<h2><a name="example" id="intro7"></a>4. Example</h2>
<pre class="code">$zip = new clsTbsZip(); <span class="versioning">// instantiate the class</span>
$zip->Open('archive1.zip'); <span class="versioning">// open an existing zip archive</span>
$ok = $zip->FileExists('innerfolder/subfile1.txt'); <span class="versioning">// check if a sub-file exist in the archive</span>
$txt = $zip->FileRead('subfile2.txt'); <span class="versioning">// retrieve the content of a sub-file</span>
... <span class="versioning">// some work on the $txt contents</span>
$zip->FileReplace('subfile2.txt', $txt, TBSZIP_STRING); <span class="versioning">// replace the existing sub-file</span>
$zip->FileReplace('subfile3.txt', false); <span class="versioning">// delete the existing sub-file</span>
$zip->FileAdd('subfile4.txt', $txt3, TBSZIP_STRING); <span class="versioning">// add a new sub-file</span>
$zip->Flush(TBSZIP_FILE, 'archive1_new.zip'); <span class="versioning">// flush the modifications as a new archive</span>
$zip->Close(); <span class="versioning">// close the current archive</span>
</pre>
<h2><a name="synopsis" id="intro4"></a>5. Synopsis</h2>
<p>Class name: clsTbsZip</p>
<table cellspacing="2" cellpadding="3" border="0">
<tbody>
<tr>
<th valign="top"><strong>Method or Property</strong></th>
<th valign="top"><strong>Description</strong></th>
</tr>
<tr>
<td class="code" valign="top">Open($ArchFile, $UseIncludePath=false)</td>
<td valign="top"> Open an original Zip archive (it can be an
LibreOffice document, an MS Office document or any other Zip
archive).<br />
<span class="versioning">Versioning:<br />
- since TbsZip version 2.14, $ArchFile can be a PHP file handle<br />
- argument $UseIncludePath is supported since TbsZip version 2.12</span></td>
</tr>
<tr>
<td class="code" valign="top">CreateNew()</td>
<td valign="top"> 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.<br />
<span class="versioning">Versioning: method CreateNew() is supported
since TbsZip version 2.1 </span></td>
</tr>
<tr>
<td class="code" valign="top">FileExists($NameOrIdx)</td>
<td valign="top">Return <span class="value">true</span> if the file
exists in the original archive. <span class="value">$NameOrIdx</span>
must be the full name (including folder name inside the archive) or
the index of an existing file in the archive.</td>
</tr>
<tr>
<td class="code" valign="top">FileRead($NameOrIdx, $Uncompress=true)</td>
<td valign="top"> Return the contents of the file stored in the
original archive. If <span class="value">$Uncompress</span> is <span
class="value">true</span>, then TbsZip tryies to uncompressed the
contents if needed. If the file is compressed but TbsZip cannot
uncompress it then an error is raised. You can check if the result
is compressed using property <span class="value">LastReadComp</span>.</td>
</tr>
<tr>
<td class="code" valign="top">FileReplace($NameOrIdx, $Data,
$DataType=TBSZIP_STRING, $Compress=true)</td>
<td valign="top">
<p>Replace or delete an existing file in the archive. Set <span class="value">$Data</span>=<span
class="value">false</span> in order to delete the file. <span class="value">$DataType</span>
accepts <span class="value">TBSZIP_STRING</span> and <span class="value">TBSZIP_FILE</span>
(<span class="value">$Data</span> must then be the path of the
external file to insert). <span class="value">$Compress</span>
can be <span class="value">true</span>, <span class="value">false</span>
or an array with keys (<span class="value">'meth'</span>,<span class="value">'len_u'</span>,<span
class="value">'crc32'</span>) which means that the data is
already previously compressed. <em>Note that the original archive
is not modified, modifications will be provided as a new archive
when you call the method Flush().</em></p>
Returned values:
<table cellspacing="0" cellpadding="3" border="0">
<tbody>
<tr>
<td class="value">false</td>
<td>if the file has not been replaced or deleted.</td>
</tr>
<tr>
<td class="value">true</td>
<td>if the file has been successfully deleted.</td>
</tr>
<tr>
<td class="value">-1</td>
<td>if the file could not be compressed and has been stored
uncompressed</td>
</tr>
<tr>
<td class="value">0</td>
<td>if the file has been stored uncompressed as expected</td>
</tr>
<tr>
<td class="value">1</td>
<td>if the file has been stored compressed has expected</td>
</tr>
<tr>
<td class="value">2</td>
<td> if the file has been stored as is with pre-compression as
defined in the array <span class="value">$Compress</span></td>
</tr>
</tbody>
</table>
<p>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 <span class="value">TBSZIP_FILE</span>),
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 <span class="value">Flush()</span> is
called. Thus, you can add lot of files in an archive without
occupying the PHP memory.</p>
</td>
</tr>
<tr>
<td class="code" valign="top">FileAdd($Name, $Data,
$DataType=TBSZIP_STRING, $Compress=true)</td>
<td valign="top"> Add a new file in the archive, works like <span class="value">FileReplace()</span>.
<em>Note that the original archive is not modified, modifications
will be provided as a new archive when you call the method
Flush().</em><br />
If <span class="value">$Data</span> is <span class="value">false</span>
then the previously add file with the given name is canceled if any.</td>
</tr>
<tr>
<td class="code" valign="top">FileCancelModif($NameOrIdx)</td>
<td valign="top"> Cancel add, delete and replacements in the archive
for the given file name. Return the number of cancels.</td>
</tr>
<tr>
<td class="code" valign="top">FileGetState($NameOrIdx)</td>
<td valign="top">
<p>Return a string that represents the state of the file in the
archive:</p>
<table cellspacing="0" cellpadding="3" border="0">
<tbody>
<tr>
<td class="value">'u'</td>
<td>Unchanged</td>
</tr>
<tr>
<td class="value">'m'</td>
<td>Modified</td>
</tr>
<tr>
<td class="value">'d'</td>
<td>Deleted</td>
</tr>
<tr>
<td class="value">'a'</td>
<td>Added</td>
</tr>
<tr>
<td class="value">false</td>
<td>The file is not find in the archive </td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td class="code" valign="top">Flush($Render=TBSZIP_DOWNLOAD, $File='',
$ContentType='')</td>
<td valign="top">
<p>Actually create the new archive with all modifications. External
files to be inserted as sub-files are loaded during this proces
and not before. They are compressed and output on the fly and one
by one without staying in the PHP memory. No temporay files are
used.</p>
The <span class="value">$Render</span> option:
<table cellspacing="0" cellpadding="3" border="0">
<tbody>
<tr>
<td class="value" valign="top">TBSZIP_DOWNLOAD</td>
<td valign="top">will provide the new archive as a download
with HTTP headers. Use <span class="value">$File</span> to
customize the name of the downloaded file. Use <span class="value">$ContentType</span>
to customize the ContentType header.</td>
</tr>
<tr>
<td class="value" valign="top">TBSZIP_DOWNLOAD +<br />
TBSZIP_NOHEADER</td>
<td valign="top">will provide the new archive as a download
without HTTP</td>
</tr>
<tr>
<td class="value" valign="top">TBSZIP_FILE</td>
<td valign="top"> will provide the new archive as a physical
file on the server. Use <span class="value">$File</span> to
define the path of the physical file</td>
</tr>
<tr>
<td class="value" valign="top">TBSZIP_STRING</td>
<td valign="top">will make method <span class="value">Flush()</span>
to return the new archive as a binary string</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td class="code" valign="top">Debug()</td>
<td valign="top">Display information about the original archive.</td>
</tr>
<tr>
<td class="code" valign="top">Close()</td>
<td valign="top"> Close the opened original archive.</td>
</tr>
<tr>
<td class="code" valign="top">ArchFile</td>
<td valign="top">Full path of the opened original archive.</td>
</tr>
<tr>
<td class="code" valign="top">CdFileLst</td>
<td valign="top">The Central Directory meta data.<br />
That is an array listing all existing files in the original archive
with some technical information.<br />
Synopsis :<br />
<div class="value"> array( <br />
idx1 => array(<br />
'v_name' => '...', // name of the file<br />
'v_comm' => '...', // comment<br />
'date' => '...', // date<br />
'time' => '...', // time<br />
...,<br />
),<br />
idx2 => array(...),<br />
...<br />
)<br />
<br />
</div>
</td>
</tr>
<tr>
<td class="code" valign="top">CdFileByName</td>
<td valign="top">The Central Directory files, where keys are the file
names, and values are the file indexes.<br />
Synopsis :<br />
<div class="value"> array( <br />
'file_name_1.txt' => 1,<br />
'file_name_2.txt' => 2,<br />
'file_name_3.txt' => 3,<br />
...<br />
)<br />
<br />
</div>
</td>
</tr>
<tr>
<td class="code" valign="top">LastReadIdx</td>
<td valign="top">
<p>Index of the last file read by <span class="value">FileRead()</span>.<br />
false means the file was not found in the archive,</p>
</td>
</tr>
<tr>
<td class="code" valign="top">LastReadComp</td>
<td valign="top">Compression information about of the last file read
by <span class="value">FileRead()</span>.<br />
false means the file was not found in the archive,<br />
<span class="value">-1</span> means the file was compressed and has
been successfully uncompressed,<br />
<span class="value">0</span> means the file was not compressed,<br />
<span class="value">1</span> means the file was compressed but
TbsZip was unable to uncompress.</td>
</tr>
<tr>
<td class="code" valign="top">DisplayError</td>
<td valign="top">Default value is <span class="value">false</span>
until version 2.3, and <span class="value">true</span> since
version 2.4.<br />
If the value is true, TbsZip error messages are displayed (using
echo). <br />
In any case, the last TbsZip error message is saved into property <span
class="value">Error</span>.<br />
It can be interesting to not display error directly, for example
when you flush the new archive with the Download option, the error
message may be merged to the downloaded file.</td>
</tr>
<tr>
<td class="code" valign="top">Error</td>
<td valign="top">Last error message, or <span class="value">false</span>
if no TbsZip error. Use this property in order to check errors when
property <span class="value">DisplayError</span> is set to false.</td>
</tr>
</tbody>
</table>
<br />
<h2><a name="misc" id="intro5"></a>6. Contact and license</h2>
<p>Author: <a href="http://www.tinybutstrong.com/onlyyou.html">Skrol29</a></p>
<p>License: <a href="http://www.gnu.org/licenses/lgpl.html">LGLP</a></p>
</body>
</html>