Documentation

ZipStream
in package

ZipStream

Streamed, dynamically generated zip archives.

Tags
author

Paul Duncan pabs@pablotron.org

author

Jonatan Männchen jonatan@maennchen.ch

author

Jesse Donat donatj@gmail.com

copyright

Copyright (C) 2007-2009 Paul Duncan pabs@pablotron.org

copyright

Copyright (C) 2014 Jonatan Männchen jonatan@maennchen.ch

copyright

Copyright (C) 2014 Jesse Donat donatj@gmail.com

license

https://raw.githubusercontent.com/maennchen/ZipStream-PHP/master/LICENCE

Requirements:

  • PHP version 5.1.2 or newer.

Usage:

Streaming zip archives is a simple, three-step process:

  1. Create the zip stream:

    $zip = new ZipStream('example.zip');

  2. Add one or more files to the archive:

    • add first file $data = file_get_contents('some_file.gif'); $zip->addFile('some_file.gif', $data);

    • add second file $data = file_get_contents('some_file.gif'); $zip->addFile('another_file.png', $data);

  3. Finish the zip stream:

    $zip->finish();

You can also add an archive comment, add comments to individual files, and adjust the timestamp of files. See the API documentation for each method below for additional information.

Example:

// create a new zip stream object $zip = new ZipStream('some_files.zip');

// list of local files $files = array('foo.txt', 'bar.jpg');

// read and add each file to the archive foreach ($files as $path) $zip->addFile($path, file_get_contents($path));

// write archive footer to stream $zip->finish();

Table of Contents

COMPRESS  = 0x8
METHOD_DEFLATE  = 'deflate'
METHOD_STORE  = 'store'
NOCOMPRESS  = 0x0
OPTION_CONTENT_DISPOSITION  = 'content_disposition'
OPTION_CONTENT_TYPE  = 'content_type'
OPTION_HTTP_HEADER_CALLBACK  = 'http_header_callback'
OPTION_LARGE_FILE_METHOD  = 'large_file_method'
OPTION_LARGE_FILE_SIZE  = 'large_file_size'
OPTION_OUTPUT_STREAM  = 'output_stream'
OPTION_SEND_HTTP_HEADERS  = 'send_http_headers'
VERSION  = '0.3.0'
$cdr_ofs  : int
$files  : array<string|int, mixed>
$ofs  : int
$opt  : array<string|int, mixed>
Global Options
$need_headers  : bool
$output_name  : null|string
__construct()  : mixed
Create a new ZipStream object.
addFile()  : mixed
addFile
addFileFromPath()  : void
addFileFromPath
addFileFromStream()  : void
addFile_from_stream
finish()  : void
finish
addCdr()  : void
Add CDR (Central Directory Record) footer.
addCdrEof()  : void
Send CDR EOF (Central Directory Record End-of-File) record.
addCdrFile()  : void
Send CDR record for specified file.
addDataDescriptorHeader()  : int
addFileHeader()  : int
Create and send zip header for this file.
addLargeFile()  : void
Add a large file from the given path.
clear()  : void
Clear all internal variables. Note that the stream object is not usable after this.
dostime()  : int
Convert a UNIX timestamp to a DOS timestamp.
getStorageConstant()  : mixed
isLargeFile()  : bool
Is this file larger than large_file_size?
packFields()  : string
Create a format string and argument list for pack(), then call pack() and return the result.
send()  : void
Send string, sending HTTP headers if necessary.
sendHttpHeaders()  : void
Send HTTP headers for this stream.
addToCdr()  : int
Save file attributes for trailing CDR record.

Constants

METHOD_DEFLATE

public mixed METHOD_DEFLATE = 'deflate'

METHOD_STORE

public mixed METHOD_STORE = 'store'

OPTION_CONTENT_DISPOSITION

public mixed OPTION_CONTENT_DISPOSITION = 'content_disposition'

OPTION_CONTENT_TYPE

public mixed OPTION_CONTENT_TYPE = 'content_type'

OPTION_HTTP_HEADER_CALLBACK

public mixed OPTION_HTTP_HEADER_CALLBACK = 'http_header_callback'

OPTION_LARGE_FILE_METHOD

public mixed OPTION_LARGE_FILE_METHOD = 'large_file_method'

OPTION_LARGE_FILE_SIZE

public mixed OPTION_LARGE_FILE_SIZE = 'large_file_size'

OPTION_OUTPUT_STREAM

public mixed OPTION_OUTPUT_STREAM = 'output_stream'

OPTION_SEND_HTTP_HEADERS

public mixed OPTION_SEND_HTTP_HEADERS = 'send_http_headers'

VERSION

public mixed VERSION = '0.3.0'
Tags
deprecated

deprecated since version 0.3.0, use composer version

Properties

$files

public array<string|int, mixed> $files = array()

$opt

Global Options

public array<string|int, mixed> $opt = array()

$output_name

protected null|string $output_name

Methods

__construct()

Create a new ZipStream object.

public __construct([string $name = null ][, array<string|int, mixed> $opt = array() ]) : mixed

Parameters:

Parameters
$name : string = null
  • Name of output file (optional).
$opt : array<string|int, mixed> = array()
  • Hash of archive options (optional, see "Archive Options" below).

Archive Options:

comment - Comment for this archive. content_type - HTTP Content-Type. Defaults to 'application/x-zip'. content_disposition - HTTP Content-Disposition. Defaults to 'attachment; filename="FILENAME"', where FILENAME is the specified filename. large_file_size - Size, in bytes, of the largest file to try and load into memory (used by addFileFromPath()). Large files may also be compressed differently; see the 'large_file_method' option. large_file_method - How to handle large files. Legal values are 'store' (the default), or 'deflate'. Store sends the file raw and is significantly faster, while 'deflate' compresses the file and is much, much slower. Note that deflate must compress the file twice and extremely slow. sendHttpHeaders - Boolean indicating whether or not to send the HTTP headers for this file.

Note that content_type and content_disposition do nothing if you are not sending HTTP headers.

Large File Support:

By default, the method addFileFromPath() will send send files larger than 20 megabytes along raw rather than attempting to compress them. You can change both the maximum size and the compression behavior using the large_file_* options above, with the following caveats:

  • For "small" files (e.g. files smaller than large_file_size), the memory use can be up to twice that of the actual file. In other words, adding a 10 megabyte file to the archive could potentially occupty 20 megabytes of memory.

  • Enabling compression on large files (e.g. files larger than large_file_size) is extremely slow, because ZipStream has to pass over the large file once to calculate header information, and then again to compress and send the actual data.

Examples:

// create a new zip file named 'foo.zip' $zip = new ZipStream('foo.zip');

// create a new zip file named 'bar.zip' with a comment $zip = new ZipStream('bar.zip', array( 'comment' => 'this is a comment for the zip file.', ));

Notes:

If you do not set a filename, then this library DOES NOT send HTTP headers by default. This behavior is to allow software to send its own headers (including the filename), and still use this library.

Return values
mixed —

addFile()

addFile

public addFile(string $name, string $data[, array<string|int, mixed> $opt = array() ][, string $storage_method = 'deflate' ]) : mixed

add a file to the archive

Parameters
$name : string
  • path of file in archive (including directory).
$data : string
  • contents of file
$opt : array<string|int, mixed> = array()
  • Hash of options for file (optional, see "File Options" below).

File Options: time - Last-modified timestamp (seconds since the epoch) of this file. Defaults to the current time. comment - Comment related to this file.

Examples:

// add a file named 'foo.txt' $data = file_get_contents('foo.txt'); $zip->addFile('foo.txt', $data);

// add a file named 'bar.jpg' with a comment and a last-modified // time of two hours ago $data = file_get_contents('bar.jpg'); $zip->addFile('bar.jpg', $data, array( 'time' => time() - 2 * 3600, 'comment' => 'this is a comment about bar.jpg', ));

$storage_method : string = 'deflate'
  • storage method for file, could be "store" or "deflate"
Return values
mixed —

addFileFromPath()

addFileFromPath

public addFileFromPath(string $name, string $path[, array<string|int, mixed> $opt = array() ][, string $storage_method = "deflate" ]) : void

add a file at path to the archive.

Note that large files may be compresed differently than smaller files; see the "Large File Support" section above for more information.

Parameters
$name : string
  • name of file in archive (including directory path).
$path : string
  • path to file on disk (note: paths should be encoded using UNIX-style forward slashes -- e.g '/path/to/some/file').
$opt : array<string|int, mixed> = array()
  • Hash of options for file (optional, see "File Options" below).

File Options: time - Last-modified timestamp (seconds since the epoch) of this file. Defaults to the current time. comment - Comment related to this file.

Examples:

// add a file named 'foo.txt' from the local file '/tmp/foo.txt' $zip->addFileFromPath('foo.txt', '/tmp/foo.txt');

// add a file named 'bigfile.rar' from the local file // '/usr/share/bigfile.rar' with a comment and a last-modified // time of two hours ago $path = '/usr/share/bigfile.rar'; $zip->addFileFromPath('bigfile.rar', $path, array( 'time' => time() - 2 * 3600, 'comment' => 'this is a comment about bar.jpg', ));

