Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
tgz_packer Class Reference

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

Inheritance diagram for tgz_packer:
file_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.

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$filesarray from archive path => pathname or stored_file
string$archivefilepath to target zip file
bool$ignoreinvalidfilestrue means ignore missing or invalid files, false means abort on any error
file_progress$progressProgress indicator callback or null if not required
Return values
booltrue if file created, false if not
Exceptions
coding_exceptionIf 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$filesarray from archive path => pathname or stored_file
int$contextidcontext ID
string$componentcomponent
string$fileareafile area
int$itemiditem ID
string$filepathfile path
string$filenamefile name
int$useriduser ID
bool$ignoreinvalidfilestrue means ignore missing or invalid files, false means abort on any error
file_progress$progressProgress indicator callback or null if not required
Return values
stored_file|boolfalse if error stored_file instance if ok
Exceptions
file_exceptionIf file operations fail
coding_exceptionIf 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$strInput string
Return values
intChecksum

◆ 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$fsFile storage
array$filerecordFile 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$archivefilefull pathname of zip file or stored_file instance
string$pathnametarget directory
array$onlyfilesonly extract files present in the array
file_progress$progressProgress indicator callback or null if not required
bool$returnboolWhether to return a basic true/false indicating error state, or full per-file error details.
Return values
arraylist of processed files (name=>true)
Exceptions
moodle_exceptionIf 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$archivefilefull pathname of zip file or stored_file instance
int$contextidcontext ID
string$componentcomponent
string$fileareafile area
int$itemiditem ID
string$pathbasefile path
int$useriduser ID
file_progress$progressProgress indicator callback or null if not required
Return values
arraylist of processed files (name=>true)
Exceptions
moodle_exceptionIf 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
boolTrue 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
boolTrue 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
arrayof 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$expandedfilesList of all files to archive (output)
string$archivepathCurrent path within archive
string$pathOS path on disk
file_progress | null$progressProgress indicator or null if none
int$doneValue for progress indicator
Return values
boolTrue 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$expandedfilesList of all files to archive (output)
string$archivepathCurrent path within archive
stored_file$fileFile 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$includeindexIf 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$gzGzip file
string$archivepathFull path of file within archive
string | resource$fileFull path of file on disk or file handle or null if none
int$sizeSize or 0 for directories
int | string$mtimeTime or ? if unknown
string$contentActual content of file to write (null if using $filepath)
file_progress$progressProgress indicator or null if none
int$doneValue for progress indicator
Return values
boolTrue if OK
Exceptions
coding_exceptionIf names aren't valid

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