A class for reading ZIP file directories, for the purposes of upload verification. More...

Static Public Member Functions
static	read ( $fileName, $callback, $options=[])
	Read a ZIP file and call a function for each file discovered in it.

Protected Member Functions
	__construct ( $fileName, $callback, $options)

Protected Attributes
	$buffer
	A segmented cache of the file contents.

	$callback
	The file data callback.

	$data

	$eocdr
	Stored headers.

	$eocdr64

	$eocdr64Locator

	$file
	The opened file resource.

	$fileLength
	The cached length of the file, or null if it has not been loaded yet.

	$fileName
	The file name.

	$zip64 = false
	The ZIP64 mode.

Private Member Functions
	error ( $code, $debugMessage)
	Throw an error, and log a debug message.

	execute ()
	Read the directory according to settings in $this.

	findOldCentralDirectory ()
	Find the location of the central directory, as would be seen by a non-ZIP64 reader.

	findZip64CentralDirectory ()
	Find the location of the central directory, as would be seen by a ZIP64-compliant reader.

	getBlock ( $start, $length=null)
	Get the file contents from a given offset.

	getFileLength ()
	Get the length of the file.

	getSegment ( $segIndex)
	Get a section of the file starting at position $segIndex * self::SEGSIZE, of length self::SEGSIZE.

	getStructSize ( $struct)
	Get the size of a structure in bytes.

	readCentralDirectory ( $offset, $size)
	Read the central directory at the given location.

	readEndOfCentralDirectoryRecord ()
	Read the header which is at the end of the central directory, unimaginatively called the "end of central directory record" by the ZIP spec.

	readZip64EndOfCentralDirectoryLocator ()
	Read the header called the "ZIP64 end of central directory locator".

	readZip64EndOfCentralDirectoryRecord ()
	Read the header called the "ZIP64 end of central directory record".

	testBit ( $value, $bitIndex)
	Returns a bit from a given position in an integer value, converted to boolean.

	unpack ( $string, $struct, $offset=0)
	Unpack a binary structure.

	unpackZip64Extra ( $extraField)
	Interpret ZIP64 "extra field" data and return an associative array.

Private Attributes
const	GENERAL_CD_ENCRYPTED = 13
	The index of the "general field" bit for central directory encryption.

const	GENERAL_UTF8 = 11
	The index of the "general field" bit for UTF-8 file names.

const	SEGSIZE = 16384
	The segment size for the file contents cache.

const	ZIP64_EXTRA_HEADER = 0x0001
	The "extra field" ID for ZIP64 central directory entries.

Detailed Description

A class for reading ZIP file directories, for the purposes of upload verification.

Only a functional interface is provided: ZipFileReader::read(). No access is given to object instances.

Definition at line 30 of file ZipDirectoryReader.php.

Constructor & Destructor Documentation

◆ __construct()

ZipDirectoryReader::__construct	(	$fileName,
		$callback,
		$options
	)

protected

Parameters

string	$fileName
callable	$callback
array	$options

Definition at line 134 of file ZipDirectoryReader.php.

References $callback, and $fileName.

Member Function Documentation

◆ error()

ZipDirectoryReader::error	(	$code,
		$debugMessage
	)

private

Throw an error, and log a debug message.

Parameters

mixed	$code
string	$debugMessage

Exceptions

ZipDirectoryReaderError

Definition at line 189 of file ZipDirectoryReader.php.

References wfDebug().

Referenced by execute(), findOldCentralDirectory(), findZip64CentralDirectory(), getBlock(), getSegment(), readCentralDirectory(), readEndOfCentralDirectoryRecord(), readZip64EndOfCentralDirectoryLocator(), readZip64EndOfCentralDirectoryRecord(), and unpack().

◆ execute()

ZipDirectoryReader::execute ( )

private

Read the directory according to settings in $this.

Returns: Status

Definition at line 148 of file ZipDirectoryReader.php.

References error(), findOldCentralDirectory(), findZip64CentralDirectory(), ZipDirectoryReaderError\getErrorCode(), readCentralDirectory(), and readEndOfCentralDirectoryRecord().

