Yioop_V9.5_Source_Code_Documentation

VersionManager
in package

VersionManager can be used to create and manage versions of files in a folder so that a user can revert the files to any version desired back to the time the folder under manager was first managed. It is used by Yioop's Wiki system to handle versions of image and other media resources for a Wiki page.

Tags
author

Chris Pollett

Table of Contents

COPY_FAILED  = -8
DELETE_FAILED  = -9
HASH_FILE_NOT_FOUND  = -4
HASH_LOOKUP_FAIL  = -2
INVALID_DIR_ENTRY  = -5
LOCK_FAIL  = -1
MAKE_DIR_FAILED  = -10
PUT_CONTENTS_FAILED  = -11
RENAME_FAILED  = -12
Return code constants for public VersionManager methods
SUCCESS  = 1
TARGET_LOCATION_ERROR  = -6
UNMANAGED_FILE_LOOK_UP  = -7
VERSION_LOOK_UP_FAIL  = -3
$archive_name  : string
Name of subfolder in which to store files when a version of the managed folder is created.
$archive_path  : string
Filesystem path to the archive folder
$hash_algorithm  : string
Hash algorithm to be applied to folder's files inorder to come up with a name to store in a version in the archive.
$lock_file  : string
Filesystem path to file that is used for locking whether a new VersionManager public method is allowed to manipulate files in the archive.
$managed_folder  : string
Folder that is being managed (prior versions of files in it being maintained) by this VersionManager instance
$permissions  : string
File system permissions to use when storing version files into the version archive. If <=0 then use default file permissions
$versions_path  : string
Path to folder in archive in which a list of all versions is maintained
__construct()  : mixed
Creates an object which can be used to manage multiple versions of files in a managed folder, storing prior version in an archive folder using a hash_algorithm to determine how to name these archived files and saving these archived files according to some file system permissions.
createVersion()  : mixed
If $file_changed is not a subpath of $folder then only the $folder file is involved in new version. I.e., a single repository dir file for folder will be made. If $file_changed is a nonexistent file in $folder then the dir's in path to $file_changed will be updated.
deleteFileOrDir()  : mixed
This is a callback function used in the process of recursively deleting a directory
getActiveVersion()  : mixed
Gets the most recent version timestamp of a version in the repository that is less than or equal to the searched for timestamp.
getVersionsInRange()  : mixed
Gets all the versions times that exist in the repository and which are between in time two values.
headCopy()  : int
Copies the data in a file $from_name in the head version of the repository to a different file named $to_name
headDelete()  : int
Deletes a file $file from the version of the repository
headGetContents()  : int
Read from the head version of the repository the contents of $file.
headInfo()  : mixed
Returns the files in the root directory in the most recent version of the repository together with a TIMESTAMP of the date when the most recent version was made.
headMakeDirectory()  : int
Makes a directory named $dir in the current folder in the head version of the repository being managed
headPutContents()  : int
Write $data into the file $file in the head version of the repository
headRename()  : int
Renames the file $old_name in the head version of the repository to a different file named $new_name
restoreVersion()  : int
Restores the version of the repository that existed at a timestamp to the managed folder. Files currently in the managed folder before the restored but which exist in the HEAD version of the repository are removed from the managed folder (kept in repository).
traverseDirectory()  : array<string|int, mixed>
Recursively traverse a directory structure and call a callback function
unlinkRecursive()  : mixed
Recursively delete a file or directory
versionGetContents()  : mixed
Retrieves the contents of a file from a particular version of the repository
copyFromVersionOrHashName()  : mixed
Copies to the target folder in the managed folder a file or directory that existed at a given timestamp in the archive repository
deleteVersionFileOrFolder()  : mixed
This function is used in the process of recursively deleting a directory
getArchiveFileAndPath()  : array<string|int, mixed>
Gets the hash file name and path within the archive repository for a file name from the managed folder that existed at timestamp
getArchivePathHashName()  : string
Get the path in the repository archive that corresponds to the given hash name of an object that might be in the repository.
getHashNamePath()  : string
Given a file or directory and a timestamp finds the path to that file in the repository by traversing the repository and looking the hash names of folders subfolders in the repository.
getVersionPath()  : string
Versions are stored in the version subfolder of the archive repository within a year folder within a day folder. Given a timestamp this function returns the path of the version folder it would correspond to
traverseUnlinkHead()  : mixed
Recursively traverse a directory structure and call a callback function
unlinkHead()  : mixed
Delete all the files from the managed folder which exist in the HEAD version in the archive repository

Constants

RENAME_FAILED

Return code constants for public VersionManager methods

public mixed RENAME_FAILED = -12

Properties

$archive_name

Name of subfolder in which to store files when a version of the managed folder is created.

public string $archive_name

$archive_path

Filesystem path to the archive folder

public string $archive_path

$hash_algorithm

Hash algorithm to be applied to folder's files inorder to come up with a name to store in a version in the archive.

public string $hash_algorithm

$lock_file

Filesystem path to file that is used for locking whether a new VersionManager public method is allowed to manipulate files in the archive.

public string $lock_file

$managed_folder

Folder that is being managed (prior versions of files in it being maintained) by this VersionManager instance

public string $managed_folder

$permissions

File system permissions to use when storing version files into the version archive. If <=0 then use default file permissions

public string $permissions

$versions_path

Path to folder in archive in which a list of all versions is maintained

public string $versions_path

Methods

__construct()

Creates an object which can be used to manage multiple versions of files in a managed folder, storing prior version in an archive folder using a hash_algorithm to determine how to name these archived files and saving these archived files according to some file system permissions.

public __construct([string $managed_folder = '.' ][, string $archive_name = '.archive' ][, string $hash_algorithm = 'sha256' ][, int $permissions = 0777 ]) : mixed
Parameters
$managed_folder : string = '.'

what folder should be managed with this versioning system

$archive_name : string = '.archive'

file_name in the folder to use for the subfolder containing the archived versions of files

$hash_algorithm : string = 'sha256'

what hash algorithm should be used to generate archive filenames. Defaults to sha256

$permissions : int = 0777

what to set the file permissions to for the archive file. To keep things simple this defaults to world read write. In practice you probably want to tailor this to the situation for security. If you set the value to <= 0 the permissions will be whatever your OS would use by default

Return values
mixed —

createVersion()

If $file_changed is not a subpath of $folder then only the $folder file is involved in new version. I.e., a single repository dir file for folder will be made. If $file_changed is a nonexistent file in $folder then the dir's in path to $file_changed will be updated.

public createVersion([string $file_changed = "" ][, string $folder = "" ], int $now[, bool $lock = true ][, array<string|int, mixed> $force_update_list = [] ]) : mixed
Parameters
$file_changed : string = ""
$folder : string = ""
$now : int
$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

$force_update_list : array<string|int, mixed> = []
Return values
mixed —

either an error code or the name of the hash_file in the repository for the version just created

deleteFileOrDir()

This is a callback function used in the process of recursively deleting a directory

public deleteFileOrDir(string $file_or_dir) : mixed
Parameters
$file_or_dir : string

the filename or directory name to be deleted

Tags
see
unlinkRecursive()
Return values
mixed —

getActiveVersion()

Gets the most recent version timestamp of a version in the repository that is less than or equal to the searched for timestamp.

public getActiveVersion(int $search_timestamp[, bool $lock = true ]) : mixed
Parameters
$search_timestamp : int

want to find the version in the repository closest to, but not exceeding this value.

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
mixed —

getVersionsInRange()

Gets all the versions times that exist in the repository and which are between in time two values.

public getVersionsInRange(int $start_time, int $end_time[, bool $lock = true ]) : mixed
Parameters
$start_time : int

look for timestamps in repository above or equal this value

$end_time : int

look for timestamps in repository below or equal this value

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
mixed —

headCopy()

Copies the data in a file $from_name in the head version of the repository to a different file named $to_name

public headCopy(string $from_name, string $to_name[, bool $lock = true ]) : int
Parameters
$from_name : string

name of file or dir to copy

$to_name : string

name of file or dir to save copy to

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
int —

success code

headDelete()

Deletes a file $file from the version of the repository

public headDelete(string $file[, bool $lock = true ]) : int
Parameters
$file : string

name of file to delete

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
int —

success code

headGetContents()

Read from the head version of the repository the contents of $file.

public headGetContents(string $file[, bool $lock = true ]) : int
Parameters
$file : string

name of file to get contents of

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
int —

success code

headInfo()

Returns the files in the root directory in the most recent version of the repository together with a TIMESTAMP of the date when the most recent version was made.

public headInfo([bool $lock = true ]) : mixed
Parameters
$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
mixed —

either any array [TIMESTAMP => time of last version, FILES => files in last version's folder] or LOCK_FAIL error code

headMakeDirectory()

Makes a directory named $dir in the current folder in the head version of the repository being managed

public headMakeDirectory(string $dir[, bool $lock = true ]) : int
Parameters
$dir : string

name of directory folder to make

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
int —

success code

headPutContents()

Write $data into the file $file in the head version of the repository

public headPutContents(string $file, string $data[, bool $lock = true ]) : int
Parameters
$file : string

name of file to store data for

$data : string

what to store in the file $file

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
int —

success code

headRename()

Renames the file $old_name in the head version of the repository to a different file named $new_name

public headRename(string $old_name, string $new_name[, bool $lock = true ]) : int
Parameters
$old_name : string

original name of file

$new_name : string

what to change it to

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
int —

success code

restoreVersion()

Restores the version of the repository that existed at a timestamp to the managed folder. Files currently in the managed folder before the restored but which exist in the HEAD version of the repository are removed from the managed folder (kept in repository).

public restoreVersion(int $timestamp[, bool $lock = true ][, bool $force_lock = false ]) : int
Parameters
$timestamp : int

of version what to restore to

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

$force_lock : bool = false

whether or not any existing lock should be ignored

Return values
int —

success code

traverseDirectory()

Recursively traverse a directory structure and call a callback function

public traverseDirectory(string $dir, function $callback[, bool $root_too = true ]) : array<string|int, mixed>
Parameters
$dir : string

directory name

$callback : function

Function to call as traverse structure

$root_too : bool = true

whether to have an apply the callback to the whole directory as well

Return values
array<string|int, mixed> —

results computed by performing the traversal

unlinkRecursive()

Recursively delete a file or directory

public unlinkRecursive(string $dir[, bool $delete_root_too = true ]) : mixed
Parameters
$dir : string

file or directory name

$delete_root_too : bool = true

Delete specified top directory as well

Return values
mixed —

versionGetContents()

Retrieves the contents of a file from a particular version of the repository

public versionGetContents(string $file, int $timestamp[, bool $get_nearest_version = false ][, bool $lock = true ]) : mixed
Parameters
$file : string

name of file to get data about

$timestamp : int

which version want to get file out of

$get_nearest_version : bool = false

if true then if $timestamp doesn't exist as a version get the nearest version after $timestamp

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
mixed —

either a string with the file's data or an error code

copyFromVersionOrHashName()

Copies to the target folder in the managed folder a file or directory that existed at a given timestamp in the archive repository

protected copyFromVersionOrHashName(string $file, string $target, int $timestamp[, string $hash_name_type = "" ][, bool $lock = true ]) : mixed
Parameters
$file : string

file name of file or directory to copy to managed folder

$target : string

folder to copy to

$timestamp : int

which archive version of the file to copy

$hash_name_type : string = ""

either f, l, or d depending on whether the object in the repository is known to be a file, link, or folder. If left empty then this is looked up in the repository

$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
mixed —

deleteVersionFileOrFolder()

This function is used in the process of recursively deleting a directory

protected deleteVersionFileOrFolder(string $file_or_dir, int $timestamp) : mixed
Parameters
$file_or_dir : string

the filename or directory name to be deleted

$timestamp : int

only deletes if the file existed in the version given by the timestamp in the repository

Return values
mixed —

getArchiveFileAndPath()

Gets the hash file name and path within the archive repository for a file name from the managed folder that existed at timestamp

protected getArchiveFileAndPath(string $file, int $timestamp[, bool $make_path = false ]) : array<string|int, mixed>
Parameters
$file : string

name of file want to get the archive name and archive path for

$timestamp : int

of version want to compute archive filename and path for

$make_path : bool = false

whether to make folders (if they don't exists already) in the archive repository for the path calculated

Return values
array<string|int, mixed> —

[hash_name, archive_path] to use for file in the repository for object given that version timestamp

getArchivePathHashName()

Get the path in the repository archive that corresponds to the given hash name of an object that might be in the repository.

protected getArchivePathHashName(string $hash_name) : string

Currently, the archive consists of two nested folders based on prefixes of objects stored in the repository, so this method calculates those prefixes and tacks them on to the archive path.

Parameters
$hash_name : string

to make a archive path for

Return values
string —

path to $hash_name object in repository archive

getHashNamePath()

Given a file or directory and a timestamp finds the path to that file in the repository by traversing the repository and looking the hash names of folders subfolders in the repository.

protected getHashNamePath(string $file, int $timestamp[, bool $get_nearest_version = false ][, string $path_so_far = "" ][, string $hash_path_so_far = "" ]) : string

The timestamp that is lookedup might not be the timestamp of the file because when created a version that file might not have changed so its old info is copied into the new version. This is why a traversal might be needed.

Parameters
$file : string

name of file to get path for

$timestamp : int

which version in repository want to get file for

$get_nearest_version : bool = false

if true then if $timestamp doesn't exist as a version get the nearest version after $timestamp

$path_so_far : string = ""

path in managed folder that this recursive procedure has already traversed

$hash_path_so_far : string = ""

corresponding path to path_so_far but in the archive repository

Return values
string —

path to file in the archive repository

getVersionPath()

Versions are stored in the version subfolder of the archive repository within a year folder within a day folder. Given a timestamp this function returns the path of the version folder it would correspond to

protected getVersionPath(int $timestamp[, bool $make_path = false ]) : string
Parameters
$timestamp : int

to find version folder for

$make_path : bool = false

whether to make folders (if they don't exists already) in the archive repository for the path calculated

Return values
string —

path to version folder

traverseUnlinkHead()

Recursively traverse a directory structure and call a callback function

protected traverseUnlinkHead(string $dir, int $timestamp) : mixed
Parameters
$dir : string

name of folder to delete

$timestamp : int

only deletes if the file existed in the version given by the timestamp in the repository (by default this is the timestamp asscoaited with the HEAD version)

Return values
mixed —

unlinkHead()

Delete all the files from the managed folder which exist in the HEAD version in the archive repository

protected unlinkHead([bool $lock = true ]) : mixed
Parameters
$lock : bool = true

whether or not a lock should be obtained before carrying out the operation

Return values
mixed — 

        

        
    




    

    

                

    

        

            
Search results