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

Inheritance diagram for FileBackend:

Collaboration 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 stat 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.
	directoryExists (array $params)
	Check if a directory exists at a given storage path.
	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.
	doQuickOperation (array $op)
	Same as doQuickOperations() except it takes a single operation.
	doQuickOperations (array $ops, array $opts=array())
	Perform a set of independent file operations on some files.
	fileExists (array $params)
	Check if a file exists at a storage path in the backend.
	getContainerStoragePath ($container)
	Get the storage path for the given container for this backend.
	getDirectoryList (array $params)
	Get an iterator to list all directories under a storage directory.
	getFileContents (array $params)
	Get the contents of a file at a storage path in the backend.
	getFileContentsMulti (array $params)
	Like getFileContents() except it takes an array of storage paths and returns a map of storage paths to strings (or null on failure).
	getFileHttpUrl (array $params)
	Return an HTTP URL to a given file that requires no authentication to use.
	getFileList (array $params)
	Get an iterator to list 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.
	getJournal ()
	Get the file journal object for this backend.
	getLocalCopy (array $params)
	Get a local copy on disk of the file at a storage path in the backend.
	getLocalCopyMulti (array $params)
	Like getLocalCopy() except it takes an array of storage paths and returns a map of storage paths to TempFSFile objects (or null on failure).
	getLocalReference (array $params)
	Returns a file system file, identical to the file at a storage path.
	getLocalReferenceMulti (array $params)
	Like getLocalReference() except it takes an array of storage paths and returns a map of storage paths to FSFile objects (or null on failure).
	getName ()
	Get the unique backend name.
	getReadOnlyReason ()
	Get an explanatory message if this backend is read-only.
	getRootStoragePath ()
	Get the root storage path of this backend.
	getScopedFileLocks (array $paths, $type, Status $status)
	Lock the files at the given storage paths in the backend.
	getScopedLocksForOps (array $ops, Status $status)
	Get an array of scoped locks needed for a batch of file operations.
	getTopDirectoryList (array $params)
	Same as FileBackend::getDirectoryList() except only lists directories that are immediately under the given directory.
	getTopFileList (array $params)
	Same as FileBackend::getFileList() except only lists files that are immediately under the given directory.
	getWikiId ()
	Get the wiki identifier used for this backend (possibly empty).
	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.
	preloadCache (array $paths)
	Preload persistent file stat and property cache into in-process cache.
	prepare (array $params)
	Prepare a storage directory for usage.
	publish (array $params)
	Remove measures to block web access to a storage directory and the container it belongs to.
	quickCopy (array $params)
	Performs a single quick copy operation.
	quickCreate (array $params)
	Performs a single quick create operation.
	quickDelete (array $params)
	Performs a single quick delete operation.
	quickMove (array $params)
	Performs a single quick move operation.
	quickStore (array $params)
	Performs a single quick store operation.
	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	isPathTraversalFree ($path)
	Check if a relative path has no directory traversals.
static	isStoragePath ($path)
	Check if a given path is a "mwstore://" path.
static	makeContentDisposition ($type, $filename= '')
	Build a Content-Disposition header value per RFC 6266.
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)
	doPublish (array $params)
	doQuickOperationsInternal (array $ops)
	doSecure (array $params)
Static Protected Member Functions
static	normalizeContainerPath ($path)
	Validate and normalize a relative storage path.
Protected Attributes
	$concurrency
FileJournal	$fileJournal
	*
LockManager	$lockManager
	*
	$name
	$parallelize
	$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 "<path>" portion is a relative path that uses UNIX file system (FS) notation, though any particular backend may not actually be using a local filesystem. Therefore, the relative 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 of subclasses should avoid throwing exceptions at all costs. As a corollary, external dependencies should be kept to a minimum.

Since:: 1.19

Definition at line 59 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. It should only consist of alphanumberic, '-', and '_' characters.
lockManager : Registered name of a file lock manager to use.
fileJournal : File journal configuration; see FileJournal::factory(). Journals simply log changes to files stored in the backend.
readOnly : Write operations are disallowed if this is a non-empty string. It should be an explanation for the backend being read-only.
parallelize : When to do file operations in parallel (when possible). Allowed values are "implicit", "explicit" and "off".
concurrency : How many file operations can be done in parallel.

Parameters:

$config Array

Exceptions:

MWException

Reimplemented in SwiftFileBackend, FileBackendMultiWrite, FSFileBackend, and FileBackendStore.

Definition at line 91 of file FileBackend.php.

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 will be deleted.

