kernel/private/classes/clusterfilehandlers/ezdfsfilehandler.php

Show:

inherited

Classes
- \eZDFSFileHandler

Table of Contents

File containing the eZDFSFileHandler class.

Copyright: Copyright (C) 1999-2011 eZ Systems AS. All rights reserved.
License: eZ Business Use License Agreement Version 2.0
Package: kernel
Version: 4.6.0

\eZDFSFileHandler
jump to top

Package: Default

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)

Parent(s): \ezpDatabaseBasedClusterFileHandler
Since: 4.2.0

Constants

int 
                LOCAL_CACHE
                = 1

Controls whether file data from database is cached on the local filesystem.

Note: This is primarily available for debugging purposes.
: int

int 
                INFOCACHE_MAX
                = 200

Controls the maximum number of metdata entries to keep in memory for this request.

If the limit is reached the least used entries are removed.

: int

Properties

array
                 $_metaData= 'null'

Holds actual file metadata, accessed through the self::metadata magic propery. null means the metadata haven't been loaded, false that they've been loaded but the file was not found.

Use eZDFSFileHandler::loadMetaData( true ) to force reloading from DB

Default valuenullDetails

Type: array

\eZDFSFileHandlerMySQLBackend
                 $dbbackend= 'null'

static

Database backend class Provides metadata operations

Default valuenullDetails

Type: \eZDFSFileHandlerMySQLBackend

string
                 $filePath= 'null'

Path to the current file

Default valuenullDetails

Type: string

int
                 $generationStartTimestamp= 'false'

Cache generation start timestamp

When the instance generates the cached version for a file, this property holds the timestamp at which generation was started. This is used to control a possible generation timeout

Default valuefalseDetails

Type: int

array
                 $nonExistantStaleCacheHandling= 'null'

static

Holds the preferences used when stale cache is activated and no expired file is available.

This is loaded from file.ini, ClusteringSettings/NonExistantStaleCacheHandling

Default valuenullDetails

Type: array


                 $realFilePath= 'null'

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

Default valuenullDetails

Type: n/a

int
                 $remainingCacheGenerationTime= 'false'

Remaining time before cache generation times out

Default valuefalseDetails

Type: int

bool
                 $useStaleCache= 'false'

Indicates that the current cache item is being generated and an old version should be used

Default valuefalseDetails

Type: bool

Methods

__construct(
          string $filePath
              =
              false
          )
        
        :
          void

Constructor

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

Parameters

Name	Type	Description
$filePath	string	Path of the file to handle

Throws

Exception	Description
\eZDBNoConnectionException	DB connection failed

__get(
           $propertyName
          )
        
        :
          void

Magic getter

Parameters

Name	Type	Description
$propertyName

_cacheType(
          
          )
        
        :
          string

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

Returns

Type	Description
string	viewcache, cacheblock or misc

abortCacheGeneration(
          
          )
        
        :
          void

Aborts the current cache generation process.

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

checkCacheGenerationTimeout(
          
          )
        
        :
          void

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

cleanPath(
           $path
          )
        
        :
          string

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\windows\path => my/windows/path - extra//slashes/\are/fixed => extra/slashes/are/fixed - ending/slashes/ => ending/slashes

Parameters

Name	Type	Description
$path

Returns

Type	Description
string	cleaned up $path

Details

Todo: -ceZDFSFileHandler write unit test

delete(
          
          )
        
        :
          void

Deletes specified file/directory.

If a directory specified it is deleted recursively.

deleteLocal(
          
          )
        
        :
          void

Deletes a file that has been fetched before.

disconnect(
          
          )
        
        :
          void

Disconnects the cluster handler from the database

endCacheGeneration(
           $rename
              =
              true
          )
        
        :
          void

Ends the cache generation started by startCacheGeneration().

Parameters

Name	Type	Description
$rename

exists(
          bool $checkDFSFile
              =
              false
          )
        
        :
          bool

Check if given file/dir exists.

Parameters

Name	Type	Description
$checkDFSFile	bool	if true, also check on the DFS

Returns

Type	Description
bool

Details

See: \eZDFSFileHandler::fileExists()

fetch(
          bool $noLocalCache
              =
              false
          )
        
        :
          void

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

Parameters

Name	Type	Description
$noLocalCache	bool

fetchContents(
          
          )
        
        :
          string | bool

Returns file contents.

Returns

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

fetchExpiredBinaryItems(
          array $limit
              =
              array( 0 , 100 )
          )
        
        :
          \array(filepath)

Fetches the first $limit expired binary items from the DB

Parameters

Name	Type	Description
$limit	array	A 2 items array( offset, limit )

Returns

Type	Description
\array(filepath)

Details

Deprecated: Deprecated as of 4.5, use {@link eZDFSFileHandler::fetchExpiredItems()} instead.
Since: 4.3.0

fetchExpiredItems(
          array $scopes, array $limit
              =
              array( 0 , 100 ), int $expiry
              =
              false
          )
        
        :
          \array(filepath)

Fetches the first $limit expired files from the DB

Parameters

Name	Type	Description
$scopes	array	Array of scopes to fetch from
$limit	array	A 2 items array( offset, limit )
$expiry	int	Number of seconds, only items older than this will be returned

Returns

Type	Description
\array(filepath)

Details

Since: 4.5.0

fetchUnique(
          
          )
        
        :
          string

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

Returns

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

fileCopy(
           $srcPath,  $dstPath
          )
        
        :
          void

Copy file.

Parameters

Name	Type	Description
$srcPath
$dstPath

fileDelete(
          string $path, bool | string $fnamePart
              =
              false
          )
        
        :
          void

Deletes specified file/directory.

Parameters

Name	Type	Description
$path	string	the file path to delete
$fnamePart	bool \| string	If 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

Details

Todo: -ceZDFSFileHandler write unit test

fileDeleteByDirList(
          array $dirList, string $commonPath, string $commonSuffix
          )
        
        :
          void

Deletes a list of files based on directory / filename components

Parameters

Name	Type	Description
$dirList	array	Array of directory that will be prefixed with $commonPath when looking for files
$commonPath	string	Starting path common to every delete request
$commonSuffix	string	Suffix appended to every delete request

Details

Todo: -ceZDFSFileHandler write unit test

fileDeleteByRegex(
          string $dir, string $fileRegex
          )
        
        :
          void

Deletes multiple files by regex

Parameters

Name	Type	Description
$dir	string	An optional directory that will be prepended to the regex. Set to false to disable
$fileRegex	string	The regular expression applied to files

Details

Todo: -ceZDFSFileHandler write unit test

fileDeleteByWildcard(
          string $wildcard
          )
        
        :
          void

Deletes a list of files by wildcard

Parameters

Name	Type	Description
$wildcard	string	The wildcard used to look for files. Can contain and ?*

Details

Todo: -ceZDFSFileHandler write unit test

fileDeleteLocal(
           $path
          )
        
        :
          void

Deletes a file that has been fetched before.

Parameters

Name	Type	Description
$path

fileExists(
          string $path, bool $checkDFSFile
              =
              false
          )
        
        :
          bool

Check if given file/dir exists.

Parameters

Name	Type	Description
$path	string	File path to test existence for
$checkDFSFile	bool	if true, also check on the DFS

Returns

Type	Description
bool

Details

See: \eZDFSFileHandler::exists()

fileFetch(
          string $filePath
          )
        
        :
          string | false

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

Parameters

Name	Type	Description
$filePath	string

Returns

Type	Description
string \| false	the file path, or false if fetching failed

fileFetchContents(
           $filePath
          )
        
        :
          bool | string

Returns file contents.

Parameters

Name	Type	Description
$filePath

Returns

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

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

Create symbolic or hard link to file.

Parameters

Name	Type	Description
$srcPath
$dstPath
$symLink

fileMove(
           $srcPath,  $dstPath
          )
        
        :
          void

Move file.

Parameters

Name	Type	Description
$srcPath
$dstPath

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

Stores a file by path to the backend

Parameters

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

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

Store file contents.

Parameters

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

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

Get list of files stored in database.

Used in bin/php/clusterize.php.

Parameters

Name	Type	Description
$scopes	array	return only files that belong to any of these scopes
$excludeScopes	boolean	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

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

Calculates if the DB file is expired or not.

Parameters

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

Returns

Type	Description
bool

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

Calculates if the current file data is expired or not.

Parameters

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

Returns

Type	Description
bool

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

Calculates if the file data is expired or not.

Parameters

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

Returns

Type	Description
bool

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

Calculates if the local file is expired or not.

Parameters

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

Returns

Type	Description
bool

loadMetaData(
          bool $force
              =
              false
          )
        
        :
          void

Loads file meta information.

Parameters

Name	Type	Description
$force	bool	File stats will be refreshed if true

move(
          string $dstPath
          )
        
        :
          void

Move/rename file to $dstPath

Parameters

Name	Type	Description
$dstPath	string	Destination path

mtime(
          
          )
        
        :
          int | null

Returns file modification time.

Returns

Type	Description
int \| null

name(
          
          )
        
        :
          string | null

Returns file name.

Returns

Type	Description
string \| null

passthrough(
          int $startOffset
              =
              0, int $length
              =
              false
          )
        
        :
          void

Outputs file contents directly

Parameters

Name	Type	Description
$startOffset	int	Byte offset to start transfer from
$length	int	Byte length to transfer. NOT end offset, end offset = $startOffset + $length

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

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

Name	Type	Description
$retrieveCallback
$generateCallback
$ttl
$expiry
$extraData

Details

See: \$expiry
See: \$expiry
Todo: Reformat the doc so that it's readable

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

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

Name	Type	Description
$callback
$expiry
$extraData

Details

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

purge(
          callback $printCallback
              =
              false, int $microsleep
              =
              false, int $max
              =
              false, int $expiry
              =
              false
          )
        
        :
          void

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

Name	Type	Description
$printCallback	callback	Callback called after each delete iteration (@see $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)
$microsleep	int	Wait interval before each purge batch of $max items
$max	int	Maximum number of items to delete in one batch (default: 100)
$expiry	int	If specificed, only files older than this date will be purged

requiresBinaryPurge(
          
          )
        
        :
          bool

eZDFS does require binary purge.

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

Returns

Type	Description
bool

Details

Deprecated: Deprecated as of 4.5, use {@link eZDFSFileHandler::requiresPurge()} instead.
Since: 4.3

requiresClusterizing(
          
          )
        
        :
          bool

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

Returns

Type	Description
bool

requiresPurge(
          
          )
        
        :
          bool

eZDFS does require binary purge.

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

Returns

Type	Description
bool

Details

Since: 4.5.0

size(
          
          )
        
        :
          int | null

Returns file size.

Returns

Type	Description
int \| null

startCacheGeneration(
          
          )
        
        :
          bool

Starts cache generation for the current file.

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

Returns

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

Returns file metadata.

storeCache(
           $fileData
          )
        
        :
          void

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

Parameters

Name	Type	Description
$fileData

Details

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.

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

Store file contents using binary data

Parameters

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

kernel/private/classes/clusterfilehandlers/ezdfsfilehandler.php

\eZDFSFileHandlerjump to top

Constants

Properties

Methods

\eZDFSFileHandler
jump to top