Documentation

SubsPackage
in package

SMF

Various utility functions for working with packages.

These are kept separate from the PackageManager class for memory purposes.

Properties

$package_cache : mixed
$package_ftp : mixed
$temp_path : string

Methods

compareVersions() : int: Compares two versions and determines if one is newer, older or the same, returns - (-1) if version1 is lower than version2 - (0) if version1 is equal to version2 - (1) if version1 is higher than version2
copytree() : void: Copies one directory structure over to another.
create_chmod_control() : array<string|int, mixed>: Create a chmod control for chmoding files.
deltree() : void: Deletes a directory, and all the files and directories inside it.
getPackageInfo() : array<string|int, mixed>|string: Loads a package's information and returns a representative array.
list_restoreFiles() : array<string|int, mixed>: Get a listing of files that will need to be set back to the original state
listtree() : array<string|int, mixed>: Create a tree listing for a given directory path
loadInstalledPackages() : array<string|int, mixed>: Loads and returns an array of installed packages.
matchHighestPackageVersion() : string|bool: Checks if version matches any of the versions in `$versions`.
matchPackageVersion() : bool: Checks if the forum version matches any of the available versions from the package install xml.
mktree() : bool: Creates the specified tree structure with the mode specified.
package_chmod() : bool: Try to make a file writable.
package_create_backup() : bool: Creates a backup of forum files prior to modifying them
package_crypt() : string: Used to crypt the supplied ftp password in this session
package_flush_cache() : void: Flushes the cache from memory to the filesystem
package_get_contents() : string: Get the physical contents of a packages file
package_put_contents() : int: Writes data to a file, almost exactly like the file_put_contents() function.
package_unique_filename() : string: Generates a unique filename for the specified file in the specified directory
package_validate() : array<string|int, mixed>: Validate multiple packages.
package_validate_installtest() : array<string|int, mixed>: Validate a package during install
package_validate_send() : array<string|int, mixed>: Sending data off to validate packages.
packageRequireFTP() : array<string|int, mixed>: Use FTP functions to work with a package download/install
parse_path() : string: Parses special identifiers out of the specified path.
parseBoardMod() : array<string|int, mixed>: Parses a boardmod-style (.mod) modification file
parseModification() : array<string|int, mixed>: Parses a xml-style modification file (file).
parsePackageInfo() : array<string|int, mixed>: Parses the actions in package-info.xml file from packages.
read_tgz_data() : array<string|int, mixed>|string|false: Extracts a file or files from the .tar.gz contained in data.
read_tgz_file() : array<string|int, mixed>|string|false: Reads an archive from either a remote location or from the local filesystem.
read_zip_data() : mixed: Extract zip data.
url_exists() : bool: Checks the existence of a remote file since file_exists() does not do remote.
build_special_files__recursive() : void: Builds a list of special files recursively for a given path
count_directories__recursive() : int: Counts all the directories under a given path
fetchPerms__recursive() : void: Checks the permissions of all the areas that will be affected by the package
fixLangFilePathForRemoval() : void: When removing a language file or directory, figures out whether that file or directory is in the main languages directory or in the default theme's language directory, and then adjusts the package action info accordingly.
smf_crc32() : string: crc32 doesn't work as expected on 64-bit functions - make our own.

$package_cache


    public
    static    mixed
    $package_cache

Holds temporary package data.

$package_ftp


    public
    static    mixed
    $package_ftp

An instance of SMF\PackageManger\FtpConnection.

$temp_path


    public
    static    string
    $temp_path

Path to a temporary copy of a package.

compareVersions()

Compares two versions and determines if one is newer, older or the same, returns - (-1) if version1 is lower than version2 - (0) if version1 is equal to version2 - (1) if version1 is higher than version2


    public
            static        compareVersions(string $version1, string $version2) : int

Parameters

$version1 : string: The first version
$version2 : string: The second version

Return values

int —

-1 if version2 is greater than version1, 0 if they're equal, 1 if version1 is greater than version2

copytree()

Copies one directory structure over to another.


    public
            static        copytree(string $source, string $destination) : void

requires the destination to be writable.

Parameters

$source : string: The directory to copy
$destination : string: The directory to copy $source to

create_chmod_control()

Create a chmod control for chmoding files.


    public
            static        create_chmod_control([array<string|int, mixed> $chmodFiles = [] ][, array<string|int, mixed> $chmodOptions = [] ][, bool $restore_write_status = false ]) : array<string|int, mixed>

Parameters

$chmodFiles : array<string|int, mixed> = []: Which files to chmod
$chmodOptions : array<string|int, mixed> = []: Options for chmod
$restore_write_status : bool = false: Whether to restore write status

Return values