Parameters:

$params

Array $params include:

dir : storage directory
recursive : recursively delete empty subdirectories first (since 1.20)
bypassReadOnly : allow writes in read-only mode (since 1.20)

Returns:: Status

Definition at line 692 of file FileBackend.php.

FileBackend::clearCache ( array $ paths = null )

Invalidate any in-process file stat 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 1023 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.

Parameters:

$params

Array Operation parameters $params include:

srcs : ordered source storage paths (e.g. chunk1, chunk2, ...)
dst : file system path to 0-byte temp file
parallelize : try to do operations in parallel when possible

Returns:: Status

Reimplemented in FileBackendMultiWrite, and FileBackendStore.

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 359 of file FileBackend.php.

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 331 of file FileBackend.php.

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 387 of file FileBackend.php.

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

Check if a directory exists at a given storage path.

Backends using key/value stores will check if the path is a virtual directory, meaning there are files under the given directory.

Storage backends with eventual consistency might return stale data.

Parameters:

$params

array $params include:

dir : storage directory

Returns:: bool|null Returns null on failure

Since:: 1.20

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

See also:: FileBackend::clean()

Reimplemented in FileBackendMultiWrite, and FileBackendStore.

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 317 of file FileBackend.php.

Referenced by LocalRepo\cleanupDeletedBatch().

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. The supported actions are:

create
store
copy
move
delete
null

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>,
         'disposition'         => <Content-Disposition header value>
     );

b) Copy a file system file into storage

     array(
         'op'                  => 'store',
         'src'                 => <file system path>,
         'dst'                 => <storage path>,
         'overwrite'           => <boolean>,
         'overwriteSame'       => <boolean>,
         'disposition'         => <Content-Disposition header value>
     )

c) Copy a file within storage

     array(
         'op'                  => 'copy',
         'src'                 => <storage path>,
         'dst'                 => <storage path>,
         'overwrite'           => <boolean>,
         'overwriteSame'       => <boolean>,
         'ignoreMissingSource' => <boolean>, # since 1.21
         'disposition'         => <Content-Disposition header value>
     )

d) Move a file within storage

     array(
         'op'                  => 'move',
         'src'                 => <storage path>,
         'dst'                 => <storage path>,
         'overwrite'           => <boolean>,
         'overwriteSame'       => <boolean>,
         'ignoreMissingSource' => <boolean>, # since 1.21
         'disposition'         => <Content-Disposition header value>
     )

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.
disposition : When supplied, the backend will add a Content-Disposition header when GETs/HEADs of the destination file are made. Backends that don't support file metadata will ignore this. See http://tools.ietf.org/html/rfc6266 (since 1.20).

$opts is an associative of boolean flags, including:

force : Operation precondition errors no longer trigger an abort. Any remaining operations are still attempted. Unexpected failures may still cause remaning operations to be aborted.
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.
nonJournaled : Don't log this operation batch in the file journal. This limits the ability of recovery scripts.
parallelize : Try to do operations in parallel when possible.
bypassReadOnly : Allow writes in read-only mode (since 1.20).
preserveCache : Don't clear the process cache before checking files. This should only be used if all entries in the process cache were added after the files were already locked (since 1.20).

Remarks:: 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 occurred 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 occurred 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 290 of file FileBackend.php.

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

See also:: FileBackend::doOperations()

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

See also:: FileBackend::prepare()

Reimplemented in FileBackendMultiWrite, and FileBackendStore.

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

See also:: FileBackend::publish()

Reimplemented in FileBackendMultiWrite, and FileBackendStore.

FileBackend::doQuickOperation ( array $ op ) [final]

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

If you are doing a batch of operations, then use that function instead.

See also:: FileBackend::doQuickOperations()

Parameters:

$op	Array Operation

Returns:: Status

Since:: 1.20

Definition at line 507 of file FileBackend.php.

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

Perform a set of independent file operations on some files.

This does no locking, nor journaling, and possibly no stat calls. Any destination files that already exist will be overwritten. This should *only* be used on non-original files, like cache files.

Supported operations and their parameters:

create
store
copy
move
delete
null

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>,
         'disposition'         => <Content-Disposition header value>
     )

b) Copy a file system file into storage

     array(
         'op'                  => 'store',
         'src'                 => <file system path>,
         'dst'                 => <storage path>,
         'disposition'         => <Content-Disposition header value>
     )

c) Copy a file within storage

     array(
         'op'                  => 'copy',
         'src'                 => <storage path>,
         'dst'                 => <storage path>,
         'ignoreMissingSource' => <boolean>, # since 1.21
         'disposition'         => <Content-Disposition header value>
     )

d) Move a file within storage

     array(
         'op'                  => 'move',
         'src'                 => <storage path>,
         'dst'                 => <storage path>,
         'ignoreMissingSource' => <boolean>, # since 1.21
         'disposition'         => <Content-Disposition header value>
     )

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.
disposition : When supplied, the backend will add a Content-Disposition header when GETs/HEADs of the destination file are made. Backends that don't support file metadata will ignore this. See http://tools.ietf.org/html/rfc6266 (since 1.20).

$opts is an associative of boolean flags, including:

bypassReadOnly : Allow writes in read-only mode (since 1.20)

Return value:: This returns a Status, which contains all warnings and fatals that occurred during the operation. The 'failCount', 'successCount', and 'success' members will reflect each operation attempted for the given files. The status will be considered "OK" as long as no fatal errors occurred.

Parameters:

$ops	Array Set of operations to execute
$opts	Array Batch operation options

Returns:: Status

Since:: 1.20

Definition at line 481 of file FileBackend.php.

Referenced by CopyFileBackend\copyFileBatch(), and SyncFileBackend\syncFileBatch().

FileBackend::doQuickOperationsInternal ( array $ ops ) [abstract, protected]

See also:: FileBackend::doQuickOperations()

Since:: 1.20

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

See also:: FileBackend::secure()

Reimplemented in FileBackendMultiWrite, and FileBackendStore.

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

Get the final extension from a storage or FS path.

Parameters:

$path string

Returns:: string

Definition at line 1190 of file FileBackend.php.

Referenced by UploadFromChunks\concatenateChunks(), SwiftFileBackend\doGetFileContentsMulti(), SwiftFileBackend\doGetLocalCopyMulti(), and FileBackendTest\testExtensionFromPath().

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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

Returns:: bool|null Returns null on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by CopyFileBackend\filesAreSame(), ForeignAPIRepo\getThumbUrlFromCache(), and SyncFileBackend\syncFileBatch().

FileBackend::getContainerStoragePath ( $ container ) [final]

Get the storage path for the given container for this backend.

Parameters:

$container string Container name

Returns:: string Storage path

Since:: 1.21

Definition at line 1103 of file FileBackend.php.

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

Get an iterator to list *all* directories under a storage directory.

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

Storage backends with eventual consistency might return stale data.

Parameters:

$params

array $params include:

dir : storage directory
topOnly : only return direct child dirs of the directory

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

Since:: 1.20

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

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

This should be avoided for potentially large files.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

Returns:: string|bool Returns false on failure

Definition at line 737 of file FileBackend.php.

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

Like getFileContents() except it takes an array of storage paths and returns a map of storage paths to strings (or null on failure).

The map keys (paths) are in the same order as the provided list of paths.

See also:: FileBackend::getFileContents()

Parameters:

$params

Array $params include:

srcs : list of source storage paths
latest : use the latest available data
parallelize : try to do operations in parallel when possible

Returns:: Array Map of (path name => string or false on failure)

Since:: 1.20

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

Return an HTTP URL to a given file that requires no authentication to use.

The URL may be pre-authenticated (via some token in the URL) and temporary. This will return null if the backend cannot make an HTTP URL for the file.

This is useful for key/value stores when using scripts that seek around large files and those scripts (and the backend) support HTTP Range headers. Otherwise, one would need to use getLocalReference(), which involves loading the entire file on to local disk.

Parameters:

$params

Array $params include:

src : source storage path

Returns:: string|null

Since:: 1.21

Reimplemented in SwiftFileBackend, FileBackendStore, and FileBackendMultiWrite.

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

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

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

Storage backends with eventual consistency might return stale data.

Parameters:

$params

array $params include:

dir : storage directory
topOnly : only return direct child files of the directory (since 1.20)

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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

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

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by CopyFileBackend\filesAreSame(), and SyncFileBackend\filesAreSame().

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

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

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

Returns:: integer|bool Returns false on failure

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by CopyFileBackend\filesAreSame(), and SyncFileBackend\filesAreSame().

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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

Returns:: Array|bool|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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

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

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

Referenced by ForeignAPIRepo\getThumbUrlFromCache().

FileBackend::getJournal ( ) [final]

Get the file journal object for this backend.

Returns:: FileJournal

Definition at line 1112 of file FileBackend.php.

