Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
tgz_packer Class Reference
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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 list_files ($archivefile)
 Returns array of info about all files in archive. More...
 
 set_include_index ($includeindex)
 By default, the .tar file includes a .ARCHIVE_INDEX file as its first entry. More...
 

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. More...
 
static has_required_extension ()
 The zlib extension is required for this packer to work. More...
 
static is_tgz_file ($archivefile)
 Checks whether a file appears to be a .tar.gz file. More...
 

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=null, $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. More...
 
 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. More...
 
 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. More...
 

Static Protected Member Functions

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

Protected Attributes

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

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 = null,
  $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$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: