Manual

Send HTTP Downloads

Intro

Intro – Introduction in usage of HTTP_Download

Introduction

HTTP_Download provides an interface to easily send any arbitrary data to HTTP clients. HTTP_Download can gain its data from variables, files or stream resources.

With this package you can easily handle (hidden) downloads. Hidden means not accessible by the public - for instance if you want to restrict access to particular downloads.

It supports HTTP compression, caching and partial downloads, resuming and sending raw data, for example from database BLOBs.

ATTENTION: You shouldn't use this package together with ob_gzhandler or zlib.output_compression enabled in your php.ini, especially if you want to send already gzipped data!

Usage Examples:

Have a look at the following examples:

Static send:

<?php
1  $params = array(
2   'file'                => '../hidden/download.tgz',
3   'contenttype'         => 'application/x-gzip',
4   'contentdisposition'  => array(HTTP_DOWNLOAD_ATTACHMENT, 'latest.tgz'),
5  );
6  
7  $error = HTTP_Download::staticSend($params, false);
?>

Send a hidden file:

<?php
1  $dl = &new HTTP_Download();
2  $dl->setFile('../hidden/download.tgz');
3  $dl->setContentDisposition(HTTP_DOWNLOAD_ATTACHMENT, 'latest.tgz');
4  // with ext/magic.mime
5  // $dl->guessContentType();
6  // else:
7  $dl->setContentType('application/x-gzip');
8  $dl->send();
?>

Send arbitrary data:

<?php
1  $dl = &new HTTP_Download();
2  $dl->setData($data);
3  $dl->setLastModified($unix_timestamp);
4  $dl->setContentType('application/x-gzip');
5  $dl->setContentDisposition(HTTP_DOWNLOAD_ATTACHMENT, 'latest.tgz');
6  $dl->send();
?>

Limiting bandwidth:

<?php
1  $dl = &new HTTP_Download();
2  $dl->setFile('huge_file.bin');
3  $dl->setBufferSize(25 * 1024); // 25 K
4  $dl->setThrottleDelay(1);   // 1 sec
5  $dl->send();
?>

Sending a PostgreSQL LOB:

<?php
1  require_once 'HTTP/Download.php';
2  require_once 'HTTP/Download/PgLOB.php';
3  $dl = &new HTTP_Download();
4  $dl->setResource(
5    HTTP_Download_PgLOB::open(pg_connect('dbname=lobs'), 12345));
6  $dl->send();
?>

HTTP_Download::HTTP_Download

HTTP_Download::HTTP_Download() – Constructor

Synopsis

require_once 'HTTP/Download.php';

object new HTTP_Download ( array $params = array() )

Description

Creates an instance of an HTTP_Download object and sets supplied parameters.

Parameter

array $params - An associative array of parameters:
- one of:
  - $params['file'] - filepath
  - $params['data'] - raw data
  - $params['resource'] - resource handle
- and any of:
  - $params['gzip'] - whether to gzip the download
  - $params['cache'] - whether to allow client side caching of the download
  - $params['lastmodified'] - unix timestamp of last modification
  - $params['contenttype'] - content type
  - $params['contentdisposition'] - content disposition
  - $params['buffersize'] - amount of bytes read at once from files or resources
  - $params['throttledelay'] - amount of seconds to sleep after each chunk that has been sent
  - $params['cachecontrol'] - cache privacy and validity

See

HTTP_Download::setParams

HTTP_Download::setParams() – Set various parameters

Synopsis

mixed HTTP_Download::setParams ( array $params )

Description

Set the parameters for the download.

You can use this method as an alternative to passing the parameters in the constructor or calling the setter of each parameter.

Parameter

array $params - An associative array of parameters:
- one of:
  - $params['file'] - filepath
  - $params['data'] - raw data
  - $params['resource'] - resource handle
- and any of:
  - $params['gzip'] - whether to gzip the download
  - $params['cache'] - whether to allow client side caching of the download
  - $params['lastmodified'] - unix timestamp of last modification
  - $params['contenttype'] - content type
  - $params['contentdisposition'] - content disposition
  - $params['buffersize'] - amount of bytes read at once from files or resources
  - $params['throttledelay'] - amount of seconds to sleep after each chunk that has been sent
  - $params['cachecontrol'] - cache privacy and validity

See

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::setFile

HTTP_Download::setFile() – Set file path