◆ findOldCentralDirectory()

ZipDirectoryReader::findOldCentralDirectory ( )

private

Find the location of the central directory, as would be seen by a non-ZIP64 reader.

Returns: array List containing offset, size and end position.

Definition at line 314 of file ZipDirectoryReader.php.

References error().

Referenced by execute().

◆ findZip64CentralDirectory()

ZipDirectoryReader::findZip64CentralDirectory ( )

private

Find the location of the central directory, as would be seen by a ZIP64-compliant reader.

Returns: array List containing offset, size and end position.

Definition at line 335 of file ZipDirectoryReader.php.

References error(), readZip64EndOfCentralDirectoryLocator(), and readZip64EndOfCentralDirectoryRecord().

Referenced by execute().

◆ getBlock()

ZipDirectoryReader::getBlock	(	$start,
		$length = `null`
	)

private

Get the file contents from a given offset.

If there are not enough bytes in the file to satisfy the request, an exception will be thrown.

Parameters

int	$start	The byte offset of the start of the block.
int \| null	$length	The number of bytes to return. If omitted, the remainder of the file will be returned.

Returns: string

Definition at line 520 of file ZipDirectoryReader.php.

References $fileLength, error(), getFileLength(), and getSegment().

Referenced by readCentralDirectory(), readEndOfCentralDirectoryRecord(), readZip64EndOfCentralDirectoryLocator(), and readZip64EndOfCentralDirectoryRecord().

◆ getFileLength()

ZipDirectoryReader::getFileLength ( )

private

Get the length of the file.

Returns: int

Definition at line 501 of file ZipDirectoryReader.php.

References $fileLength.

Referenced by getBlock(), getSegment(), readEndOfCentralDirectoryRecord(), and readZip64EndOfCentralDirectoryLocator().

◆ getSegment()

ZipDirectoryReader::getSegment ( $segIndex )

private

Get a section of the file starting at position $segIndex * self::SEGSIZE, of length self::SEGSIZE.

The result is cached. This is a helper function for getBlock().

If there are not enough bytes in the file to satisfy the request, the return value will be truncated. If a request is made for a segment beyond the end of the file, an empty string will be returned.

Parameters

int $segIndex

Returns: string

Definition at line 566 of file ZipDirectoryReader.php.

References error(), getFileLength(), and SEGSIZE.

Referenced by getBlock().

◆ getStructSize()

ZipDirectoryReader::getStructSize ( $struct )

private

Get the size of a structure in bytes.

See unpack() for the format of $struct.

Parameters

array $struct

Returns: int

Definition at line 592 of file ZipDirectoryReader.php.

References $type.

Referenced by readCentralDirectory(), readEndOfCentralDirectoryRecord(), readZip64EndOfCentralDirectoryLocator(), readZip64EndOfCentralDirectoryRecord(), unpack(), and unpackZip64Extra().

◆ read()

static ZipDirectoryReader::read	(	$fileName,
		$callback,
		$options = `[]`
	)

static

Read a ZIP file and call a function for each file discovered in it.

Because this class is aimed at verification, an error is raised on suspicious or ambiguous input, instead of emulating some standard behavior.

Parameters

string	$fileName	The archive file name
array	$callback	The callback function. It will be called for each file with a single associative array each time, with members:

name: The file name. Directories conventionally have a trailing slash.
mtime: The file modification time, in MediaWiki 14-char format
size: The uncompressed file size

Parameters

array $options An associative array of read options, with the option name in the key. This may currently contain:

zip64: If this is set to true, then we will emulate a library with ZIP64 support, like OpenJDK 7. If it is set to false, then we will emulate a library with no knowledge of ZIP64.

NOTE: The ZIP64 code is untested and probably doesn't work. It turned out to be easier to just reject ZIP64 archive uploads, since they are likely to be very rare. Confirming safety of a ZIP64 file is fairly complex. What do you do with a file that is ambiguous and broken when read with a non-ZIP64 reader, but valid when read with a ZIP64 reader? This situation is normal for a valid ZIP64 file, and working out what non-ZIP64 readers will make of such a file is not trivial.

Returns

Status A Status object. The following fatal errors are defined:

 - zip-file-open-error: The file could not be opened.

 - zip-wrong-format: The file does not appear to be a ZIP file.

 - zip-bad: There was something wrong or ambiguous about the file
   data.

 - zip-unsupported: The ZIP file uses features which
   ZipDirectoryReader does not support.

The default messages for those fatal errors are written in a way that makes sense for upload verification.

If a fatal error is returned, more information about the error will be available in the debug log.

Note that the callback function may be called any number of times before a fatal error is returned. If this occurs, the data sent to the callback function should be discarded.

Definition at line 88 of file ZipDirectoryReader.php.

References $callback, and $fileName.

Referenced by UploadBase\verifyPartialFile().

◆ readCentralDirectory()

ZipDirectoryReader::readCentralDirectory	(	$offset,
		$size
	)

private

Read the central directory at the given location.

Parameters

int	$offset
int	$size

Definition at line 373 of file ZipDirectoryReader.php.

References $data, error(), getBlock(), getStructSize(), testBit(), unpack(), and unpackZip64Extra().

Referenced by execute().

◆ readEndOfCentralDirectoryRecord()

ZipDirectoryReader::readEndOfCentralDirectoryRecord ( )

private

Read the header which is at the end of the central directory, unimaginatively called the "end of central directory record" by the ZIP spec.

Definition at line 199 of file ZipDirectoryReader.php.

References error(), getBlock(), getFileLength(), getStructSize(), and unpack().

Referenced by execute().

◆ readZip64EndOfCentralDirectoryLocator()

ZipDirectoryReader::readZip64EndOfCentralDirectoryLocator ( )

private

Read the header called the "ZIP64 end of central directory locator".

An error will be raised if it does not exist.

Definition at line 251 of file ZipDirectoryReader.php.

References $data, error(), getBlock(), getFileLength(), getStructSize(), and unpack().

Referenced by findZip64CentralDirectory().

◆ readZip64EndOfCentralDirectoryRecord()

ZipDirectoryReader::readZip64EndOfCentralDirectoryRecord ( )

private

Read the header called the "ZIP64 end of central directory record".

It may replace the regular "end of central directory record" in ZIP64 files.

Definition at line 276 of file ZipDirectoryReader.php.

References $data, error(), getBlock(), getStructSize(), and unpack().

Referenced by findZip64CentralDirectory().

◆ testBit()

ZipDirectoryReader::testBit	(	$value,
		$bitIndex
	)

private

Returns a bit from a given position in an integer value, converted to boolean.

Parameters

int	$value
int	$bitIndex	The index of the bit, where 0 is the LSB.

Returns: bool

Definition at line 681 of file ZipDirectoryReader.php.

Referenced by readCentralDirectory().

◆ unpack()

ZipDirectoryReader::unpack	(	$string,
		$struct,
		$offset = `0`
	)

private

Unpack a binary structure.

This is like the built-in unpack() function except nicer.

Parameters

string	$string	The binary data input
array	$struct	An associative array giving structure members and their types. In the key is the field name. The value may be either an integer, in which case the field is a little-endian unsigned integer encoded in the given number of bytes, or an array, in which case the first element of the array is the type name, and the subsequent elements are type-dependent parameters. Only one such type is defined: "string": The second array element gives the length of string. Not null terminated.
int	$offset	The offset into the string at which to start unpacking.

Exceptions

MWException

Returns: array Unpacked associative array. Note that large integers in the input may be represented as floating point numbers in the return value, so the use of weak comparison is advised.

Definition at line 628 of file ZipDirectoryReader.php.

References $data, $type, error(), and getStructSize().

Referenced by readCentralDirectory(), readEndOfCentralDirectoryRecord(), readZip64EndOfCentralDirectoryLocator(), readZip64EndOfCentralDirectoryRecord(), and unpackZip64Extra().

◆ unpackZip64Extra()