Referenced by SyncFileBackend\syncBackends().

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

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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

Returns:: TempFSFile|null Returns null on failure

Definition at line 881 of file FileBackend.php.

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

Like getLocalCopy() except it takes an array of storage paths and returns a map of storage paths to TempFSFile objects (or null on failure).

The map keys (paths) are in the same order as the provided list of paths.

See also:: FileBackend::getLocalCopy()

Parameters:

$params

Array $params include:

srcs : list of source storage paths
latest : use the latest available data
parallelize : try to do operations in parallel when possible

Returns:: Array Map of (path name => TempFSFile or null on failure)

Since:: 1.20

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

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.

Parameters:

$params

Array $params include:

src : source storage path
latest : use the latest available data

Returns:: FSFile|null Returns null on failure

Definition at line 846 of file FileBackend.php.

Referenced by CopyFileBackend\copyFileBatch(), and SyncFileBackend\syncFileBatch().

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

Like getLocalReference() except it takes an array of storage paths and returns a map of storage paths to FSFile objects (or null on failure).

The map keys (paths) are in the same order as the provided list of paths.

See also:: FileBackend::getLocalReference()

Parameters:

$params

Array $params include:

srcs : list of source storage paths
latest : use the latest available data
parallelize : try to do operations in parallel when possible

Returns:: Array Map of (path name => FSFile or null on failure)

Since:: 1.20

Reimplemented in FileBackendStore, 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 125 of file FileBackend.php.

Referenced by TestFileOpPerformance\doPerfTest(), SyncFileBackend\replaceNamePaths(), and SyncFileBackend\syncFileBatch().

FileBackend::getReadOnlyReason ( ) [final]

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

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

Definition at line 154 of file FileBackend.php.

FileBackend::getRootStoragePath ( ) [final]

Get the root storage path of this backend.

All container paths are "subdirectories" of this path.

Returns:: string Storage path

Since:: 1.20

Definition at line 1092 of file FileBackend.php.

Referenced by CopyFileBackend\copyFileBatch().

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 1063 of file FileBackend.php.

Referenced by SyncFileBackend\syncFileBatch().

FileBackend::getScopedLocksForOps	(	array $	ops,
		Status $	status
	)		`[abstract]`

Get an array of scoped locks needed for a batch of file operations.

Normally, FileBackend::doOperations() handles locking, unless the 'nonLocking' param is passed in. This function is useful if you want the files to be locked for a broader scope than just when the files are changing. For example, if you need to update DB metadata, you may want to keep the files locked until finished.

See also:: FileBackend::doOperations()

Parameters:

$ops	Array List of file operations to FileBackend::doOperations()
$status	Status Status to update on lock/unlock

Returns:: Array List of ScopedFileLocks or null values

Since:: 1.20

Reimplemented in FileBackendStore, and FileBackendMultiWrite.

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

Same as FileBackend::getDirectoryList() except only lists directories that are immediately under the given directory.

Storage backends with eventual consistency might return stale data.

Parameters:

$params

array $params include:

dir : storage directory

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

Since:: 1.20

Definition at line 969 of file FileBackend.php.

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

Same as FileBackend::getFileList() except only lists files that are immediately under the given directory.

Storage backends with eventual consistency might return stale data.

Parameters:

$params

array $params include:

dir : storage directory

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

Since:: 1.20

Definition at line 1003 of file FileBackend.php.

FileBackend::getWikiId ( ) [final]

Get the wiki identifier used for this backend (possibly empty).

Note that this might *not* be in the same format as wfWikiID().

Returns:: string

Since:: 1.20

Definition at line 136 of file FileBackend.php.

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

Check if a relative path has no directory traversals.

Parameters:

$path string

Returns:: bool

Since:: 1.20

Definition at line 1202 of file FileBackend.php.

FileBackend::isReadOnly ( ) [final]

Check if this backend is read-only.

Returns:: bool

Definition at line 145 of file FileBackend.php.

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 1123 of file FileBackend.php.

Referenced by FSFile\__construct(), ForeignAPIRepo\fileExistsBatch(), UploadBase\initializePathInfo(), StreamFile\stream(), FileBackendTest\testIsStoragePath(), and wfMkdirParents().

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 1035 of file FileBackend.php.

static FileBackend::makeContentDisposition	(	$	type,
		$	filename = `''`
	)		`[static, final]`

Build a Content-Disposition header value per RFC 6266.

Parameters:

$type	string One of (attachment, inline)
$filename	string Suggested file name (should not contain slashes)

Exceptions:

MWException

Returns:: string

Since:: 1.20

Definition at line 1215 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 373 of file FileBackend.php.

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.

This uses the same traversal protection as Title::secureAndSplit().

Parameters:

$path string Storage path relative to a container

Returns:: string|null

Definition at line 1241 of file FileBackend.php.

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 1157 of file FileBackend.php.

Referenced by FileBackendTest\testNormalizeStoragePath().

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 1178 of file FileBackend.php.

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

FileBackend::preloadCache ( array $ paths )

Preload persistent file stat and property cache into in-process cache.

This should be used when stat calls will be made on a known list of a many files.

Parameters:

$paths Array Storage paths

Returns:: void

Reimplemented in FileBackendStore.

Definition at line 1014 of file FileBackend.php.

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.

The 'noAccess' and 'noListing' parameters works the same as in secure(), except they are only applied *if* the directory/container had to be created. These flags should always be set for directories that have private files.

Parameters:

$params

Array $params include:

dir : storage directory
noAccess : try to deny file access (since 1.20)
noListing : try to deny file listing (since 1.20)
bypassReadOnly : allow writes in read-only mode (since 1.20)

Returns:: Status

Definition at line 613 of file FileBackend.php.

Referenced by CopyFileBackend\copyFileBatch(), TestFileOpPerformance\doPerfTest(), ForeignAPIRepo\getThumbUrlFromCache(), and SyncFileBackend\syncFileBatch().

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

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

FS backends might remove .htaccess files whereas key/value store backends might grant container access to the storage user representing end-users in web requests. This essentially can undo the result of secure() calls.

Parameters:

$params

Array $params include:

dir : storage directory
access : try to allow file access
listing : try to allow file listing
bypassReadOnly : allow writes in read-only mode (since 1.20)

Returns:: Status

Since:: 1.20

Definition at line 668 of file FileBackend.php.

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

Performs a single quick copy operation.

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

See also:: FileBackend::doQuickOperation()

Parameters:

$params Array Operation parameters

Returns:: Status

Since:: 1.20

Definition at line 549 of file FileBackend.php.

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

Performs a single quick create operation.

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

See also:: FileBackend::doQuickOperation()

Parameters:

$params Array Operation parameters

Returns:: Status

Since:: 1.20

Definition at line 521 of file FileBackend.php.

Referenced by ForeignAPIRepo\getThumbUrlFromCache().

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

Performs a single quick delete operation.

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

See also:: FileBackend::doQuickOperation()

Parameters:

$params Array Operation parameters

Returns:: Status

Since:: 1.20

Definition at line 577 of file FileBackend.php.

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

Performs a single quick move operation.

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

See also:: FileBackend::doQuickOperation()

Parameters:

$params Array Operation parameters

Returns:: Status

Since:: 1.20

Definition at line 563 of file FileBackend.php.

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

Performs a single quick store operation.

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

See also:: FileBackend::doQuickOperation()

Parameters:

$params Array Operation parameters

Returns:: Status

Since:: 1.20

Definition at line 535 of file FileBackend.php.

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 revoke container access to the storage user representing end-users in web requests. This is not guaranteed to actually do anything.

Parameters:

$params

Array $params include:

dir : storage directory
noAccess : try to deny file access
noListing : try to deny file listing
bypassReadOnly : allow writes in read-only mode (since 1.20)

Returns:: Status

Definition at line 640 of file FileBackend.php.

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 1135 of file FileBackend.php.

Referenced by FileBackendTest\testSplitStoragePath().

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 345 of file FileBackend.php.

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

Stream the file at a storage path in the backend.

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

Parameters:

$params

Array $params include:

src : source storage path
headers : list of additional HTTP headers to send on success
latest : use the latest available data

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 1046 of file FileBackend.php.

Member Data Documentation

FileBackend::$concurrency [protected]

Definition at line 64 of file FileBackend.php.

FileJournal FileBackend::$fileJournal [protected]

*

Definition at line 67 of file FileBackend.php.

LockManager FileBackend::$lockManager [protected]

*

Definition at line 66 of file FileBackend.php.

FileBackend::$name [protected]

Definition at line 60 of file FileBackend.php.

FileBackend::$parallelize [protected]

Definition at line 63 of file FileBackend.php.

FileBackend::$readOnly [protected]

Definition at line 62 of file FileBackend.php.

FileBackend::$wikiId [protected]

Definition at line 61 of file FileBackend.php.

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

includes/filebackend/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