\Pluf\HTTPDownload2

Send HTTP Downloads/Responses.

With this package you can handle (hidden) downloads. It supports partial downloads, resuming and sending raw data ie. 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!

Summary

Methods
Properties
Constants
__construct()
setParams()
setFile()
setData()
setResource()
setGzip()
setCache()
setCacheControl()
setETag()
setBufferSize()
setThrottleDelay()
setLastModified()
setContentDisposition()
setContentType()
guessContentType()
send()
staticSend()
sendArchive()
generateETag()
sendChunks()
sendChunk()
getChunks()
sortChunks()
mergeChunks()
isRangeRequest()
getRanges()
isCached()
isValidRange()
compareAsterisk()
sendHeaders()
flush()
sleep()
$file
$data
$handle
$gzip
$cache
$size
$lastModified
$headers
$HTTP
$etag
$bufferSize
$throttleDelay
$sentBytes
$_error
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Properties

$file

$file : string

Path to file for download

Type

string

$data

$data : string

Data for download

Type

string

$handle

$handle : integer

Resource handle for download

Type

integer

$gzip

$gzip : boolean

Whether to gzip the download

Type

boolean

$cache

$cache : boolean

Whether to allow caching of the download on the clients side

Type

boolean

$size

$size : integer

Size of download

Type

integer

$lastModified

$lastModified : integer

Last modified

Type

integer

$headers

$headers : array

HTTP headers

Type

array

$HTTP

$HTTP : object

HTTP_Header

Type

object

$etag

$etag : string

ETag

Type

string

$bufferSize

$bufferSize : integer

Buffer Size

Type

integer

$throttleDelay

$throttleDelay : float

Throttle Delay

Type

float

$sentBytes

$sentBytes : integer

Sent Bytes

Type

integer

$_error

$_error : \PEAR_Error

Startup error

Type

\PEAR_Error

Methods

__construct()

__construct(array  $params = array()) 

Constructor

Set supplied parameters.

Parameters

array $params

associative array of parameters one of:

  • 'file' => path to file for download
  • 'data' => raw data for download
  • 'resource' => resource handle for download

and any of:

  • 'cache' => whether to allow cs caching
  • 'gzip' => whether to gzip the download
  • 'lastmodified' => unix timestamp
  • 'contenttype' => content type of download
  • 'contentdisposition' => content disposition
  • 'buffersize' => amount of bytes to buffer
  • 'throttledelay' => amount of secs to sleep
  • 'cachecontrol' => cache privacy and validity

'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".

setParams()

setParams(array  $params) : mixed

Set parameters

Set supplied parameters through its accessor methods.

Parameters

array $params

associative array of parameters

Returns

mixed —

Returns true on success or PEAR_Error on failure.

setFile()

setFile(string  $file, boolean  $send_error = true) : mixed

Set path to file for download

The Last-Modified header will be set to files filemtime(), actually. Returns PEAR_Error (HTTP_DOWNLOAD2_E_INVALID_FILE) if file doesn't exist. Sends HTTP 404 or 403 status if $send_error is set to true.

Parameters

string $file

path to file for download

boolean $send_error

whether to send HTTP/404 or 403 if the file wasn't found or is not readable

Returns

mixed —

Returns true on success or PEAR_Error on failure.

setData()

setData(string  $data = null) : void

Set data for download

Set $data to null if you want to unset this.

Parameters

string $data

raw data to send

setResource()

setResource(integer  $handle = null) : mixed

Set resource for download

The resource handle supplied will be closed after sending the download. Returns a PEAR_Error (HTTP_DOWNLOAD2_E_INVALID_RESOURCE) if $handle is no valid resource. Set $handle to null if you want to unset this.

Parameters

integer $handle

resource handle

Returns

mixed —

Returns true on success or PEAR_Error on failure.

setGzip()

setGzip(boolean  $gzip = false) : mixed

Whether to gzip the download

Returns a PEAR_Error (HTTP_DOWNLOAD2_E_NO_EXT_ZLIB) if ext/zlib is not available/loadable.

Parameters

boolean $gzip

whether to gzip the download

Returns

mixed —

Returns true on success or PEAR_Error on failure.

setCache()

setCache(boolean  $cache = true) : void

Whether to allow caching

If set to true (default) we'll send some headers that are commonly used for caching purposes like ETag, Cache-Control and Last-Modified.

If caching is disabled, we'll send the download no matter if it would actually be cached at the client side.

Parameters

boolean $cache

whether to allow caching

setCacheControl()

setCacheControl(string  $cache = 'public', integer  $maxage) : boolean

Whether to allow proxies to cache

If set to 'private' proxies shouldn't cache the response. This setting defaults to 'public' and affects only cached responses.

Parameters

string $cache

private or public

integer $maxage

maximum age of the client cache entry

Returns

boolean

setETag()

setETag(string  $etag = null) : void

Set ETag

Sets a user-defined ETag for cache-validation. The ETag is usually generated by Download2 through its payload information.

Parameters

string $etag

Entity tag used for strong cache validation.

setBufferSize()

setBufferSize(integer  $bytes = 2097152) : mixed