$storage_method : string = "deflate"
  • storage method for the file: either 'deflate' or 'store'
Tags
throws
FileNotFoundException
throws
FileNotReadableException
Return values
void —

addFileFromStream()

addFile_from_stream

public addFileFromStream(string $name, resource $stream[, array<string|int, mixed> $opt = array() ][, mixed $storage_method = self::METHOD_DEFLATE ]) : void

dds an open stream to the archive uncompressed

Parameters
$name : string
  • path of file in archive (including directory).
$stream : resource
  • contents of file as a stream resource
$opt : array<string|int, mixed> = array()
  • Hash of options for file (optional, see "File Options" below).

File Options: time - Last-modified timestamp (seconds since the epoch) of this file. Defaults to the current time. comment - Comment related to this file.

Examples:

// create a temporary file stream and write text to it $fp = tmpfile(); fwrite($fp, 'The quick brown fox jumped over the lazy dog.');

// add a file named 'streamfile.txt' from the content of the stream $x->addFile_from_stream('streamfile.txt', $fp);

$storage_method : mixed = self::METHOD_DEFLATE
Return values
void —

finish()

finish

public finish() : void

Write zip footer to stream.

Example:

// add a list of files to the archive $files = array('foo.txt', 'bar.jpg'); foreach ($files as $path) $zip->addFile($path, file_get_contents($path));

// write footer to stream $zip->finish();

Return values
void —

addCdr()

Add CDR (Central Directory Record) footer.

protected addCdr([array<string|int, mixed> $opt = null ]) : void
Parameters
$opt : array<string|int, mixed> = null
Return values
void —

addCdrEof()

Send CDR EOF (Central Directory Record End-of-File) record.

protected addCdrEof([array<string|int, mixed> $opt = null ]) : void
Parameters
$opt : array<string|int, mixed> = null
Return values
void —

addCdrFile()

Send CDR record for specified file.

protected addCdrFile(array<string|int, mixed> $args) : void
Parameters
$args : array<string|int, mixed>
Return values
void —

addDataDescriptorHeader()

protected addDataDescriptorHeader(int $len, int $zlen, string $crc) : int
Parameters
$len : int
$zlen : int
$crc : string
Return values
int —

$num_bytes_written. Num bytes written to zip stream output.

addFileHeader()

Create and send zip header for this file.

protected addFileHeader(string $name, array<string|int, mixed> &$opt, int $meth, string $crc, int $zlen, int $len[, Hex $genb = 0x0 ]) : int
Parameters
$name : string
$opt : array<string|int, mixed>
$meth : int
$crc : string
$zlen : int
$len : int
$genb : Hex = 0x0
Return values
int —

$num_bytes_written

addLargeFile()

Add a large file from the given path.

protected addLargeFile(string $name, string $path[, array<string|int, mixed> $opt = array() ]) : void
Parameters
$name : string
$path : string
$opt : array<string|int, mixed> = array()
Tags
throws
InvalidOptionException
Return values
void —

clear()

Clear all internal variables. Note that the stream object is not usable after this.

protected clear() : void
Return values
void —

dostime()

Convert a UNIX timestamp to a DOS timestamp.

protected final dostime(int $when) : int
Parameters
$when : int
Return values
int —

DOS Timestamp

getStorageConstant()

protected getStorageConstant(mixed $storage_method) : mixed
Parameters
$storage_method : mixed
Return values
mixed —

isLargeFile()

Is this file larger than large_file_size?

protected isLargeFile(string $path) : bool
Parameters
$path : string
Return values
bool —

packFields()

Create a format string and argument list for pack(), then call pack() and return the result.

protected packFields(array<string|int, mixed> $fields) : string
Parameters
$fields : array<string|int, mixed>
Return values
string —

send()

Send string, sending HTTP headers if necessary.

protected send(string $str) : void
Parameters
$str : string
Return values
void —

sendHttpHeaders()

Send HTTP headers for this stream.

protected sendHttpHeaders() : void
Return values
void —

addToCdr()

Save file attributes for trailing CDR record.

private addToCdr(string $name, array<string|int, mixed> $opt, int $meth, string $crc, int $zlen, int $len, int $rec_len[, Hex $genb = 0x0 ]) : int
Parameters
$name : string
$opt : array<string|int, mixed>
$meth : int
$crc : string
$zlen : int
$len : int
$rec_len : int
$genb : Hex = 0x0
Return values
int —

$num_bytes_written

Search results