Synopsis

mixed HTTP_Download::setFile ( string $file , bool $send_404 = true )

Description

Set the path to the file for the download.

Parameter

string $file - file path
bool $send_404 = true - whether to send "HTTP 404 File Not Found", if file couldn't be found

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::setData

HTTP_Download::setData() – Set raw data

Synopsis

void HTTP_Download::setData ( mixed $data = null )

Description

Set $data to null if you want to unset.

Otherwise you can send any arbitrary data ie. from a database BLOB.

Parameter

mixed $data = null - any arbietrary data as string to send or null to unset

Note

This function can not be called statically.

HTTP_Download::setResource

HTTP_Download::setResource() – Set resource for download

Synopsis

mixed HTTP_Download::setResource ( mixed $handle = null )

Description

Set the resource handle to retrieve the data for the download.

The resource handle supplied will be closed after sending the download.

Set $handle to null if you want to unset.

This cannot be used with resources of databases that populate their BLOBs as resource handles like PostgreSQL. A possible solution would be to write a stream wrapper.

Returns a PEAR_Error if $handle is no valid resource or not null.

Parameter

mixed $handle = null - (int) resource handle or null

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::setGzip

HTTP_Download::setGzip() – Whether to gzip the download on the fly or not. (requires ext/zlib)

Synopsis

mixed HTTP_Download::setGzip ( bool $gzip = false )

Description

Define whether you want to send the download gzipped or not.

Returns a PEAR_Error if ext/zlib is not available.

Parameter

bool $gzip = false - whether to gzip the download on the fly

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::setCache

HTTP_Download::setCache() – Whether to allow caching of the download on the clients side.

Synopsis

void HTTP_Download::setCache ( bool $cache = true )

Description

Define whether you want to allow caching of the download on the clients side.

If set to true (default), HTTP_Download will emit some caching headers like Cache-Control, Last-Modified and ETag.

Parameter

bool $cache = true - whether to allow caching of the download

Note

This function can not be called statically.

HTTP_Download::setCacheControl

HTTP_Download::setCacheControl() – Control cache privacy and validity.

Synopsis

void HTTP_Download::setCacheControl ( string $cache = "public" , int $maxage = 0 )

Description

Define the contents of the Cache-Control header.

If set to set to "public", proxies are adviced to cache the response, if set to "private", proxies are adviced to do not.

The maxage paramter controls the amount of seconds an entity is suggested to be cached. Many user agents won't even send a request for subsequent requests to the same resource within the specified time frame.

Parameter

string $cache = "public" - whether to allow proxy caching
int $maxage = 0 - maximum age of the cached entity

Note

This function can not be called statically.

HTTP_Download::setBufferSize

HTTP_Download::setBufferSize() – Set size of buffer in bytes.

Synopsis

mixed HTTP_Download::setBufferSize ( int $size = 2097152 )

Description

The amount of bytes specified as buffer size is the maximum amount of data read at once from resources or files. The default size is 2M (2097152 bytes).

Be aware that if you enable gzip compression and you set a very low buffer size that the actual file size may grow due to added gzip headers for each sent chunk of the specified size.

Returns PEAR_Error (HTTP_DOWNLOAD_E_INVALID_PARAM) if $size is not greater than 0 bytes.

Parameter

int $size = 2097152 - amount of bytes to buffer

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::setThrottleDelay

HTTP_Download::setThrottleDelay() – Set throttle delay in seconds

Synopsis

void HTTP_Download::setThrottleDelay ( float $seconds = 0 )

Description

Set the amount of seconds to sleep after each chunck that has been sent. One can implement some sort of throttle through adjusting the buffer size and the throttle delay. With a setting of buffersize=25600 and throttledelay=1 HTTP_Download will sleep a second after each 25 K of data sent.

Just be aware that if gzip'ing is enabled, decreasing the chunk size too much leads to proportionally increased network traffic due to added gzip header and bottom bytes around each chunk.

Parameter

float $seconds = 0 - amount of seconds to sleep

Return value

Returns void.

Note

This function can not be called statically.

HTTP_Download::setContentType

HTTP_Download::setContentType() – Set content type

Synopsis

mixed HTTP_Download::setContentType ( string $content_type = 'application/x-octetstream' )

Description

Set a reasonable content type for the download.

Examples:

application/pdf
application/zip
text/css

