Base class for all file backend classes (including multi-write backends). More...

Inheritance diagram for FileBackend:

Public Member Functions
	__construct (array $config)
	Create a new backend instance from configuration.
	clean (array $params)
	Delete a storage directory if it is empty.
	clearCache (array $paths=null)
	Invalidate any in-process file existence and property cache.
	concatenate (array $params)
	Concatenate a list of storage files into a single file system file.
	copy (array $params, array $opts=array())
	Performs a single copy operation.
	create (array $params, array $opts=array())
	Performs a single create operation.
	delete (array $params, array $opts=array())
	Performs a single delete operation.
	doOperation (array $op, array $opts=array())
	Same as doOperations() except it takes a single operation.
	doOperations (array $ops, array $opts=array())
	This is the main entry point into the backend for write operations.
	fileExists (array $params)
	Check if a file exists at a storage path in the backend.
	getFileContents (array $params)
	Get the contents of a file at a storage path in the backend.
	getFileList (array $params)
	Get an iterator to list out all stored files under a storage directory.
	getFileProps (array $params)
	Get the properties of the file at a storage path in the backend.
	getFileSha1Base36 (array $params)
	Get a SHA-1 hash of the file at a storage path in the backend.
	getFileSize (array $params)
	Get the size (bytes) of a file at a storage path in the backend.
	getFileStat (array $params)
	Get quick information about a file at a storage path in the backend.
	getFileTimestamp (array $params)
	Get the last-modified timestamp of the file at a storage path.
	getLocalCopy (array $params)
	Get a local copy on disk of the file at a storage path in the backend.
	getLocalReference (array $params)
	Returns a file system file, identical to the file at a storage path.
	getName ()
	Get the unique backend name.
	getReadOnlyReason ()
	Get an explanatory message if this backend is read-only.
	getScopedFileLocks (array $paths, $type, Status $status)
	Lock the files at the given storage paths in the backend.
	isReadOnly ()
	Check if this backend is read-only.
	lockFiles (array $paths, $type)
	Lock the files at the given storage paths in the backend.
	move (array $params, array $opts=array())
	Performs a single move operation.
	prepare (array $params)
	Prepare a storage directory for usage.
	secure (array $params)
	Take measures to block web access to a storage directory and the container it belongs to.
	store (array $params, array $opts=array())
	Performs a single store operation.
	streamFile (array $params)
	Stream the file at a storage path in the backend.
	unlockFiles (array $paths, $type)
	Unlock the files at the given storage paths in the backend.
Static Public Member Functions
static	extensionFromPath ($path)
	Get the final extension from a storage or FS path.
static	isStoragePath ($path)
	Check if a given path is a "mwstore://" path.
static	normalizeStoragePath ($storagePath)
	Normalize a storage path by cleaning up directory separators.
static	parentStoragePath ($storagePath)
	Get the parent storage directory of a storage path.
static	splitStoragePath ($storagePath)
	Split a storage path into a backend name, a container name, and a relative file path.
Protected Member Functions
	doClean (array $params)
	doOperationsInternal (array $ops, array $opts)
	doPrepare (array $params)
	doSecure (array $params)
Static Protected Member Functions
static	normalizeContainerPath ($path)
	Validate and normalize a relative storage path.
Protected Attributes
	$lockManager
	$name
	$readOnly
	$wikiId

Detailed Description

Base class for all file backend classes (including multi-write backends).

This class defines the methods as abstract that subclasses must implement. Outside callers can assume that all backends will have these functions.

All "storage paths" are of the format "mwstore://backend/container/path". The paths use UNIX file system (FS) notation, though any particular backend may not actually be using a local filesystem. Therefore, the paths are only virtual.

Backend contents are stored under wiki-specific container names by default. For legacy reasons, this has no effect for the FS backend class, and per-wiki segregation must be done by setting the container paths appropriately.

