Class

eZFSFileHandler

class eZFSFileHandler implements eZClusterFileHandlerInterface

File containing the eZFSFileHandler class.

Constants

EXPIRY_TIMESTAMP

Properties

$metaData
$filePath

Methods

__construct(bool $filePath = false)

Constructor.

_exclusiveLock($fname = false)

_freeExclusiveLock($fname = false)

_mutex()

void loadMetaData(bool $force = false)

Loads file meta information.

string|false fileFetch(string $filePath)

Fetches file from db and saves it in FS under the same name.

fetch(bool $noLocalCache = false)

Fetches file from db and saves it in FS under the same name.

string fetchUnique()

Fetches file from db and saves it in FS under unique name.

void fileStore(string $filePath, string $scope = false, bool $delete = false, string $datatype = false)

Store file.

void fileStoreContents(string $filePath, string $contents, string $scope = false, string $datatype = false)

Store file contents.

void storeContents(string $contents, string $scope = false, string $datatype = false, bool $storeLocally = false)

Store file contents to disk

string|false fileFetchContents(string $filePath)

Returns file contents.

string|bool fetchContents()

Returns file contents.

processCache($retrieveCallback, $generateCallback = null, $ttl = null, $expiry = null, $extraData = null)

Handles cache requests / write operations

static bool isFileExpired(string $fname, int $mtime, int $expiry, int $curtime, int $ttl)

Calculates if the file data is expired or not.

bool isExpired(int $expiry, int $curtime, int $ttl)

Calculates if the current file data is expired or not.

string|null storeCache(string|array $fileData, $storeCache = true)

Stores the data in $fileData to the remote and local file and commits the transaction.

processFile($callback, $expiry = false, $extraData = null)

Provides access to the file contents by downloading the file locally and calling $callback with the local filename.

stat()

Returns file metadata.

int|null size()

Returns file size.

string|null dataType()

Returns file mime-type / content-type.

int|null mtime()

Returns file modification time.

string name()

Returns file name.

fileDeleteByWildcard($wildcard)

Delete files matching given wildcard.

fileDeleteByDirList($dirList, $commonPath, $commonSuffix)

Delete files located in a directories from dirList, with common prefix specified by commonPath, and common suffix with added wildcard at the end

fileDelete($path, $fnamePart = false)

\public \static

delete()

Deletes specified file/directory.

fileDeleteLocal($path)

Deletes a file that has been fetched before.

deleteLocal()

Deletes a file that has been fetched before.

purge($printCallback = false, $microsleep = false, $max = false, $expiry = false)

Purges local and remote file data for current file.

bool fileExists($path)

Check if given file/dir exists.

bool exists()

Check if given file/dir exists.

passthrough(int $offset, int $length = false)

Outputs file contents to the browser Note: does not handle headers.

fileCopy($srcPath, $dstPath)

Copy file.

fileLinkCopy($srcPath, $dstPath, $symLink)

Create symbolic or hard link to file.

fileMove($srcPath, $dstPath)

Move file.

move(string $dstPath)

Move file.

mixed startCacheGeneration()

Starts cache generation for the current file.

endCacheGeneration($rename = true)

Ends the cache generation started by startCacheGeneration().

abortCacheGeneration()

Aborts the current cache generation process.

checkCacheGenerationTimeout()

Checks if the .generating file was changed, which would mean that generation timed out.

bool requiresClusterizing()

eZFS only stores data to FS and doesn't require/support clusterizing

bool requiresPurge()

eZFS does not require binary purge.

bool hasStaleCacheSupport()

Indicates if the handler supports the stalecache feature

getFileList(array $scopes = false, boolean $excludeScopes = false)

Get list of files stored in database.

bool isDBFileExpired(int $expiry, int $curtime, int $ttl)

Calculates if the DB file is expired or not.

bool isLocalFileExpired(int $expiry, int $curtime, int $ttl)

Calculates if the local file is expired or not.

string applyServerUri(string $filePath)

No transformation is required since files are served from the same host

Details

at line 20
public __construct(bool $filePath = false)

Constructor.

Parameters

bool $filePath File path. If specified, file metadata is fetched in the constructor.

at line 40
public _exclusiveLock($fname = false)

Parameters

$fname

at line 85
public _freeExclusiveLock($fname = false)

Parameters

$fname

at line 95
public _mutex()

at line 109
public void loadMetaData(bool $force = false)

Loads file meta information.

Parameters

bool $force File stats will be refreshed if true

Return Value

void

at line 130
public string|false fileFetch(string $filePath)

Fetches file from db and saves it in FS under the same name.

In case of fetching from filesystem does nothing.

Parameters

string $filePath

Return Value

string|false the file path, or false if fetching failed

at line 141
public fetch(bool $noLocalCache = false)

Fetches file from db and saves it in FS under the same name.

In case of fetching from filesystem does nothing.

Parameters

bool $noLocalCache

at line 154
public string fetchUnique()

Fetches file from db and saves it in FS under unique name.

In case of fetching from filesystem, does nothing

Return Value

string The unique file path. on FS, the file path.

at line 169
public void fileStore(string $filePath, string $scope = false, bool $delete = false, string $datatype = false)

Store file.

In case of storing to filesystem does nothing.

Parameters

string $filePath Path to the file being stored.
string $scope Means something like "file category". May be used to clean caches of a certain type.
bool $delete true if the file should be deleted after storing.
string $datatype

Return Value

void

at line 180
public void fileStoreContents(string $filePath, string $contents, string $scope = false, string $datatype = false)

Store file contents.

\public \static

Parameters

string $filePath Path to the file being stored.
string $contents Binary file content
string $scope "file category". May be used by cache management
string $datatype Datatype for the file. Also used to clean cache up

Return Value

void

at line 204
public void storeContents(string $contents, string $scope = false, string $datatype = false, bool $storeLocally = false)

Store file contents to disk

Parameters

string $contents Binary file content
string $scope "file category". May be used by cache management
string $datatype Datatype for the file. Also used to clean cache up
bool $storeLocally If true the file will also be stored on the local file system.

Return Value

void

at line 224
public string|false fileFetchContents(string $filePath)

Returns file contents.

Parameters

string $filePath

Return Value

string|false contents string, or false in case of an error.

at line 241
public string|bool fetchContents()

Returns file contents.

\public \return contents string, or false in case of an error.

Return Value

string|bool contents string, or false in case of an error.

at line 298
public processCache($retrieveCallback, $generateCallback = null, $ttl = null, $expiry = null, $extraData = null)

Handles cache requests / write operations

Creates a single transaction out of the typical file operations for accessing caches. Caches are normally ready from the database or local file, if the entry does not exist or is expired then it generates the new cache data and stores it. This method takes care of these operations and handles the custom code by performing callbacks when needed.

The $retrieveCallback is used when the file contents can be used (ie. not re-generation) and is called when the file is ready locally. The function will be called with the file path as the first parameter, the mtime as the second and optionally $extraData as the third. The function must return the file contents or an instance of eZClusterFileFailure which can be used to tell the system that the retrieve data cannot be used after all.

$retrieveCallback can be set to null which makes the system go directly to the generation.

The $generateCallback is used when the file content is expired or does not exist, in this case the content must be re-generated and stored. The function will be called with the file path as the first parameter and optionally $extraData as the second. The function must return an array with information on the contents, the array consists of: - scope - The current scope of the file, is optional. - datatype - The current datatype of the file, is optional. - content - The file content, this can be any type except null. - binarydata - The binary data which is written to the file. - store - Whether content or binarydata should be stored to the file, if false it will simply return the data. Optional, by default it is true. Note: Set $generateCallback to false to disable generation callback. Note: Set $generateCallback to null to tell the function to perform a write lock but not do any generation, the generation must done be done by the caller by calling see storeCache().

Either content or binarydata must be supplied, if not an error is issued and it returns null.

If content is set it will be used as the return value of this function, if not it will return the binary data. If binarydata is set it will be used as the binary data for the file, if not it will perform a var_export on *content* and use that as the binary data.

For convenience the $generateCallback function can return a string which will be considered as the binary data for the file and returned as the content.

For controlling how long a cache entry can be used the parameters

Parameters

$retrieveCallback
$generateCallback
$ttl
$expiry
$extraData

at line 420
static public bool isFileExpired(string $fname, int $mtime, int $expiry, int $curtime, int $ttl)

Calculates if the file data is expired or not.

Parameters

string $fname Name of file, available for easy debugging.
int $mtime Modification time of file, can be set to false if file does not exist.
int $expiry Time when file is to be expired, a value of -1 will disable this check.
int $curtime The current time to check against.
int $ttl Number of seconds the data can live, set to null to disable TTL.

Return Value

bool

at line 450
public bool isExpired(int $expiry, int $curtime, int $ttl)

Calculates if the current file data is expired or not.

Parameters

int $expiry Time when file is to be expired, a value of -1 will disable this check.
int $curtime The current time to check against.
int $ttl Number of seconds the data can live, set to null to disable TTL.

Return Value

bool

at line 468
public string|null storeCache(string|array $fileData, $storeCache = true)

Stores the data in $fileData to the remote and local file and commits the transaction.

The parameter $fileData must contain the same as information as the $generateCallback returns as explained in processCache().

This method is just a continuation of the code in processCache() and is not meant to be called alone since it relies on specific state in the database.

Parameters

string|array $fileData
$storeCache

Return Value

string|null

at line 540
public processFile($callback, $expiry = false, $extraData = null)

Provides access to the file contents by downloading the file locally and calling $callback with the local filename.

The callback can then process the contents and return the data in the same way as in processCache().

Downloading is only done once so the local copy is kept, while updates to the remote DB entry is synced with the local one.

The parameters $expiry and $extraData is the same as for processCache().

Parameters

$callback
$expiry
$extraData

at line 555
public stat()

Returns file metadata.

\public

at line 566
public int|null size()

Returns file size.

\public

Return Value

int|null

at line 577
public string|null dataType()

Returns file mime-type / content-type.

Return Value

string|null

at line 590
public int|null mtime()

Returns file modification time.

\public

Return Value

int|null

at line 602
public string name()

Returns file name.

\public

Return Value

string

at line 614
public fileDeleteByWildcard($wildcard)

Delete files matching given wildcard.

\public \static

Parameters

$wildcard

at line 635
public fileDeleteByDirList($dirList, $commonPath, $commonSuffix)

Delete files located in a directories from dirList, with common prefix specified by commonPath, and common suffix with added wildcard at the end

\public \static

Parameters

$dirList
$commonPath
$commonSuffix

at line 657
public fileDelete($path, $fnamePart = false)

\public \static

Parameters

$path
$fnamePart

at line 707
public delete()

Deletes specified file/directory.

If a directory specified it is deleted recursively.

\public \static

at line 741
public fileDeleteLocal($path)

Deletes a file that has been fetched before.

Parameters

$path

See also

fetchUnique In case of fetching from filesystem does nothing.

at line 753
public deleteLocal()

Deletes a file that has been fetched before.

In case of fetching from filesystem does nothing.

\public

at line 762
public purge($printCallback = false, $microsleep = false, $max = false, $expiry = false)

Purges local and remote file data for current file.

Parameters

$printCallback
$microsleep
$max
$expiry

at line 822
public bool fileExists($path)

Check if given file/dir exists.

\public \static

Parameters

$path

Return Value

bool

at line 841
public bool exists()

Check if given file/dir exists.

NOTE: this function does not interact with filesystem. Instead, it just returns existance status determined in the constructor.

\public

Return Value

bool

at line 856
public passthrough(int $offset, int $length = false)

Outputs file contents to the browser Note: does not handle headers.

eZFile::downloadHeaders() can be used for this

Parameters

int $offset Transfer start offset
int $length Transfer length, in bytes

at line 872
public fileCopy($srcPath, $dstPath)

Copy file.

\public \static

Parameters

$srcPath
$dstPath

at line 887
public fileLinkCopy($srcPath, $dstPath, $symLink)

Create symbolic or hard link to file.

\public \static

Parameters

$srcPath
$dstPath
$symLink

at line 902
public fileMove($srcPath, $dstPath)

Move file.

\public \static

Parameters

$srcPath
$dstPath

at line 916
public move(string $dstPath)

Move file.

\public

Parameters

string $dstPath Destination path

at line 938
public mixed startCacheGeneration()

Starts cache generation for the current file.

This is done by creating a file named by the original file name, prefixed with '.generating'.

Return Value

mixed true if generation lock was granted, an integer matching the time before the current generation times out

at line 946
public endCacheGeneration($rename = true)

Ends the cache generation started by startCacheGeneration().

Parameters

$rename

at line 957
public abortCacheGeneration()

Aborts the current cache generation process.

Does so by rolling back the current transaction, which should be the .generating file lock

at line 967
public checkCacheGenerationTimeout()

Checks if the .generating file was changed, which would mean that generation timed out.

If not timed out, refreshes the timestamp so that storage won't be stolen

at line 977
public bool requiresClusterizing()

eZFS only stores data to FS and doesn't require/support clusterizing

Return Value

bool false

at line 989
public bool requiresPurge()

eZFS does not require binary purge.

Files are stored on plain FS and removed using FS functions

Return Value

bool

at line 994
public bool hasStaleCacheSupport()

Indicates if the handler supports the stalecache feature

Return Value

bool true if it does, false otherwise

at line 999
public getFileList(array $scopes = false, boolean $excludeScopes = false)

Get list of files stored in database.

Used in bin/php/clusterize.php.

Parameters

array $scopes return only files that belong to any of these scopes
boolean $excludeScopes if true, then reverse the meaning of $scopes, which is return only files that do not belong to any of the scopes listed in $scopes

at line 1004
public bool isDBFileExpired(int $expiry, int $curtime, int $ttl)

Calculates if the DB file is expired or not.

Parameters

int $expiry Time when file is to be expired, a value of -1 will disable this check.
int $curtime The current time to check against.
int $ttl Number of seconds the data can live, set to null to disable TTL.

Return Value

bool

at line 1009
public bool isLocalFileExpired(int $expiry, int $curtime, int $ttl)

Calculates if the local file is expired or not.

Parameters

int $expiry Time when file is to be expired, a value of -1 will disable this check.
int $curtime The current time to check against.
int $ttl Number of seconds the data can live, set to null to disable TTL.

Return Value

bool

at line 1017
public string applyServerUri(string $filePath)

No transformation is required since files are served from the same host

Parameters

string $filePath Example: /var/site/storage/images/example.png

Return Value

string http://static.example.com/var/site/storage/images/example.png