Returns PEAR_Error if $content_type doesn't seem to be valid.

Parameter

string $content_type = 'application/x-octetstream' - a reasonable content type

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::setLastModified

HTTP_Download::setLastModified() – Set "Last-Modified"

Synopsis

void HTTP_Download::setLastModified ( int $last_modified )

Description

Set the time (unix timestamp) of last modification of the download.

This is usually determined by filemtime($file) in setFile().

Parameter

int $last_modified - unix timestamp of last modification time

Note

This function can not be called statically.

HTTP_Download::setContentDisposition

HTTP_Download::setContentDisposition() – Set content disposition

Synopsis

void HTTP_Download::setContentDisposition ( string $disposition = HTTP_DOWNLOAD_ATTACHMENT , string $file_name = null )

Description

Set content disposition of the download.

"Content-Disposition" is not HTTP compliant, but most browsers follow this header, so it was borrowed from MIME standard. It looks like this: "Content-Disposition: attachment; filename=example.tgz".

Parameter

string $disposition = HTTP_DOWNLOAD_ATTACHMENT - the disposition of the download (either 'attachment' or 'inline')
string $file_name = null - the file name the browser's download window should show

Note

This function can not be called statically.

HTTP_Download::guessContentType

HTTP_Download::guessContentType() – Guess content type of file

Synopsis

mixed HTTP_Download::guessContentType ( )

Description

Use only if you send a file.

First we try to use MIME_Type, if installed, to detect the content type, else we check if ext/mime_magic is loaded and properly configured.

Returns PEAR_Error if:

MIME_Type failed to detect a proper content type (HTTP_DOWNLOAD_E_INVALID_CONTENT_TYPE)
ext/magic.mime is not installed, or not properly configured (HTTP_DOWNLOAD_E_NO_EXT_MMAGIC)
mime_content_type() couldn't guess content type or returned a content type considered to be bogus by setContentType() (HTTP_DOWNLOAD_E_INVALID_CONTENT_TYPE)

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::send

HTTP_Download::send() – Send file

Synopsis

mixed HTTP_Download::send ( bool $autoSetContentDisposition = true )

Description

Send the download.

Returns PEAR_Error if:

HTTP headers were already sent
HTTP Range was invalid

Parameter

bool $autoSetContentDisposition = true - automatically sets the Content-Disposition to HTTP_DOWNLOAD_ATTACHMENT header if not already set

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

HTTP_Download::staticSend

HTTP_Download::staticSend() – Static send

Synopsis

mixed HTTP_Download::staticSend ( array $params , bool $guess = false )

Description

Send a download statically without instantiating an HTTP_Download object.

Parameter

array $params - An associative array of parameters:
- one of:
  - $params['file'] - filepath
  - $params['data'] - raw data
  - $params['resource'] - resource handle
- and any of:
  - $params['gzip'] - whether to gzip the download
  - $params['cache'] - whether to allow client side caching of the download
  - $params['lastmodified'] - unix timestamp of last modification
  - $params['contenttype'] - content type
  - $params['contentdisposition'] - content disposition
  - $params['buffersize'] - amount of bytes read at once from files or resources
  - $params['throttledelay'] - amount of seconds to sleep after each chunk that has been sent
bool $guess = false - whether to call guessContentType()

See

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function should be called statically.

HTTP_Download::sendArchive

HTTP_Download::sendArchive() – Send an archive created on the fly

Synopsis

mixed HTTP_Download::sendArchive ( string $name , mixed $files , string $type = HTTP_DOWNLOAD_TGZ , string $add_path = '' , string $strip_path = '' )

Description

Send an archive created on the fly by Archive_Tar or Archive_Zip.

The parameter $files can be an array of files/directories or a space separated string of files/directories which should be packed to an archive.

The parameter $type can be one of HTTP_DOWNLOAD_TAR, HTTP_DOWNLOAD_TGZ, HTTP_DOWNLOAD_BZ2 and HTTP_DOWNLOAD_ZIP.

The usage of this method is deprecated. Use HTTP_Download_Archive::send() instead.

Parameter

string $name - the name the archive should have
mixed $files - list of files/directories
string $type = - the format of the archive (TAR, TGZ, BZ2 or ZIP)
string $add_path = '' - path that should be prepended to the files
string $strip_path = '' - path that should be stripped from the files

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function should be called statically.