Set Size of Buffer

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_DOWNLOAD2_E_INVALID_PARAM) if $size is not greater than 0 bytes.

Parameters

integer $bytes

Amount of bytes to use as buffer.

Returns

mixed —

Returns true on success or PEAR_Error on failure.

setThrottleDelay()

setThrottleDelay(float  $seconds) : void

Set Throttle Delay

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 the following settings Download2 will sleep a second after each 25 K of data sent.

Array( 'throttledelay' => 1, 'buffersize' => 1024 * 25, )

Just be aware that if gzipp'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.

Parameters

float $seconds

Amount of seconds to sleep after each chunk that has been sent.

setLastModified()

setLastModified(integer  $last_modified) : void

Set "Last-Modified"

This is usually determined by filemtime() in Download2::setFile() If you set raw data for download with Download2::setData() and you want do send an appropiate "Last-Modified" header, you should call this method.

Parameters

integer $last_modified

unix timestamp

setContentDisposition()

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

Set Content-Disposition header

Example: $Download2->setContentDisposition( HTTP_DOWNLOAD2_ATTACHMENT, 'download.tgz' );

Parameters

string $disposition

whether to send the download inline or as attachment

string $file_name

the filename to display in the browser's download window

setContentType()

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

Set content type of the download

Default content type of the download will be 'application/x-octetstream'. Returns PEAR_Error (HTTP_DOWNLOAD2_E_INVALID_CONTENT_TYPE) if $content_type doesn't seem to be valid.

Parameters

string $content_type

content type of file for download

Returns

mixed —

Returns true on success or PEAR_Error on failure.

guessContentType()

guessContentType() : mixed

Guess content type of file

First we try to use PEAR::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: o if PEAR::MIME_Type failed to detect a proper content type (HTTP_DOWNLOAD2_E_INVALID_CONTENT_TYPE) o ext/magic.mime is not installed, or not properly configured (HTTP_DOWNLOAD2_E_NO_EXT_MMAGIC) o mime_content_type() couldn't guess content type or returned a content type considered to be bogus by setContentType() (HTTP_DOWNLOAD2_E_INVALID_CONTENT_TYPE)

Returns

mixed —

Returns true on success or PEAR_Error on failure.

send()

send(boolean  $autoSetContentDisposition = true) : mixed

Send

Returns PEAR_Error if: o HTTP headers were already sent (HTTP_DOWNLOAD2_E_HEADERS_SENT) o HTTP Range was invalid (HTTP_DOWNLOAD2_E_INVALID_REQUEST)

Parameters

boolean $autoSetContentDisposition

Whether to set the Content-Disposition header if it isn't already.

Returns

mixed —

Returns true on success or PEAR_Error on failure.

staticSend()

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

Static send

Parameters

array $params

associative array of parameters

boolean $guess

whether Download2::guessContentType() should be called

Returns

mixed —

Returns true on success or PEAR_Error on failure.

sendArchive()

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

Send a bunch of files or directories as an archive

Example: require_once 'HTTP/Download2.php'; Download2::sendArchive( 'myArchive.tgz', '/var/ftp/pub/mike', HTTP_DOWNLOAD2_TGZ, '', '/var/ftp/pub' );

Parameters

string $name

name the sent archive should have

mixed $files

files/directories

string $type

archive type

string $add_path

path that should be prepended to the files

string $strip_path

path that should be stripped from the files

Returns

mixed —

Returns true on success or PEAR_Error on failure.

generateETag()

generateETag() : string

Generate ETag

Returns

string

sendChunks()

sendChunks(array  $chunks) : mixed

Send multiple chunks

Parameters

array $chunks

Chunks to send

Returns

mixed —

Returns true on success or PEAR_Error on failure.

sendChunk()

sendChunk(array  $chunk, string  $cType = null, string  $bound = null) : mixed

Send chunk of data

Parameters

array $chunk

start and end offset of the chunk to send

string $cType

actual content type

string $bound

boundary for multipart/byteranges

Returns

mixed —

Returns true on success or PEAR_Error on failure.

getChunks()

getChunks() : array

Get chunks to send

Returns

array —

Chunk list or PEAR_Error on invalid range request

sortChunks()

sortChunks(  $chunks) : void

Sorts the ranges to be in ascending order

Parameters

$chunks

mergeChunks()

mergeChunks(array  $chunks) : array

Merges consecutive chunks to avoid overlaps

Parameters

array $chunks

Ranges to merge

Returns

array —

merged ranges

isRangeRequest()

isRangeRequest() : boolean

Check if range is requested

Returns

boolean

getRanges()

getRanges() : array

Get range request

Returns

array

isCached()

isCached() : boolean

Check if entity is cached

Returns

boolean

isValidRange()

isValidRange() : boolean

Check if entity hasn't changed

Returns

boolean

compareAsterisk()

compareAsterisk(string  $svar, string  $compare) : boolean

Compare against an asterisk or check for equality

Parameters

string $svar

key for the $_SERVER array

string $compare

string to compare

Returns

boolean

sendHeaders()

sendHeaders() : void

Send HTTP headers

flush()

flush(string  $data = '') : void

Flush

Parameters

string $data

Data

sleep()

sleep() : void

Sleep