array<string|int, mixed> —

An array of file info

deltree()

Deletes a directory, and all the files and directories inside it.


    public
            static        deltree(string $dir[, bool $delete_dir = true ]) : void

requires access to delete these files.

Parameters

$dir : string: A directory
$delete_dir : bool = true: If false, only deletes everything inside the directory but not the directory itself

getPackageInfo()

Loads a package's information and returns a representative array.


    public
            static        getPackageInfo(string $gzfilename) : array<string|int, mixed>|string

expects the file to be a package in Packages/.
returns an error string if the package-info is invalid.
otherwise returns a basic array of id, version, filename, and similar information.
an XmlArray is available in 'xml'.

Parameters

$gzfilename : string: The path to the file

Return values

array<string|int, mixed>|string —

An array of info about the file or a string indicating an error

list_restoreFiles()

Get a listing of files that will need to be set back to the original state


    public
            static        list_restoreFiles(mixed $dummy1, mixed $dummy2, mixed $dummy3, bool $do_change) : array<string|int, mixed>

Parameters

$dummy1 : mixed
$dummy2 : mixed
$dummy3 : mixed
$do_change : bool

Return values

array<string|int, mixed> —

An array of info about the files that need to be restored back to their original state

listtree()

Create a tree listing for a given directory path


    public
            static        listtree(string $path[, string $sub_path = '' ]) : array<string|int, mixed>

Parameters

$path : string: The path
$sub_path : string = '': The sub-path

Return values

array<string|int, mixed> —

An array of information about the files at the specified path/subpath

loadInstalledPackages()

Loads and returns an array of installed packages.


    public
            static        loadInstalledPackages() : array<string|int, mixed>

default sort order is package_installed time

Return values

array<string|int, mixed> —

An array of info about installed packages

matchHighestPackageVersion()

Checks if version matches any of the versions in `$versions`.


    public
            static        matchHighestPackageVersion(string $versions, bool $reset, string $the_version) : string|bool

supports comma separated version numbers, with or without whitespace.
supports lower and upper bounds. (1.0-1.2)
returns true if the version matched.

Parameters

$versions : string: The versions that this package will install on
$reset : bool: Whether to reset $near_version
$the_version : string: The forum version

Return values

string|bool —

Highest install value string or false

matchPackageVersion()

Checks if the forum version matches any of the available versions from the package install xml.


    public
            static        matchPackageVersion(string $version, string $versions) : bool

supports comma separated version numbers, with or without whitespace.
supports lower and upper bounds. (1.0-1.2)
returns true if the version matched.

Parameters

$version : string: The forum version
$versions : string: The versions that this package will install on

Return values

bool —

Whether the version matched

mktree()

Creates the specified tree structure with the mode specified.


    public
            static        mktree(string $strPath, int $mode) : bool

creates every directory in path until it finds one that already exists.

Parameters

$strPath : string: The path
$mode : int: The permission mode for CHMOD (0666, etc.)

Return values

bool —

True if successful, false otherwise

package_chmod()

Try to make a file writable.


    public
            static        package_chmod(string $filename[, string $perm_state = 'writable' ][, bool $track_change = false ]) : bool

Parameters

$filename : string: The name of the file
$perm_state : string = 'writable': The permission state - can be either 'writable' or 'execute'
$track_change : bool = false: Whether to track this change

Return values

bool —

True if it worked, false if it didn't

package_create_backup()

Creates a backup of forum files prior to modifying them


    public
            static        package_create_backup([string $id = 'backup' ]) : bool

Parameters

$id : string = 'backup': The name of the backup

Return values

bool —

True if it worked, false if it didn't

package_crypt()

Used to crypt the supplied ftp password in this session


    public
            static        package_crypt(string $pass) : string

Parameters

$pass : string: The password

Return values

string —

The encrypted password

package_flush_cache()

Flushes the cache from memory to the filesystem


    public
            static        package_flush_cache([bool $trash = false ]) : void

Parameters

$trash : bool = false

package_get_contents()

Get the physical contents of a packages file


    public
            static        package_get_contents(string $filename) : string

Parameters

$filename : string: The package file

Return values

string —

The contents of the specified file

package_put_contents()

Writes data to a file, almost exactly like the file_put_contents() function.


    public
            static        package_put_contents(string $filename, string $data[, bool $testing = false ]) : int

uses FTP to create/chmod the file when necessary and available. uses text mode for text mode file extensions. returns the number of bytes written.

Parameters

$filename : string: The name of the file
$data : string: The data to write to the file
$testing : bool = false: Whether we're just testing things

Return values

int —

The length of the data written (in bytes)

package_unique_filename()

Generates a unique filename for the specified file in the specified directory


    public
            static        package_unique_filename(string $dir, string $filename, string $ext) : string

Parameters

$dir : string: The directory
$filename : string: The filename without an extension
$ext : string: The extension

Return values

string —

The filename with a number appended but no extension

package_validate()

Validate multiple packages.


    public
            static        package_validate(array<string|int, mixed> $packages) : array<string|int, mixed>

Parameters

$packages : array<string|int, mixed>: Package data

Return values

array<string|int, mixed> —

Results from the package validation.

package_validate_installtest()

Validate a package during install


    public
            static        package_validate_installtest(array<string|int, mixed> $package) : array<string|int, mixed>

Parameters

$package : array<string|int, mixed>: Package data

Return values

array<string|int, mixed> —

Results from the package validation.

package_validate_send()

Sending data off to validate packages.


    public
            static        package_validate_send(array<string|int, mixed> $sendData) : array<string|int, mixed>

Parameters

$sendData : array<string|int, mixed>: Json encoded data to be sent to the validation servers.

Return values

array<string|int, mixed> —

Results from the package validation.

packageRequireFTP()

Use FTP functions to work with a package download/install


    public
            static        packageRequireFTP(string $destination_url[, null|array<string|int, mixed> $files = null ][, bool $return = false ]) : array<string|int, mixed>

Parameters

$destination_url : string: The destination URL
$files : null|array<string|int, mixed> = null: The files to CHMOD
$return : bool = false: Whether to return an array of file info if there's an error

Return values

array<string|int, mixed> —

An array of file info

parse_path()

Parses special identifiers out of the specified path.


    public
            static        parse_path(string $path) : string

Parameters

$path : string: The path

Return values

string —

The parsed path

parseBoardMod()

Parses a boardmod-style (.mod) modification file


    public
            static        parseBoardMod(string $file[, bool $testing = true ][, bool $undo = false ][, array<string|int, mixed> $theme_paths = [] ]) : array<string|int, mixed>

Parameters

$file : string: The modification file to parse
$testing : bool = true: Whether we're just doing a test
$undo : bool = false: If true, specifies that the modifications should be undone. Used when uninstalling.
$theme_paths : array<string|int, mixed> = []: An array of information about custom themes to apply the changes to

Return values

array<string|int, mixed> —

An array of those changes made.

parseModification()

Parses a xml-style modification file (file).


    public
            static        parseModification(string $file[, bool $testing = true ][, bool $undo = false ][, array<string|int, mixed> $theme_paths = [] ]) : array<string|int, mixed>

Parameters

$file : string: The modification file to parse
$testing : bool = true: Whether we're just doing a test
$undo : bool = false: If true, specifies that the modifications should be undone. Used when uninstalling. Doesn't work with regex.
$theme_paths : array<string|int, mixed> = []: An array of information about custom themes to apply the changes to

Return values

array<string|int, mixed> —

An array of those changes made.

parsePackageInfo()

Parses the actions in package-info.xml file from packages.


    public
            static        parsePackageInfo(XmlArray &$packageXML[, bool $testing_only = true ][, string $method = 'install' ][, string $previous_version = '' ]) : array<string|int, mixed>

package should be an XmlArray with package-info as its base.
testing_only should be true if the package should not actually be applied.
method can be upgrade, install, or uninstall. Its default is install.
previous_version should be set to the previous installed version of this package, if any.
does not handle failure terribly well; testing first is always better.

Parameters

$packageXML : XmlArray: The info from the package-info file
$testing_only : bool = true: Whether we're only testing
$method : string = 'install': The method ('install', 'upgrade', or 'uninstall')
$previous_version : string = '': The previous version of the mod, if method is 'upgrade'

Return values

array<string|int, mixed> —

An array of those changes made.

read_tgz_data()

Extracts a file or files from the .tar.gz contained in data.


    public
            static        read_tgz_data(string $data, null|string $destination[, bool $single_file = false ][, bool $overwrite = false ][, null|array<string|int, mixed> $files_to_extract = null ]) : array<string|int, mixed>|string|false

detects if the file is really a .zip file, and if so returns the result of read_zip_data

if destination is null

returns a list of files in the archive.

if single_file is true

returns the contents of the file specified by destination, if it exists, or false.
destination can start with * and / to signify that the file may come from any directory.
destination should not begin with a / if single_file is true.

overwrites existing files with newer modification times if and only if overwrite is true. creates the destination directory if it doesn't exist, and is specified. requires zlib support be built into PHP. returns an array of the files extracted. if files_to_extract is not equal to null only extracts file within this array.

Parameters

$data : string: The gzipped tarball
$destination : null|string: The destination
$single_file : bool = false: Whether to only extract a single file
$overwrite : bool = false: Whether to overwrite existing data
$files_to_extract : null|array<string|int, mixed> = null: If set, only extracts the specified files

Return values

array<string|int, mixed>|string|false —

Information about the extracted files or false on failure

read_tgz_file()

Reads an archive from either a remote location or from the local filesystem.


    public
            static        read_tgz_file(string $gzfilename, null|string $destination[, bool $single_file = false ][, bool $overwrite = false ][, null|array<string|int, mixed> $files_to_extract = null ]) : array<string|int, mixed>|string|false

Parameters

$gzfilename : string: The path to the tar.gz file
$destination : null|string: The path to the destination directory
$single_file : bool = false: If true returns the contents of the file specified by destination if it exists
$overwrite : bool = false: Whether to overwrite existing files
$files_to_extract : null|array<string|int, mixed> = null: Specific files to extract

Return values

array<string|int, mixed>|string|false —

Information about extracted files or false on failure

read_zip_data()

Extract zip data.


    public
            static        read_zip_data(string $data, string|null $destination[, bool $single_file = false ][, bool $overwrite = false ][, array<string|int, mixed> $files_to_extract = null ]) : mixed

If single_file is true, destination can start with * and / to signify that the file may come from any directory. Destination should not begin with a / if single_file is true.

Parameters

$data : string: ZIP data
$destination : string|null: Null to display a listing of files in the archive, the destination for the files in the archive or the name of a single file to display (if $single_file is true)
$single_file : bool = false: If true, returns the contents of the file specified by destination or false if the file can't be found (default value is false).
$overwrite : bool = false: If true, will overwrite files with newer modification times. Default is false.
$files_to_extract : array<string|int, mixed> = null

Return values

mixed —

If destination is null, return a short array of a few file details optionally delimited by $files_to_extract. If $single_file is true, return contents of a file as a string; false otherwise

url_exists()

Checks the existence of a remote file since file_exists() does not do remote.


    public
            static        url_exists(string $url) : bool

will return false if the file is "moved permanently" or similar.

Parameters

$url : string: The URL to parse

Return values

bool —

Whether the specified URL exists

build_special_files__recursive()

Builds a list of special files recursively for a given path


    protected
                    build_special_files__recursive(string $path, array<string|int, mixed> &$data) : void

Parameters

$path : string
$data : array<string|int, mixed>

count_directories__recursive()

Counts all the directories under a given path


    protected
                    count_directories__recursive(string $dir) : int

Parameters

$dir : string

Return values

int

fetchPerms__recursive()

Checks the permissions of all the areas that will be affected by the package


    protected
                    fetchPerms__recursive(string $path, array<string|int, mixed> &$data, int $level) : void

Parameters

$path : string: The path to the directory to check permissions for
$data : array<string|int, mixed>: An array of data about the directory
$level : int: How far deep to go

fixLangFilePathForRemoval()

When removing a language file or directory, figures out whether that file or directory is in the main languages directory or in the default theme's language directory, and then adjusts the package action info accordingly.


    private
            static        fixLangFilePathForRemoval(array<string|int, mixed> &$return, array<string|int, mixed> &$this_action) : void

Parameters

$return : array<string|int, mixed>: The complete set of package action info.
$this_action : array<string|int, mixed>: Info about the current package action.

smf_crc32()

crc32 doesn't work as expected on 64-bit functions - make our own.


    private
            static        smf_crc32(string $number) : string

https://php.net/crc32#79567

Parameters

$number : string

Return values

string —

The crc32

SubsPackage in package SMF

Table of Contents

Properties

Methods

Properties

$package_cache

$package_ftp

$temp_path

Methods

compareVersions()

Parameters

Return values

copytree()

Parameters

create_chmod_control()

Parameters

Return values

deltree()

Parameters

getPackageInfo()

Parameters

Return values

list_restoreFiles()

Parameters

Return values

listtree()

Parameters

Return values

loadInstalledPackages()

Return values

matchHighestPackageVersion()

Parameters

Return values

matchPackageVersion()

Parameters

Return values

mktree()

Parameters

Return values

package_chmod()

Parameters

Return values

package_create_backup()

Parameters

Return values

package_crypt()

Parameters

Return values

package_flush_cache()

Parameters

package_get_contents()

Parameters

Return values

package_put_contents()

Parameters

Return values

package_unique_filename()

Parameters

Tags

Return values

package_validate()

Parameters

Return values

package_validate_installtest()

Parameters

Return values

package_validate_send()

Parameters

Return values

packageRequireFTP()

Parameters

Return values

parse_path()

Parameters

Return values

parseBoardMod()

Parameters

Return values

parseModification()

Parameters

SubsPackage
in package

SMF