FS-based backends are somewhat more restrictive due to the existence of real directory files; a regular file cannot have the same name as a directory. Other backends with virtual directories may not have this limitation. Callers should store files in such a way that no files and directories are under the same path.

Methods should avoid throwing exceptions at all costs. As a corollary, external dependencies should be kept to a minimum.

Since:: 1.19

Definition at line 40 of file FileBackend.php.

Constructor & Destructor Documentation

FileBackend::__construct ( array $ config )

Create a new backend instance from configuration.

This should only be called from within FileBackendGroup.

$config includes: 'name' : The unique name of this backend. This should consist of alphanumberic, '-', and '_' characters. This name should not be changed after use. 'wikiId' : Prefix to container names that is unique to this wiki. This should consist of alphanumberic, '-', and '_' characters. 'lockManager' : Registered name of a file lock manager to use. 'readOnly' : Write operations are disallowed if this is a non-empty string. It should be an explanation for the backend being read-only.

Parameters:

$config Array

Reimplemented in SwiftFileBackend, FileBackendMultiWrite, and FSFileBackend.

Definition at line 63 of file FileBackend.php.

References LockManagerGroup\singleton(), and wfWikiID().

Here is the call graph for this function:

Member Function Documentation

FileBackend::clean ( array $ params ) [final]

Delete a storage directory if it is empty.

Backends using key/value stores may do nothing unless the directory is that of an empty container, in which case it should be deleted.

$params include: dir : storage directory

Parameters:

$params Array

Returns:: Status

Definition at line 380 of file FileBackend.php.

References doClean(), isReadOnly(), and Status\newFatal().

Here is the call graph for this function:

FileBackend::clearCache ( array $ paths = null )

Invalidate any in-process file existence and property cache.

If $paths is given, then only the cache for those files will be cleared.

Parameters:

$paths Array Storage paths (optional)

Returns:: void

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Definition at line 561 of file FileBackend.php.

FileBackend::concatenate ( array $ params ) [abstract]

Concatenate a list of storage files into a single file system file.

The target path should refer to a file that is already locked or otherwise safe from modification from other processes. Normally, the file will be a new temp file, which should be adequate. $params include: srcs : ordered source storage paths (e.g. chunk1, chunk2, ...) dst : file system path to 0-byte temp file

Parameters:

$params Array Operation parameters

Returns:: Status

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::copy	(	array $	params,
		array $	opts = `array()`
	)		`[final]`

Performs a single copy operation.

This sets $params['op'] to 'copy' and passes it to doOperation().

See also:: FileBackend::doOperation()

Parameters:

$params	Array Operation parameters
$opts	Array Operation options

Returns:: Status

Definition at line 266 of file FileBackend.php.

References doOperation().

Referenced by FSFileBackend\doCopyInternal(), FSFileBackend\doStoreInternal(), and FSFileBackend\getLocalCopy().

Here is the call graph for this function:

Here is the caller graph for this function:

FileBackend::create	(	array $	params,
		array $	opts = `array()`
	)		`[final]`

Performs a single create operation.

This sets $params['op'] to 'create' and passes it to doOperation().

See also:: FileBackend::doOperation()

Parameters:

$params	Array Operation parameters
$opts	Array Operation options

Returns:: Status

Definition at line 236 of file FileBackend.php.

References doOperation().

Here is the call graph for this function:

FileBackend::delete	(	array $	params,
		array $	opts = `array()`
	)		`[final]`

Performs a single delete operation.

This sets $params['op'] to 'delete' and passes it to doOperation().

See also:: FileBackend::doOperation()

Parameters:

$params	Array Operation parameters
$opts	Array Operation options

Returns:: Status

Definition at line 296 of file FileBackend.php.

References doOperation().

Here is the call graph for this function:

FileBackend::doClean ( array $ params ) [abstract, protected]

See also:: FileBackend::clean()

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by clean().

Here is the caller graph for this function:

FileBackend::doOperation	(	array $	op,
		array $	opts = `array()`
	)		`[final]`

Same as doOperations() except it takes a single operation.

If you are doing a batch of operations that should either all succeed or all fail, then use that function instead.

See also:: FileBackend::doOperations()

Parameters:

$op	Array Operation
$opts	Array Operation options

Returns:: Status

Definition at line 222 of file FileBackend.php.

References doOperations().

Referenced by copy(), create(), delete(), move(), and store().

Here is the call graph for this function:

Here is the caller graph for this function:

FileBackend::doOperations	(	array $	ops,
		array $	opts = `array()`
	)		`[final]`

This is the main entry point into the backend for write operations.

Callers supply an ordered list of operations to perform as a transaction. Files will be locked, the stat cache cleared, and then the operations attempted. If any serious errors occur, all attempted operations will be rolled back.

$ops is an array of arrays. The outer array holds a list of operations. Each inner array is a set of key value pairs that specify an operation.

Supported operations and their parameters: a) Create a new file in storage with the contents of a string array( 'op' => 'create', 'dst' => <storage path>="">, 'content' => <string of="" new="" file="" contents>="">, 'overwrite' => <boolean>, 'overwriteSame' => <boolean> ) b) Copy a file system file into storage array( 'op' => 'store', 'src' => <file system="" path>="">, 'dst' => <storage path>="">, 'overwrite' => <boolean>, 'overwriteSame' => <boolean> ) c) Copy a file within storage array( 'op' => 'copy', 'src' => <storage path>="">, 'dst' => <storage path>="">, 'overwrite' => <boolean>, 'overwriteSame' => <boolean> ) d) Move a file within storage array( 'op' => 'move', 'src' => <storage path>="">, 'dst' => <storage path>="">, 'overwrite' => <boolean>, 'overwriteSame' => <boolean> ) e) Delete a file within storage array( 'op' => 'delete', 'src' => <storage path>="">, 'ignoreMissingSource' => <boolean> ) f) Do nothing (no-op) array( 'op' => 'null', )

Boolean flags for operations (operation-specific): 'ignoreMissingSource' : The operation will simply succeed and do nothing if the source file does not exist. 'overwrite' : Any destination file will be overwritten. 'overwriteSame' : An error will not be given if a file already exists at the destination that has the same contents as the new contents to be written there.

$opts is an associative of boolean flags, including: 'force' : Errors that would normally cause a rollback do not. The remaining operations are still attempted if any fail. 'nonLocking' : No locks are acquired for the operations. This can increase performance for non-critical writes. This has no effect unless the 'force' flag is set. 'allowStale' : Don't require the latest available data. This can increase performance for non-critical writes. This has no effect unless the 'force' flag is set.

Remarks on locking: File system paths given to operations should refer to files that are already locked or otherwise safe from modification from other processes. Normally these files will be new temp files, which should be adequate.

Return value: This returns a Status, which contains all warnings and fatals that occured during the operation. The 'failCount', 'successCount', and 'success' members will reflect each operation attempted. The status will be "OK" unless: a) unexpected operation errors occurred (network partitions, disk full...) b) significant operation errors occured and 'force' was not set

Parameters:

$ops	Array List of operations to execute in order
$opts	Array Batch operation options

Returns:: Status

Definition at line 195 of file FileBackend.php.

References doOperationsInternal(), isReadOnly(), and Status\newFatal().

Referenced by doOperation().

Here is the call graph for this function:

Here is the caller graph for this function:

FileBackend::doOperationsInternal	(	array $	ops,
		array $	opts
	)		`[abstract, protected]`

See also:: FileBackend::doOperations()

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by doOperations().

Here is the caller graph for this function:

FileBackend::doPrepare ( array $ params ) [abstract, protected]

See also:: FileBackend::prepare()

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by prepare(), and secure().

Here is the caller graph for this function:

FileBackend::doSecure ( array $ params ) [abstract, protected]

See also:: FileBackend::secure()

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by secure().

Here is the caller graph for this function:

static FileBackend::extensionFromPath ( $ path ) [static, final]

Get the final extension from a storage or FS path.

Parameters:

$path string

Returns:: string

Definition at line 710 of file FileBackend.php.

References $path.

Referenced by UploadFromChunks\concatenateChunks(), FSFileBackend\getLocalCopy(), SwiftFileBackend\getLocalCopy(), FileBackendTest\testExtensionFromPath(), and File\transform().

Here is the caller graph for this function:

FileBackend::fileExists ( array $ params ) [abstract]

Check if a file exists at a storage path in the backend.

This returns false if only a directory exists at the path.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: bool|null Returns null on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getFileContents ( array $ params ) [abstract]

Get the contents of a file at a storage path in the backend.

This should be avoided for potentially large files.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: string|false Returns false on failure

Reimplemented in FileBackendStore, SwiftFileBackend, and FileBackendMultiWrite.

FileBackend::getFileList ( array $ params ) [abstract]

Get an iterator to list out all stored files under a storage directory.

If the directory is of the form "mwstore://backend/container", then all files in the container should be listed. If the directory is of form "mwstore://backend/container/dir", then all files under that container directory should be listed. Results should be storage paths relative to the given directory.

Storage backends with eventual consistency might return stale data.

$params include: dir : storage path directory

Returns:: Traversable|Array|null Returns null on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getFileProps ( array $ params ) [abstract]

Get the properties of the file at a storage path in the backend.

Returns FSFile::placeholderProps() on failure.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: Array

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getFileSha1Base36 ( array $ params ) [abstract]

Get a SHA-1 hash of the file at a storage path in the backend.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: string|false Hash string or false on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getFileSize ( array $ params ) [abstract]

Get the size (bytes) of a file at a storage path in the backend.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: integer|false Returns false on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getFileStat ( array $ params ) [abstract]

Get quick information about a file at a storage path in the backend.

If the file does not exist, then this returns false. Otherwise, the result is an associative array that includes: mtime : the last-modified timestamp (TS_MW) size : the file size (bytes) Additional values may be included for internal use only.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: Array|false|null Returns null on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getFileTimestamp ( array $ params ) [abstract]

Get the last-modified timestamp of the file at a storage path.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: string|false TS_MW timestamp or false on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::getLocalCopy ( array $ params ) [abstract]

Get a local copy on disk of the file at a storage path in the backend.

The temporary copy will have the same file extension as the source. Temporary files may be purged when the file object falls out of scope.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: TempFSFile|null Returns null on failure

Reimplemented in SwiftFileBackend, FSFileBackend, and FileBackendMultiWrite.

Referenced by FileBackendStore\getLocalReference().

Here is the caller graph for this function:

FileBackend::getLocalReference ( array $ params ) [abstract]

Returns a file system file, identical to the file at a storage path.

The file returned is either: a) A local copy of the file at a storage path in the backend. The temporary copy will have the same extension as the source. b) An original of the file at a storage path in the backend. Temporary files may be purged when the file object falls out of scope.

Write operations should *never* be done on this file as some backends may do internal tracking or may be instances of FileBackendMultiWrite. In that later case, there are copies of the file that must stay in sync. Additionally, further calls to this function may return the same file.

$params include: src : source storage path latest : use the latest available data

Parameters:

$params Array

Returns:: FSFile|null Returns null on failure

Reimplemented in FileBackendStore, FSFileBackend, and FileBackendMultiWrite.

FileBackend::getName ( ) [final]

Get the unique backend name.

We may have multiple different backends of the same type. For example, we can have two Swift backends using different proxies.

Returns:: string

Definition at line 86 of file FileBackend.php.

FileBackend::getReadOnlyReason ( ) [final]

Get an explanatory message if this backend is read-only.

Returns:: string|false Returns falls if the backend is not read-only

Definition at line 104 of file FileBackend.php.

FileBackend::getScopedFileLocks	(	array $	paths,
		$	type,
		Status $	status
	)		`[final]`

Lock the files at the given storage paths in the backend.

This will either lock all the files or none (on failure). On failure, the status object will be updated with errors.

Once the return value goes out scope, the locks will be released and the status updated. Unlock fatals will not change the status "OK" value.

Parameters:

$paths	Array Storage paths
$type	integer LockManager::LOCK_* constant
$status	Status Status to update on lock/unlock

Returns:: ScopedLock|null Returns null on failure

Definition at line 601 of file FileBackend.php.

References ScopedLock\factory().

Referenced by SwiftFileBackend\addMissingMetadata(), FileBackendStore\concatenate(), FileBackendStore\doClean(), FileBackendMultiWrite\doOperationsInternal(), and FileBackendStore\doOperationsInternal().

Here is the call graph for this function:

Here is the caller graph for this function:

FileBackend::isReadOnly ( ) [final]

Check if this backend is read-only.

Returns:: bool

Definition at line 95 of file FileBackend.php.

Referenced by clean(), doOperations(), prepare(), and secure().

Here is the caller graph for this function:

static FileBackend::isStoragePath ( $ path ) [static, final]

Check if a given path is a "mwstore://" path.

This does not do any further validation or any existence checks.

Parameters:

$path string

Returns:: bool

Definition at line 612 of file FileBackend.php.

References $path.

Referenced by FSFile\__construct(), FileRepo\cleanupBatch(), FileRepo\fileExistsBatch(), UploadBase\initializePathInfo(), FileRepo\publishBatch(), FileRepo\storeBatch(), FileBackendTest\testIsStoragePath(), and wfMkdirParents().

Here is the caller graph for this function:

FileBackend::lockFiles	(	array $	paths,
		$	type
	)		`[final]`

Lock the files at the given storage paths in the backend.

This will either lock all the files or none (on failure).

Callers should consider using getScopedFileLocks() instead.

Parameters:

$paths	Array Storage paths
$type	integer LockManager::LOCK_* constant

Returns:: Status

Definition at line 573 of file FileBackend.php.

FileBackend::move	(	array $	params,
		array $	opts = `array()`
	)		`[final]`

Performs a single move operation.

This sets $params['op'] to 'move' and passes it to doOperation().

See also:: FileBackend::doOperation()

Parameters:

$params	Array Operation parameters
$opts	Array Operation options

Returns:: Status

Definition at line 281 of file FileBackend.php.

References doOperation().

Here is the call graph for this function:

static FileBackend::normalizeContainerPath ( $ path ) [static, final, protected]

Validate and normalize a relative storage path.

Null is returned if the path involves directory traversal. Traversal is insecure for FS backends and broken for others.

Parameters:

$path string Storage path relative to a container

Returns:: string|null

Definition at line 667 of file FileBackend.php.

References $path.

Referenced by normalizeStoragePath(), and FileBackendStore\resolveStoragePath().

Here is the caller graph for this function:

static FileBackend::normalizeStoragePath ( $ storagePath ) [static, final]

Normalize a storage path by cleaning up directory separators.

Returns null if the path is not of the format of a valid storage path.

Parameters:

$storagePath string

Returns:: string|null

Definition at line 646 of file FileBackend.php.

References normalizeContainerPath(), and splitStoragePath().

Referenced by FileBackendStore\getFileStat(), and FileBackendTest\testNormalizeStoragePath().

Here is the call graph for this function:

Here is the caller graph for this function:

static FileBackend::parentStoragePath ( $ storagePath ) [static, final]

Get the parent storage directory of a storage path.

This returns a path like "mwstore://backend/container", "mwstore://backend/container/...", or null if there is no parent.

Parameters:

$storagePath string

Returns:: string|null

Definition at line 698 of file FileBackend.php.

References splitStoragePath().

Referenced by NewParserTest\deleteFiles(), FileBackendTest\recursiveClean(), StoreBatchTest\tearDown(), and FileBackendTest\testParentStoragePath().

Here is the call graph for this function:

Here is the caller graph for this function:

FileBackend::prepare ( array $ params ) [final]

Prepare a storage directory for usage.

This will create any required containers and parent directories. Backends using key/value stores only need to create the container.

$params include: dir : storage directory

Parameters:

$params Array

Returns:: Status

Definition at line 326 of file FileBackend.php.

References doPrepare(), isReadOnly(), and Status\newFatal().

Here is the call graph for this function:

FileBackend::secure ( array $ params ) [final]

Take measures to block web access to a storage directory and the container it belongs to.

FS backends might add .htaccess files whereas key/value store backends might restrict container access to the auth user that represents end-users in web request. This is not guaranteed to actually do anything.

$params include: dir : storage directory noAccess : try to deny file access noListing : try to deny file listing

Parameters:

$params Array

Returns:: Status

Definition at line 353 of file FileBackend.php.

References doPrepare(), doSecure(), isReadOnly(), and Status\newFatal().

Here is the call graph for this function:

static FileBackend::splitStoragePath ( $ storagePath ) [static, final]

Split a storage path into a backend name, a container name, and a relative file path.

The relative path may be the empty string. This does not do any path normalization or traversal checks.

Parameters:

$storagePath string

Returns:: Array (backend, container, rel object) or (null, null, null)

Definition at line 624 of file FileBackend.php.

Referenced by FileBackendGroup\backendFromPath(), FileBackendStore\doClean(), FSFileBackend\doCleanInternal(), FileBackendStore\doPrepare(), FSFileBackend\doPrepareInternal(), FileBackendStore\doSecure(), FSFileBackend\doSecureInternal(), FileBackendStore\getFileList(), FSFileBackend\getFileListInternal(), normalizeStoragePath(), parentStoragePath(), FileBackendStore\resolveStoragePath(), FSFileBackend\resolveToFSPath(), and FileBackendTest\testSplitStoragePath().

Here is the caller graph for this function:

FileBackend::store	(	array $	params,
		array $	opts = `array()`
	)		`[final]`

Performs a single store operation.

This sets $params['op'] to 'store' and passes it to doOperation().

See also:: FileBackend::doOperation()

Parameters:

$params	Array Operation parameters
$opts	Array Operation options

Returns:: Status

Definition at line 251 of file FileBackend.php.

References doOperation().

Here is the call graph for this function:

FileBackend::streamFile ( array $ params ) [abstract]

Stream the file at a storage path in the backend.

If the file does not exists, a 404 error will be given. Appropriate HTTP headers (Status, Content-Type, Content-Length) must be sent if streaming began, while none should be sent otherwise. Implementations should flush the output buffer before sending data.

$params include: src : source storage path headers : additional HTTP headers to send on success latest : use the latest available data

Parameters:

$params Array

Returns:: Status

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

FileBackend::unlockFiles	(	array $	paths,
		$	type
	)		`[final]`

Unlock the files at the given storage paths in the backend.

Parameters:

$paths	Array Storage paths
$type	integer LockManager::LOCK_* constant

Returns:: Status

Definition at line 584 of file FileBackend.php.

Member Data Documentation

FileBackend::$lockManager [protected]

Definition at line 45 of file FileBackend.php.

FileBackend::$name [protected]

Definition at line 41 of file FileBackend.php.

Referenced by FileBackendMultiWrite\__construct().

FileBackend::$readOnly [protected]

Definition at line 43 of file FileBackend.php.

FileBackend::$wikiId [protected]

Definition at line 42 of file FileBackend.php.

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

includes/filerepo/backend/FileBackend.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation