Utility class - handles all packing/unpacking of .tar.gz files. More...

Inheritance diagram for tgz_packer:

Public Member Functions
	archive_to_pathname (array $files, $archivefile, $ignoreinvalidfiles=true, file_progress $progress=null)
	Archive files and store the result in an OS file.

	archive_to_storage (array $files, $contextid, $component, $filearea, $itemid, $filepath, $filename, $userid=null, $ignoreinvalidfiles=true, file_progress $progress=null)
	Archive files and store the result in file storage.

	extract_to_pathname ($archivefile, $pathname, array $onlyfiles=null, file_progress $progress=null, $returnbool=false)
	Extract file to given file path (real OS filesystem), existing files are overwritten.

	extract_to_storage ($archivefile, $contextid, $component, $filearea, $itemid, $pathbase, $userid=null, file_progress $progress=null)
	Extract file to given file path (real OS filesystem), existing files are overwritten.

	list_files ($archivefile)
	Returns array of info about all files in archive.

	set_include_index ($includeindex)
	By default, the .tar file includes a .ARCHIVE_INDEX file as its first entry.

Static Public Member Functions
static	delete_existing_file_record (file_storage $fs, array $filerecord)
	Wrapper function useful for deleting an existing file (if present) just before creating a new one.

static	has_required_extension ()
	The zlib extension is required for this packer to work.

static	is_tgz_file ($archivefile)
	Checks whether a file appears to be a .tar.gz file.

Public Attributes
string const	ARCHIVE_INDEX_COUNT_PREFIX = 'Moodle archive file index. Count: '
	Required text at start of archive index file before file count.

string const	ARCHIVE_INDEX_FILE = '.ARCHIVE_INDEX'
	Name of special archive index file added by Moodle.

int const	DEFAULT_TIMESTAMP = 1356998400
	Default timestamp used where unknown (Jan 1st 2013 00:00)

int const	PROGRESS_MAX = 1000000
	Max value for total progress.

int const	TAR_BLOCK_SIZE = 512
	Tar files have a fixed block size of 512 bytes.

Protected Member Functions
	list_files_path (array &$expandedfiles, $archivepath, $path, ?file_progress $progress, $done)
	Based on an OS path, adds either that path (if it's a file) or all its children (if it's a directory) into the list of files to archive.

	list_files_stored (array &$expandedfiles, $archivepath, stored_file $file)
	Based on a stored_file objects, adds either that file (if it's a file) or all its children (if it's a directory) into the list of files to archive.

	write_tar_entry ($gz, $archivepath, $file, $size, $mtime, $content=null, file_progress $progress=null, $done=0)
	Writes a single tar file to the archive, including its header record and then the file contents.

Static Protected Member Functions
static	calculate_checksum ($str)
	Calculates a checksum by summing all characters of the binary string (treating them as unsigned numbers).

Protected Attributes
bool	$includeindex = true
	If true, includes .ARCHIVE_INDEX file in root of tar file.

Detailed Description

Utility class - handles all packing/unpacking of .tar.gz files.

Copyright: 2013 The Open University

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ archive_to_pathname()

tgz_packer::archive_to_pathname	(	array	$files,
			$archivefile,
			$ignoreinvalidfiles = true,
		file_progress	$progress = null )

Archive files and store the result in an OS file.

Parameters

array	$files	array from archive path => pathname or stored_file
string	$archivefile	path to target zip file
bool	$ignoreinvalidfiles	true means ignore missing or invalid files, false means abort on any error
file_progress	$progress	Progress indicator callback or null if not required

Return values

bool	true if file created, false if not

Exceptions

coding_exception If any archive paths do not meet the restrictions

Reimplemented from file_packer.

◆ archive_to_storage()

tgz_packer::archive_to_storage	(	array	$files,
			$contextid,
			$component,
			$filearea,
			$itemid,
			$filepath,
			$filename,
			$userid = null,
			$ignoreinvalidfiles = true,
		file_progress	$progress = null )

Archive files and store the result in file storage.

Any existing file at that location will be overwritten.

Parameters

array	$files	array from archive path => pathname or stored_file
int	$contextid	context ID
string	$component	component
string	$filearea	file area
int	$itemid	item ID
string	$filepath	file path
string	$filename	file name
int	$userid	user ID
bool	$ignoreinvalidfiles	true means ignore missing or invalid files, false means abort on any error
file_progress	$progress	Progress indicator callback or null if not required

Return values

stored_file|bool false if error stored_file instance if ok

Exceptions

file_exception	If file operations fail
coding_exception	If any archive paths do not meet the restrictions

Reimplemented from file_packer.

◆ calculate_checksum()

static tgz_packer::calculate_checksum ( $str )

staticprotected

Calculates a checksum by summing all characters of the binary string (treating them as unsigned numbers).

Parameters

string $str Input string

Return values

int Checksum

◆ delete_existing_file_record()

static tgz_packer::delete_existing_file_record	(	file_storage	$fs,
		array	$filerecord )

static

Wrapper function useful for deleting an existing file (if present) just before creating a new one.

Parameters

file_storage	$fs	File storage
array	$filerecord	File record in same format used to create file

◆ extract_to_pathname()

tgz_packer::extract_to_pathname	(		$archivefile,
			$pathname,
		array	$onlyfiles = null,
		file_progress	$progress = null,
			$returnbool = false )

Extract file to given file path (real OS filesystem), existing files are overwritten.

Parameters

stored_file \| string	$archivefile	full pathname of zip file or stored_file instance
string	$pathname	target directory
array	$onlyfiles	only extract files present in the array
file_progress	$progress	Progress indicator callback or null if not required
bool	$returnbool	Whether to return a basic true/false indicating error state, or full per-file error details.

Return values

array list of processed files (name=>true)

Exceptions

moodle_exception If error

Reimplemented from file_packer.

◆ extract_to_storage()

tgz_packer::extract_to_storage	(		$archivefile,
			$contextid,
			$component,
			$filearea,
			$itemid,
			$pathbase,
			$userid = null,
		file_progress	$progress = null )

Extract file to given file path (real OS filesystem), existing files are overwritten.

Parameters

string \| stored_file	$archivefile	full pathname of zip file or stored_file instance
int	$contextid	context ID
string	$component	component
string	$filearea	file area
int	$itemid	item ID
string	$pathbase	file path
int	$userid	user ID
file_progress	$progress	Progress indicator callback or null if not required

Return values

array list of processed files (name=>true)

Exceptions

moodle_exception If error

Reimplemented from file_packer.

◆ has_required_extension()

static tgz_packer::has_required_extension ( )

static

The zlib extension is required for this packer to work.

This is a single location for the code to check whether the extension is available.

Deprecated: since 2.7 Always true because zlib extension is now required.

Return values

bool	True if the zlib extension is available OK

◆ is_tgz_file()

static tgz_packer::is_tgz_file ( $archivefile )

static

Checks whether a file appears to be a .tar.gz file.

Parameters

string | stored_file $archivefile

Return values

bool	True if file contains the gzip magic number

◆ list_files()

tgz_packer::list_files ( $archivefile )

Returns array of info about all files in archive.

Parameters

string | stored_file $archivefile

Return values

array of file infos

Reimplemented from file_packer.

◆ list_files_path()

tgz_packer::list_files_path	(	array &	$expandedfiles,
			$archivepath,
			$path,
		?file_progress	$progress,
			$done )

protected

Based on an OS path, adds either that path (if it's a file) or all its children (if it's a directory) into the list of files to archive.

If a progress indicator is supplied and if this corresponds to a directory, then it will be repeatedly called with the same values. This allows the progress handler to respond in some way to avoid timeouts if required.

Parameters

array	$expandedfiles	List of all files to archive (output)
string	$archivepath	Current path within archive
string	$path	OS path on disk
file_progress \| null	$progress	Progress indicator or null if none
int	$done	Value for progress indicator

Return values

bool	True if successful

◆ list_files_stored()

tgz_packer::list_files_stored	(	array &	$expandedfiles,
			$archivepath,
		stored_file	$file )

protected

Based on a stored_file objects, adds either that file (if it's a file) or all its children (if it's a directory) into the list of files to archive.

If a progress indicator is supplied and if this corresponds to a directory, then it will be repeatedly called with the same values. This allows the progress handler to respond in some way to avoid timeouts if required.

Parameters

array	$expandedfiles	List of all files to archive (output)
string	$archivepath	Current path within archive
stored_file	$file	File object

◆ set_include_index()

tgz_packer::set_include_index ( $includeindex )

By default, the .tar file includes a .ARCHIVE_INDEX file as its first entry.

This makes list_files much faster and allows for better progress reporting.

If you need to disable the inclusion of this file, use this function before calling one of the archive_xx functions.

Parameters

bool $includeindex If true, includes index

◆ write_tar_entry()

tgz_packer::write_tar_entry	(		$gz,
			$archivepath,
			$file,
			$size,
			$mtime,
			$content = null,
		file_progress	$progress = null,
			$done = 0 )

protected

Writes a single tar file to the archive, including its header record and then the file contents.

Parameters

resource	$gz	Gzip file
string	$archivepath	Full path of file within archive
string \| resource	$file	Full path of file on disk or file handle or null if none
int	$size	Size or 0 for directories
int \| string	$mtime	Time or ? if unknown
string	$content	Actual content of file to write (null if using $filepath)
file_progress	$progress	Progress indicator or null if none
int	$done	Value for progress indicator

Return values

bool	True if OK

Exceptions

coding_exception If names aren't valid

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

lib/filestorage/tgz_packer.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ archive_to_pathname()

◆ archive_to_storage()

◆ calculate_checksum()

◆ delete_existing_file_record()

◆ extract_to_pathname()

◆ extract_to_storage()

◆ has_required_extension()

◆ is_tgz_file()

◆ list_files()

◆ list_files_path()

◆ list_files_stored()

◆ set_include_index()

◆ write_tar_entry()