eZPublish  4.4
eZDFSFileHandler Class Reference

Handles file operations for Distributed File Systems (f.e. More...

+ Inheritance diagram for eZDFSFileHandler:
+ Collaboration diagram for eZDFSFileHandler:

Public Member Functions

 __construct ($filePath=false)
 Constructor. More...
 
 __get ($propertyName)
 Magic getter. More...
 
 abortCacheGeneration ()
 Aborts the current cache generation process. More...
 
 checkCacheGenerationTimeout ()
 Checks if the .generating file was changed, which would mean that generation timed out. More...
 
 delete ()
 Deletes specified file/directory. More...
 
 deleteLocal ()
 Deletes a file that has been fetched before. More...
 
 endCacheGeneration ($rename=true)
 Ends the cache generation started by startCacheGeneration(). More...
 
 exists ()
 Check if given file/dir exists. More...
 
 fetch ($noLocalCache=false)
 Fetches file from DFS and saves it in FS under the same name. More...
 
 fetchContents ()
 Returns file contents. More...
 
 fetchExpiredBinaryItems ($limit=array(0, 100))
 Fetches the first $limit expired binary items from the DB. More...
 
 fetchUnique ()
 Fetches file from db and saves it in FS under a unique name. More...
 
 fileCopy ($srcPath, $dstPath)
 Copy file. More...
 
 fileDelete ($path, $fnamePart=false)
 Deletes specified file/directory. More...
 
 fileDeleteByDirList ($dirList, $commonPath, $commonSuffix)
 Deletes a list of files based on directory / filename components. More...
 
 fileDeleteByRegex ($dir, $fileRegex)
 Deletes multiple files by regex. More...
 
 fileDeleteByWildcard ($wildcard)
 Deletes a list of files by wildcard. More...
 
 fileDeleteLocal ($path)
 Deletes a file that has been fetched before. More...
 
 fileExists ($path)
 Check if given file/dir exists. More...
 
 fileFetch ($filePath)
 Fetches file from DFS and saves it in LFS under the same name. More...
 
 fileFetchContents ($filePath)
 Returns file contents. More...
 
 fileLinkCopy ($srcPath, $dstPath, $symLink)
 Create symbolic or hard link to file. More...
 
 fileMove ($srcPath, $dstPath)
 Move file. More...
 
 fileStore ($filePath, $scope=false, $delete=false, $datatype=false)
 Stores a file by path to the backend. More...
 
 fileStoreContents ($filePath, $contents, $scope=false, $datatype=false)
 Store file contents. More...
 
 getFileList ($scopes=false, $excludeScopes=false)
 Get list of files stored in database. More...
 
 isDBFileExpired ($expiry, $curtime, $ttl)
 Calculates if the DB file is expired or not. More...
 
 isExpired ($expiry, $curtime, $ttl)
 Calculates if the current file data is expired or not. More...
 
 isFileExpired ($fname, $mtime, $expiry, $curtime, $ttl)
 Calculates if the file data is expired or not. More...
 
 isLocalFileExpired ($expiry, $curtime, $ttl)
 Calculates if the local file is expired or not. More...
 
 loadMetaData ($force=false)
 Loads file meta information. More...
 
 move ($dstPath)
 Move/rename file to $dstPath. More...
 
 mtime ()
 Returns file modification time. More...
 
 name ()
 Returns file name. More...
 
 passthrough ()
 Outputs file contents prepending them with appropriate HTTP headers. More...
 
 processCache ($retrieveCallback, $generateCallback=null, $ttl=null, $expiry=null, $extraData=null)
 Handles cache requests / write operations. More...
 
 processFile ($callback, $expiry=false, $extraData=null)
 Provides access to the file contents by downloading the file locally and calling $callback with the local filename. More...
 
 purge ($printCallback=false, $microsleep=false, $max=false, $expiry=false)
 Purges local and remote file data for current file path. More...
 
 requiresBinaryPurge ()
 eZDFS does require binary purge. More...
 
 requiresClusterizing ()
 Since eZDFS uses the database, running clusterize.php is required. More...
 
 size ()
 Returns file size. More...
 
 startCacheGeneration ()
 Starts cache generation for the current file. More...
 
 stat ()
 Returns file metadata. More...
 
 storeCache ($fileData)
 Stores the data in $fileData to the remote and local file and commits the transaction. More...
 
 storeContents ($contents, $scope=false, $datatype=false, $storeLocally=false)
 Store file contents using binary data. More...
 

Static Public Member Functions

static cleanPath ($path)
 Returns a clean version of input $path. More...
 

Public Attributes

 $filePath = null
 
 $remainingCacheGenerationTime = false
 
const INFOCACHE_MAX = 200
 
const LOCAL_CACHE = 1
 

Protected Member Functions

 _cacheType ()
 Determines the cache type based on the current file's path. More...
 

Protected Attributes

 $_metaData = null
 
 $generationStartTimestamp = false
 

Static Protected Attributes

static $dbbackend = null
 
static $nonExistantStaleCacheHandling = null
 

Private Attributes

 $realFilePath = null
 holds the real file path. More...
 
 $useStaleCache = false
 

Detailed Description

Handles file operations for Distributed File Systems (f.e.

NFS)

Uses a dual DB / FS approach:

  • files metadata are DB based
  • files data are read/written to a local mount point (outside var/)
  • actual files are locally written, exactly like the DB handler does

Glossary of terms used in the internal doc:

  • DFS: Distributed File System. Local NFS mount point
  • DB: MetaData database
  • LFS: Local file system (var)
Since
4.2.0

Constructor & Destructor Documentation

eZDFSFileHandler::__construct (   $filePath = false)

Constructor.

If provided with $filePath, will use this file for further operations. If not given, the file* methods must be used instead

Parameters
string$filePathPath of the file to handle
Exceptions
eZDBNoConnectionExceptionDB connection failed

Member Function Documentation

eZDFSFileHandler::__get (   $propertyName)

Magic getter.

eZDFSFileHandler::_cacheType ( )
protected

Determines the cache type based on the current file's path.

Returns
string viewcache, cacheblock or misc

Referenced by __get().

eZDFSFileHandler::abortCacheGeneration ( )

Aborts the current cache generation process.

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

Implements eZClusterFileHandlerInterface.

Referenced by storeCache().

eZDFSFileHandler::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

Implements eZClusterFileHandlerInterface.

Referenced by storeCache().

static eZDFSFileHandler::cleanPath (   $path)
static

Returns a clean version of input $path.

  • Backslashes are turned into slashes.
  • Multiple consecutive slashes are turned into one slash.
  • Ending slashes are removed.

Examples:

  • my => my/windows/path
  • extra//slashes//fixed => extra/slashes/are/fixed
  • ending/slashes/ => ending/slashes
Todo:
-ceZDFSFileHandler write unit test
Returns
string cleaned up $path
eZDFSFileHandler::delete ( )

Deletes specified file/directory.

If a directory specified it is deleted recursively.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::deleteLocal ( )

Deletes a file that has been fetched before.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::endCacheGeneration (   $rename = true)

Ends the cache generation started by startCacheGeneration().

Implements eZClusterFileHandlerInterface.

Referenced by storeCache().

eZDFSFileHandler::exists ( )

Check if given file/dir exists.

See Also
eZDFSFileHandler::fileExists()
Returns
bool

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fetch (   $noLocalCache = false)

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

Parameters
bool$noLocalCache

Implements eZClusterFileHandlerInterface.

Referenced by processCache().

eZDFSFileHandler::fetchContents ( )

Returns file contents.

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

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fetchExpiredBinaryItems (   $limit = array( 0 , 100 ))

Fetches the first $limit expired binary items from the DB.

Parameters
array$limitA 2 items array( offset, limit )
Returns
array(filepath)
Since
4.3.0
eZDFSFileHandler::fetchUnique ( )

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

Returns
string filename with path of a saved file. You can use this filename to get contents of file from filesystem.

Implements eZClusterFileHandlerInterface.

Referenced by processCache().

eZDFSFileHandler::fileCopy (   $srcPath,
  $dstPath 
)

Copy file.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileDelete (   $path,
  $fnamePart = false 
)

Deletes specified file/directory.

Parameters
string$paththe file path to delete
bool | string$fnamePartIf set to true, $path is a directory and its content is deleted. If it is a string, this string is appended a wildcard and used for deletion
Returns
void
Todo:
-ceZDFSFileHandler write unit test

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileDeleteByDirList (   $dirList,
  $commonPath,
  $commonSuffix 
)

Deletes a list of files based on directory / filename components.

Parameters
array$dirListArray of directory that will be prefixed with $commonPath when looking for files
string$commonPathStarting path common to every delete request
string$commonSuffixSuffix appended to every delete request
Returns
void
Todo:
-ceZDFSFileHandler write unit test

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileDeleteByRegex (   $dir,
  $fileRegex 
)

Deletes multiple files by regex.

Parameters
string$dirAn optional directory that will be prepended to the regex. Set to false to disable
string$fileRegexThe regular expression applied to files
Returns
void
Todo:
-ceZDFSFileHandler write unit test

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileDeleteByWildcard (   $wildcard)

Deletes a list of files by wildcard.

Parameters
string$wildcardThe wildcard used to look for files. Can contain
  • and ?
Returns
void
Todo:
-ceZDFSFileHandler write unit test

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileDeleteLocal (   $path)

Deletes a file that has been fetched before.

Implements eZClusterFileHandlerInterface.

Referenced by processCache().

eZDFSFileHandler::fileExists (   $path)

Check if given file/dir exists.

Parameters
string$pathFile path to test existence for
See Also
eZDFSFileHandler::exists()
Returns
bool

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileFetch (   $filePath)

Fetches file from DFS and saves it in LFS under the same name.

Parameters
string$filePath
Returns
string|false the file path, or false if fetching failed

Implements eZClusterFileHandlerInterface.

Referenced by fetch().

eZDFSFileHandler::fileFetchContents (   $filePath)

Returns file contents.

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

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileLinkCopy (   $srcPath,
  $dstPath,
  $symLink 
)

Create symbolic or hard link to file.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileMove (   $srcPath,
  $dstPath 
)

Move file.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileStore (   $filePath,
  $scope = false,
  $delete = false,
  $datatype = false 
)

Stores a file by path to the backend.

Parameters
string$filePathPath to the file being stored.
string$scopeMeans something like "file category". May be used to clean caches of a certain type.
bool$deletetrue if the file should be deleted after storing.
string$datatype
Returns
void

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::fileStoreContents (   $filePath,
  $contents,
  $scope = false,
  $datatype = false 
)

Store file contents.

Parameters
string$filePathPath to the file being stored.
string$contentsBinary file content
string$scope"file category". May be used by cache management
string$datatypeDatatype for the file. Also used to clean cache up
Returns
void

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::getFileList (   $scopes = false,
  $excludeScopes = false 
)

Get list of files stored in database.

Used in bin/php/clusterize.php.

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

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::isDBFileExpired (   $expiry,
  $curtime,
  $ttl 
)

Calculates if the DB file is expired or not.

Parameters
int$expiryTime when file is to be expired, a value of -1 will disable this check.
int$curtimeThe current time to check against.
int$ttlNumber of seconds the data can live, set to null to disable TTL.
Returns
bool

Implements eZClusterFileHandlerInterface.

Referenced by processCache().

eZDFSFileHandler::isExpired (   $expiry,
  $curtime,
  $ttl 
)

Calculates if the current file data is expired or not.

Parameters
int$expiryTime when file is to be expired, a value of -1 will disable this check.
int$curtimeThe current time to check against.
int$ttlNumber of seconds the data can live, set to null to disable TTL.
Returns
bool

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::isFileExpired (   $fname,
  $mtime,
  $expiry,
  $curtime,
  $ttl 
)

Calculates if the file data is expired or not.

Parameters
string$fnameName of file, available for easy debugging.
int$mtimeModification time of file, can be set to false if file does not exist.
int$expiryTime when file is to be expired, a value of -1 will disable this check.
int$curtimeThe current time to check against.
int$ttlNumber of seconds the data can live, set to null to disable TTL.
Returns
bool

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::isLocalFileExpired (   $expiry,
  $curtime,
  $ttl 
)

Calculates if the local file is expired or not.

Parameters
int$expiryTime when file is to be expired, a value of -1 will disable this check.
int$curtimeThe current time to check against.
int$ttlNumber of seconds the data can live, set to null to disable TTL.
Returns
bool

Implements eZClusterFileHandlerInterface.

Referenced by processCache().

eZDFSFileHandler::loadMetaData (   $force = false)

Loads file meta information.

Parameters
bool$forceFile stats will be refreshed if true
Returns
void

Referenced by __get(), and processCache().

eZDFSFileHandler::move (   $dstPath)

Move/rename file to $dstPath.

Parameters
string$dstPathDestination path

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::mtime ( )

Returns file modification time.

Returns
int|null

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::name ( )

Returns file name.

Returns
string|null

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::passthrough ( )

Outputs file contents prepending them with appropriate HTTP headers.

Deprecated:
This function should not be used since it cannot handle reading errors.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::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 Also
    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

See Also
$expiry and
$ttl is used.
$expiry can be set to a timestamp which controls the absolute max time for the cache, after this time/date the cache will never be used. If the value is set to a negative value or null there the expiration check is disabled.

$ttl (time to live) tells how many seconds the cache can live from the time it was stored. If the value is set to negative or null there is no limit for the lifetime of the cache. A value of 0 means that the cache will always expire and practically disables caching. For the cache to be used both the $expiry and $ttl check must hold.

Todo:
Reformat the doc so that it's readable

Implements eZClusterFileHandlerInterface.

Referenced by processFile().

eZDFSFileHandler::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().

See Also
self::processCache()
Note
Unlike processCache() this returns null if the file cannot be accessed.

Implements eZClusterFileHandlerInterface.

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

Purges local and remote file data for current file path.

Can be given a file or a folder. In order to clear a folder, do NOT add a trailing / at the end of the file's path: path/to/file instead of path/to/file/.

By default, only expired files will be removed (ezdfsfile.expired = 1). If you specify an $expiry time, it will replace the expired test and only purge files older than the given expiry timestamp.

Parameters
callback$printCallbackCallback called after each delete iteration (
See Also
$max) to print out a report of the deleted files. This callback expects two parameters, $file (delete pattern used to perform deletion) and $count (number of deleted items)
Parameters
int$microsleepWait interval before each purge batch of $max items
int$maxMaximum number of items to delete in one batch (default: 100)
int$expiryIf specificed, only files older than this date will be purged
Returns
void

The loop starts without knowing how many files are to be deleted. When _purgeByLike is called, it returns the number of affected rows. If rows were affected, _purgeByLike will be called again

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::requiresBinaryPurge ( )

eZDFS does require binary purge.

It does store files in DB + on NFS, and therefore doesn't remove files in real time

Since
4.3

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::requiresClusterizing ( )

Since eZDFS uses the database, running clusterize.php is required.

Returns
bool

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::size ( )

Returns file size.

Returns
int|null

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::startCacheGeneration ( )

Starts cache generation for the current file.

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

Returns
bool false if the file is being generated, true if it is not

Implements eZClusterFileHandlerInterface.

Referenced by processCache().

eZDFSFileHandler::stat ( )

Returns file metadata.

Implements eZClusterFileHandlerInterface.

eZDFSFileHandler::storeCache (   $fileData)

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().

Note
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.

Referenced by processCache().

eZDFSFileHandler::storeContents (   $contents,
  $scope = false,
  $datatype = false,
  $storeLocally = false 
)

Store file contents using binary data.

Parameters
string$contentsBinary file content
string$scope"file category". May be used by cache management
string$datatypeDatatype for the file. Also used to clean cache up
bool$storeLocallyIf true the file will also be stored on the local file system.

Implements eZClusterFileHandlerInterface.

Referenced by storeCache().

Member Data Documentation

eZDFSFileHandler::$_metaData = null
protected

Referenced by __get().

eZDFSFileHandler::$dbbackend = null
staticprotected
eZDFSFileHandler::$generationStartTimestamp = false
protected
eZDFSFileHandler::$nonExistantStaleCacheHandling = null
staticprotected
eZDFSFileHandler::$realFilePath = null
private

holds the real file path.

This is only used when we are generating a cache file, in which case $filePath holds the generating cache file name, and $realFilePath holds the real name

Referenced by abortCacheGeneration(), and endCacheGeneration().

eZDFSFileHandler::$remainingCacheGenerationTime = false
eZDFSFileHandler::$useStaleCache = false
private
const eZDFSFileHandler::INFOCACHE_MAX = 200
const eZDFSFileHandler::LOCAL_CACHE = 1

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