ZipDirectoryReader::unpackZip64Extra ( $extraField )

private

Interpret ZIP64 "extra field" data and return an associative array.

Parameters

string $extraField

Returns: array|bool

Definition at line 466 of file ZipDirectoryReader.php.

References getStructSize(), and unpack().

Referenced by readCentralDirectory().

Member Data Documentation

◆ $buffer

ZipDirectoryReader::$buffer

protected

A segmented cache of the file contents.

Definition at line 104 of file ZipDirectoryReader.php.

◆ $callback

ZipDirectoryReader::$callback

protected

The file data callback.

Definition at line 107 of file ZipDirectoryReader.php.

Referenced by __construct(), and read().

◆ $data

ZipDirectoryReader::$data

protected

Definition at line 115 of file ZipDirectoryReader.php.

Referenced by readCentralDirectory(), readZip64EndOfCentralDirectoryLocator(), readZip64EndOfCentralDirectoryRecord(), and unpack().

◆ $eocdr

ZipDirectoryReader::$eocdr

protected

Stored headers.

Definition at line 113 of file ZipDirectoryReader.php.

◆ $eocdr64

ZipDirectoryReader::$eocdr64

protected

Definition at line 113 of file ZipDirectoryReader.php.

◆ $eocdr64Locator

ZipDirectoryReader::$eocdr64Locator

protected

Definition at line 113 of file ZipDirectoryReader.php.

◆ $file

ZipDirectoryReader::$file

protected

The opened file resource.

Definition at line 98 of file ZipDirectoryReader.php.

◆ $fileLength

ZipDirectoryReader::$fileLength

protected

The cached length of the file, or null if it has not been loaded yet.

Definition at line 101 of file ZipDirectoryReader.php.

Referenced by getBlock(), and getFileLength().

◆ $fileName

ZipDirectoryReader::$fileName

protected

The file name.

Definition at line 95 of file ZipDirectoryReader.php.

Referenced by __construct(), and read().

◆ $zip64

ZipDirectoryReader::$zip64 = false

protected

The ZIP64 mode.

Definition at line 110 of file ZipDirectoryReader.php.

◆ GENERAL_CD_ENCRYPTED

const ZipDirectoryReader::GENERAL_CD_ENCRYPTED = 13

private

The index of the "general field" bit for central directory encryption.

Definition at line 127 of file ZipDirectoryReader.php.

◆ GENERAL_UTF8

const ZipDirectoryReader::GENERAL_UTF8 = 11

private

The index of the "general field" bit for UTF-8 file names.

Definition at line 124 of file ZipDirectoryReader.php.

◆ SEGSIZE

const ZipDirectoryReader::SEGSIZE = 16384

private

The segment size for the file contents cache.

Definition at line 121 of file ZipDirectoryReader.php.

Referenced by getSegment().

◆ ZIP64_EXTRA_HEADER

const ZipDirectoryReader::ZIP64_EXTRA_HEADER = 0x0001

private

The "extra field" ID for ZIP64 central directory entries.

Definition at line 118 of file ZipDirectoryReader.php.

The documentation for this class was generated from the following file:

includes/utils/ZipDirectoryReader.php

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ error()

◆ execute()

◆ findOldCentralDirectory()

◆ findZip64CentralDirectory()

◆ getBlock()

◆ getFileLength()

◆ getSegment()

◆ getStructSize()

◆ read()

◆ readCentralDirectory()

◆ readEndOfCentralDirectoryRecord()

◆ readZip64EndOfCentralDirectoryLocator()

◆ readZip64EndOfCentralDirectoryRecord()

◆ testBit()

◆ unpack()

◆ unpackZip64Extra()

Member Data Documentation

◆ $buffer

◆ $callback

◆ $data

◆ $eocdr

◆ $eocdr64

◆ $eocdr64Locator

◆ $file

◆ $fileLength

◆ $fileName

◆ $zip64

◆ GENERAL_CD_ENCRYPTED

◆ GENERAL_UTF8

◆ SEGSIZE

◆ ZIP64_EXTRA_HEADER