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

Inherits LoggerAwareInterface.

Inherited by FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Collaboration diagram for Wikimedia\FileBackend\FileBackend:

[legend]

Public Member Functions
	__construct (array $config)
	Create a new backend instance from configuration.

	addShellboxInputFile (BoxedCommand $command, string $boxedName, array $params)
	Add a file to a Shellbox command as an input file.

	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=[])
	Performs a single copy operation.

	create (array $params, array $opts=[])
	Performs a single create operation.

	delete (array $params, array $opts=[])
	Performs a single delete operation.

	describe (array $params, array $opts=[])
	Performs a single describe operation.

	directoryExists (array $params)
	Check if a directory exists at a given storage path.

	doOperation (array $op, array $opts=[])
	Same as doOperations() except it takes a single operation.

	doOperations (array $ops, array $opts=[])
	This is the main entry point into the backend for write operations.

	doQuickOperation (array $op, array $opts=[])
	Same as doQuickOperations() except it takes a single operation.

	doQuickOperations (array $ops, array $opts=[])
	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.

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

	getFeatures ()
	Get the a bitfield of extra features supported by the backend medium.

	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 an order preserved map of storage paths to their content.

	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 content of the file at a storage path in the backend.

	getFileSha1Base36 (array $params)
	Get a SHA-1 hash of the content 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.

	getFileXAttributes (array $params)
	Get metadata about a file at a storage path in the 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 yields an order preserved-map of storage paths to temporary local file copies.

	getLocalReference (array $params)
	Returns a file system file, identical in content to the file at a storage path.

	getLocalReferenceMulti (array $params)
	Like getLocalReference() except it takes an array of storage paths and yields an order-preserved map of storage paths to temporary local file copies.

	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, StatusValue $status, $timeout=0)
	Lock the files at the given storage paths in the backend.

	getScopedLocksForOps (array $ops, StatusValue $status)
	Get an array of scoped locks needed for a batch of file operations.

	getStreamerOptions ()
	Return options for use with HTTPFileStreamer.

	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 ()
	Alias to getDomainId()

	hasFeatures ( $bitfield)
	Check if the backend medium supports a field of extra features.

	isReadOnly ()
	Check if this backend is read-only.

	lockFiles (array $paths, $type, $timeout=0)
	Lock the files at the given storage paths in the backend.

	move (array $params, array $opts=[])
	Performs a single move operation.

	preloadCache (array $paths)
	Preload persistent file stat cache and property cache into in-process cache.

	preloadFileStat (array $params)
	Preload file stat information (concurrently if possible) 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, array $opts=[])
	Performs a single quick copy operation.

	quickCreate (array $params, array $opts=[])
	Performs a single quick create operation.

	quickDelete (array $params, array $opts=[])
	Performs a single quick delete operation.

	quickDescribe (array $params, array $opts=[])
	Performs a single quick describe operation.

	quickMove (array $params, array $opts=[])
	Performs a single quick move operation.

	quickStore (array $params, array $opts=[])
	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.

	setLogger (LoggerInterface $logger)

	store (array $params, array $opts=[])
	Performs a single store operation.

	streamFile (array $params)
	Stream the content of 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, $case='lowercase')
	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	resetOutputBufferTheDefaultWay ()
	Default behavior of resetOutputBuffer().

static	splitStoragePath ( $storagePath)
	Split a storage path into a backend name, a container name, and a relative file path.

Public Attributes
const	ATTR_HEADERS = 1
	Bitfield flags for supported features.

const	ATTR_METADATA = 2

const	ATTR_UNICODE_PATHS = 4

Protected Member Functions
	doClean (array $params)

	doOperationsInternal (array $ops, array $opts)

	doPrepare (array $params)

	doPublish (array $params)

	doQuickOperationsInternal (array $ops, array $opts)

	doSecure (array $params)

	header ( $header)

	newStatus ( $message=null,... $params)
	Yields the result of the status wrapper callback on either:

	resetOutputBuffer ()

	resolveFSFileObjects (array $ops)
	Convert FSFile 'src' paths to string paths (with an 'srcRef' field set to the FSFile)

	scopedProfileSection ( $section)

	wrapStatus (StatusValue $sv)

Static Protected Member Functions
static	normalizeContainerPath ( $path)
	Validate and normalize a relative storage path.

Protected Attributes
int	$concurrency
	How many operations can be done in parallel.

string	$domainId
	Unique domain name.

LockManager	$lockManager

LoggerInterface	$logger

string	$name
	Unique backend name.

string	$parallelize
	When to do operations in parallel.

callable null	$profiler

string	$readOnly
	Read-only explanation message.

callable null	$statusWrapper

array	$streamerOptions
	Option map for use with HTTPFileStreamer.

TempFSFileFactory	$tmpFileFactory

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 "backend" portion is unique name for the application to refer to a backend, while the "container" portion is a top-level directory of the backend. 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 "domain"-specific container names by default. A domain is simply a logical umbrella for entities, such as those belonging to a certain application or portion of a website, for example. A domain can be local or global. Global (qualified) backends are achieved by configuring the "domain ID" to a constant. Global domains are simpler, but local domains can be used by choosing a domain ID based on the current context, such as which language of a website is being used.

For legacy reasons, the FSFileBackend class allows manually setting the paths of containers to ones that do not respect the "domain ID".

In key/value (object) stores, containers are the only hierarchy (the rest is emulated). 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.

In general, this class allows for callers to access storage through the same interface, without regard to the underlying storage system. However, calling code must follow certain patterns and be aware of certain things to ensure compatibility:

a) Always call prepare() on the parent directory before trying to put a file there; key/value stores only need the container to exist first, but filesystems need all the parent directories to exist first (prepare() is aware of all this)
b) Always call clean() on a directory when it might become empty to avoid empty directory buildup on filesystems; key/value stores never have empty directories, so doing this helps preserve consistency in both cases
c) Likewise, do not rely on the existence of empty directories for anything; calling directoryExists() on a path that prepare() was previously called on will return false for key/value stores if there are no files under that path
d) Never alter the resulting FSFile returned from getLocalReference(), as it could either be a copy of the source file in /tmp or the original source file itself
e) Use a file layout that results in never attempting to store files over directories or directories over files; key/value stores allow this but filesystems do not
f) Use ASCII file names (e.g. base32, IDs, hashes) to avoid Unicode issues in Windows
g) Do not assume that move operations are atomic (difficult with key/value stores)
h) Do not assume that file stat or read operations always have immediate consistency; various methods have a "latest" flag that should always be used if up-to-date information is required (this trades performance for correctness as needed)
i) Do not assume that directory listings have immediate consistency

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

See the architecture doc for more information.

Stability: stable: to extend

Since: 1.19

Definition at line 112 of file FileBackend.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\FileBackend\FileBackend::__construct ( array $config )

Create a new backend instance from configuration.

This should only be called from within FileBackendGroup.

Stability: stable: to call

Parameters

array

$config

Parameters include:

name : The unique name of this backend. This should consist of alphanumberic, '-', and '_' characters. This name should not be changed after use. Note that the name is not used in actual container names.
domainId : Prefix to container names that is unique to this backend. It should only consist of alphanumberic, '-', and '_' characters. This ID is what avoids collisions if multiple logical backends use the same storage system, so this should be set carefully.
lockManager : LockManager object to use for any file locking. If not provided, then no file locking will be enforced.
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.
tmpDirectory : Directory to use for temporary files.
tmpFileFactory : Optional TempFSFileFactory object. Only has an effect if tmpDirectory is not set. If both are unset or null, then the backend will try to discover a usable temporary directory.
obResetFunc : alternative callback to clear the output buffer
streamMimeFunc : alternative method to determine the content type from the path
headerFunc : alternative callback for sending response headers
logger : Optional PSR logger object.
profiler : Optional callback that takes a section name argument and returns a ScopedCallback instance that ends the profile section in its destructor.
statusWrapper : Optional callback that is used to wrap returned StatusValues

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, Wikimedia\FileBackend\FileBackendStore, Wikimedia\FileBackend\FSFileBackend, and Wikimedia\FileBackend\SwiftFileBackend.

Definition at line 208 of file FileBackend.php.

Member Function Documentation

◆ addShellboxInputFile()

Wikimedia\FileBackend\FileBackend::addShellboxInputFile	(	BoxedCommand	$command,
		string	$boxedName,
		array	$params )

abstract

Add a file to a Shellbox command as an input file.

Parameters

BoxedCommand	$command
string	$boxedName
array	$params	Parameters include: src : source storage path latest : use the latest available data

Returns: StatusValue

Since: 1.43

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, Wikimedia\FileBackend\FileBackendStore, Wikimedia\FileBackend\FSFileBackend, and Wikimedia\FileBackend\SwiftFileBackend.

◆ clean()

Wikimedia\FileBackend\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

array

$params

Parameters include:

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

Returns: StatusValue

Definition at line 990 of file FileBackend.php.

References $params, Wikimedia\FileBackend\FileBackend\doClean(), Wikimedia\FileBackend\FileBackend\isReadOnly(), and Wikimedia\FileBackend\FileBackend\newStatus().

◆ clearCache()

Wikimedia\FileBackend\FileBackend::clearCache ( ?array $paths = null )

abstract

Invalidate any in-process file stat and property cache.

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

See also: FileBackend::getFileStat()

Parameters

array | null $paths Storage paths (optional)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by CopyFileBackend\copyFileBatch().

◆ concatenate()

Wikimedia\FileBackend\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

array

$params

Operation parameters, 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: StatusValue

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ copy()

Wikimedia\FileBackend\FileBackend::copy	(	array	$params,
		array	$opts = [] )

final

Performs a single copy operation.

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

See also: FileBackend::doOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Definition at line 571 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperation().

Referenced by Wikimedia\FileBackend\FSFileBackend\doGetLocalCopyMulti().

◆ create()

Wikimedia\FileBackend\FileBackend::create	(	array	$params,
		array	$opts = [] )

final

Performs a single create operation.

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

See also: FileBackend::doOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Definition at line 543 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperation().

◆ delete()

Wikimedia\FileBackend\FileBackend::delete	(	array	$params,
		array	$opts = [] )

final

Performs a single delete operation.

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

See also: FileBackend::doOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Definition at line 599 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperation().

◆ describe()

Wikimedia\FileBackend\FileBackend::describe	(	array	$params,
		array	$opts = [] )

final

Performs a single describe operation.

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

See also: FileBackend::doOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.21

Definition at line 614 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperation().

◆ directoryExists()

Wikimedia\FileBackend\FileBackend::directoryExists ( array $params )

abstract

Check if a directory exists at a given storage path.

For backends using key/value stores, a directory is said to exist whenever there exist any files with paths using the given directory path as a prefix followed by a forward slash. For example, if there is a file called "mwstore://backend/container/dir/path.svg" then directories are said to exist at "mwstore://backend/container" and "mwstore://backend/container/dir". These can be thought of as "virtual" directories.

Backends that directly use a filesystem layer might enumerate empty directories. The clean() method should always be used when files are deleted or moved if this is a concern. This is a trade-off to avoid write amplication/contention on file changes or read amplification when calling this method.

Storage backends with eventual consistency might return stale data.

See also: FileBackend::EXISTENCE_ERROR; FileBackend::clean()

Parameters

array

$params

Parameters include:

dir : storage directory

Returns: bool|null Whether a directory exists or null (I/O error)

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ doClean()

Wikimedia\FileBackend\FileBackend::doClean ( array $params )

abstractprotected

See also: FileBackend::clean()

Parameters

array $params

Returns: StatusValue

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\clean().

◆ doOperation()

Wikimedia\FileBackend\FileBackend::doOperation	(	array	$op,
		array	$opts = [] )

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

array	$op	Operation
array	$opts	Operation options

Returns: StatusValue

Definition at line 529 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperations().

Referenced by LocalRepo\cleanupDeletedBatch(), Wikimedia\FileBackend\FileBackend\copy(), Wikimedia\FileBackend\FileBackend\create(), Wikimedia\FileBackend\FileBackend\delete(), Wikimedia\FileBackend\FileBackend\describe(), Wikimedia\FileBackend\FileBackend\move(), and Wikimedia\FileBackend\FileBackend\store().

◆ doOperations()

Wikimedia\FileBackend\FileBackend::doOperations	(	array	$ops,
		array	$opts = [] )

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
describe (since 1.21)
null

FSFile/TempFSFile object support was added in 1.27.

a) Create a new file in storage with the contents of a string

[
    'op'                  => 'create',
    'dst'                 => <storage path>,
    'content'             => <string of new file contents>,
    'overwrite'           => <boolean>,
    'overwriteSame'       => <boolean>,
    'headers'             => <HTTP header name/value map> # since 1.21
]

b) Copy a file system file into storage

[
    'op'                  => 'store',
    'src'                 => <file system path, FSFile, or TempFSFile>,
    'dst'                 => <storage path>,
    'overwrite'           => <boolean>,
    'overwriteSame'       => <boolean>,
    'headers'             => <HTTP header name/value map> # since 1.21
]

c) Copy a file within storage

[
    'op'                  => 'copy',
    'src'                 => <storage path>,
    'dst'                 => <storage path>,
    'overwrite'           => <boolean>,
    'overwriteSame'       => <boolean>,
    'ignoreMissingSource' => <boolean>, # since 1.21
    'headers'             => <HTTP header name/value map> # since 1.21
]

d) Move a file within storage

[
    'op'                  => 'move',
    'src'                 => <storage path>,
    'dst'                 => <storage path>,
    'overwrite'           => <boolean>,
    'overwriteSame'       => <boolean>,
    'ignoreMissingSource' => <boolean>, # since 1.21
    'headers'             => <HTTP header name/value map> # since 1.21
]

e) Delete a file within storage

[
    'op'                  => 'delete',
    'src'                 => <storage path>,
    'ignoreMissingSource' => <boolean>
]

f) Update metadata for a file within storage

[
    'op'                  => 'describe',
    'src'                 => <storage path>,
    'headers'             => <HTTP header name/value map>
]

g) Do nothing (no-op)

[
    '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 : If a file already exists at the destination with the same contents, then do nothing to the destination file instead of giving an error. This does not compare headers. This option is ignored if 'overwrite' is already provided.
headers : If supplied, the result of merging these headers with any existing source file headers (replacing conflicting ones) will be set as the destination file headers. Headers are deleted if their value is set to the empty string. When a file has headers they are included in responses to GET and HEAD requests to the backing store for that file. Header values should be no larger than 255 bytes, except for Content-Disposition. The system might ignore or truncate any headers that are too long to store (exact limits will vary). Backends that don't support metadata ignore this. (since 1.21)

$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 remaining 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.
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)

Note: 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 StatusValue will be "OK" unless:

a) unexpected operation errors occurred (network partitions, disk full...)
b) predicted operation errors occurred and 'force' was not set

Parameters

array[]	$ops	List of operations to execute in order
array	$opts	Batch operation options @phpcs:ignore Generic.Files.LineLength

Returns: StatusValue

Definition at line 491 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperationsInternal(), Wikimedia\FileBackend\FileBackend\isReadOnly(), Wikimedia\FileBackend\FileBackend\newStatus(), and Wikimedia\FileBackend\FileBackend\resolveFSFileObjects().

Referenced by Wikimedia\FileBackend\FileBackend\doOperation(), and MigrateFileRepoLayout\runBatch().

◆ doOperationsInternal()

Wikimedia\FileBackend\FileBackend::doOperationsInternal	(	array	$ops,
		array	$opts )

abstractprotected

See also: FileBackend::doOperations()

Parameters

array	$ops
array	$opts

Returns: StatusValue

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\doOperations().

◆ doPrepare()

Wikimedia\FileBackend\FileBackend::doPrepare ( array $params )

abstractprotected

See also: FileBackend::prepare()

Parameters

array $params

Returns: StatusValue Good status without value for success, fatal otherwise.

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\prepare().

◆ doPublish()

Wikimedia\FileBackend\FileBackend::doPublish ( array $params )

abstractprotected

See also: FileBackend::publish()

Parameters

array $params

Returns: StatusValue

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\publish().

◆ doQuickOperation()

Wikimedia\FileBackend\FileBackend::doQuickOperation	(	array	$op,
		array	$opts = [] )

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

array	$op	Operation
array	$opts	Batch operation options

Returns: StatusValue

Since: 1.20

Definition at line 771 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperations().

Referenced by Wikimedia\FileBackend\FileBackend\quickCopy(), Wikimedia\FileBackend\FileBackend\quickCreate(), Wikimedia\FileBackend\FileBackend\quickDelete(), Wikimedia\FileBackend\FileBackend\quickDescribe(), Wikimedia\FileBackend\FileBackend\quickMove(), and Wikimedia\FileBackend\FileBackend\quickStore().

◆ doQuickOperations()

Wikimedia\FileBackend\FileBackend::doQuickOperations	(	array	$ops,
		array	$opts = [] )

final

Perform a set of independent file operations on some files.

This does no locking, 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
describe (since 1.21)
null

FSFile/TempFSFile object support was added in 1.27.

a) Create a new file in storage with the contents of a string

[
    'op'                  => 'create',
    'dst'                 => <storage path>,
    'content'             => <string of new file contents>,
    'headers'             => <HTTP header name/value map> # since 1.21
]

b) Copy a file system file into storage

[
    'op'                  => 'store',
    'src'                 => <file system path, FSFile, or TempFSFile>,
    'dst'                 => <storage path>,
    'headers'             => <HTTP header name/value map> # since 1.21
]

c) Copy a file within storage

[
    'op'                  => 'copy',
    'src'                 => <storage path>,
    'dst'                 => <storage path>,
    'ignoreMissingSource' => <boolean>, # since 1.21
    'headers'             => <HTTP header name/value map> # since 1.21
]

d) Move a file within storage

[
    'op'                  => 'move',
    'src'                 => <storage path>,
    'dst'                 => <storage path>,
    'ignoreMissingSource' => <boolean>, # since 1.21
    'headers'             => <HTTP header name/value map> # since 1.21
]

e) Delete a file within storage

[
    'op'                  => 'delete',
    'src'                 => <storage path>,
    'ignoreMissingSource' => <boolean>
]

f) Update metadata for a file within storage

[
    'op'                  => 'describe',
    'src'                 => <storage path>,
    'headers'             => <HTTP header name/value map>
]

g) Do nothing (no-op)

[
    'op'                  => 'null',
]

Boolean flags for operations (operation-specific):

ignoreMissingSource : The operation will simply succeed and do nothing if the source file does not exist.
headers : If supplied with a header name/value map, the backend will reply with these headers when GETs/HEADs of the destination file are made. Header values should be smaller than 256 bytes. Content-Disposition headers can be longer, though the system might ignore or truncate ones that are too long to store. Existing headers will remain, but these will replace any conflicting previous headers, and headers will be removed if they are set to an empty string. Backends that don't support metadata ignore this. (since 1.21)

$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 StatusValue will be considered "OK" as long as no fatal errors occurred.

Parameters

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

Returns: StatusValue

Since: 1.20

Definition at line 732 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperationsInternal(), Wikimedia\FileBackend\FileBackend\isReadOnly(), Wikimedia\FileBackend\FileBackend\newStatus(), and Wikimedia\FileBackend\FileBackend\resolveFSFileObjects().

Referenced by CopyFileBackend\copyFileBatch(), CopyFileBackend\delFileBatch(), and Wikimedia\FileBackend\FileBackend\doQuickOperation().

◆ doQuickOperationsInternal()

Wikimedia\FileBackend\FileBackend::doQuickOperationsInternal	(	array	$ops,
		array	$opts )

abstractprotected

See also: FileBackend::doQuickOperations()

Parameters

array	$ops
array	$opts

Returns: StatusValue

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\doQuickOperations().

◆ doSecure()

Wikimedia\FileBackend\FileBackend::doSecure ( array $params )

abstractprotected

See also: FileBackend::secure()

Parameters

array $params

Returns: StatusValue

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\secure().

◆ extensionFromPath()

static Wikimedia\FileBackend\FileBackend::extensionFromPath	(		$path,
			$case = 'lowercase' )

staticfinal

Get the final extension from a storage or FS path.

Parameters

string	$path
string	$case	One of (rawcase, uppercase, lowercase) (since 1.24)

Returns: string

Definition at line 1632 of file FileBackend.php.

References $path.

Referenced by Wikimedia\FileBackend\FSFileBackend\doGetLocalCopyMulti(), Wikimedia\FileBackend\MemoryFileBackend\doGetLocalCopyMulti(), Wikimedia\FileBackend\SwiftFileBackend\doGetLocalCopyMulti(), and MediaWiki\FileBackend\FileBackendGroup\guessMimeInternal().

◆ fileExists()

Wikimedia\FileBackend\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.

Callers that only care if a file is readily accessible can use non-strict comparisons on the result. If "does not exist" and "existence is unknown" must be distinguished, then strict comparisons to true/null should be used.

See also: FileBackend::EXISTENCE_ERROR; FileBackend::directoryExists()

Parameters

array

$params

Parameters include:

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

Returns: bool|null Whether the file exists or null (I/O error)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by CopyFileBackend\copyFileBatch(), and ForeignAPIRepo\getThumbUrlFromCache().

◆ getContainerStoragePath()

Wikimedia\FileBackend\FileBackend::getContainerStoragePath ( $container )

final

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

Parameters

string $container Container name

Returns: string Storage path

Since: 1.21

Definition at line 1525 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\getRootStoragePath().

◆ getDirectoryList()

Wikimedia\FileBackend\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.

Failures during iteration can result in FileBackendError exceptions (since 1.22).

See also: FileBackend::LIST_ERROR; FileBackend::directoryExists()

Parameters

array

$params

Parameters include:

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

Returns: \Traversable|array|null Directory list enumerator or null (initial I/O error)

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\getTopDirectoryList().

◆ getDomainId()

Wikimedia\FileBackend\FileBackend::getDomainId ( )

final

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

Returns: string

Since: 1.28

Definition at line 287 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\$domainId.

Referenced by FileBackendDBRepoWrapper\__construct(), CopyFileBackend\copyFileBatch(), CopyFileBackend\delFileBatch(), and Wikimedia\FileBackend\FileBackend\getWikiId().

◆ getFeatures()

Wikimedia\FileBackend\FileBackend::getFeatures ( )

Get the a bitfield of extra features supported by the backend medium.

Stability: stable: to override

Returns: int Bitfield of FileBackend::ATTR_* flags

Since: 1.23

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, Wikimedia\FileBackend\FSFileBackend, Wikimedia\FileBackend\MemoryFileBackend, and Wikimedia\FileBackend\SwiftFileBackend.

Definition at line 327 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\ATTR_UNICODE_PATHS.

Referenced by Wikimedia\FileBackend\FileBackend\hasFeatures().

◆ getFileContents()

Wikimedia\FileBackend\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.

See also: FileBackend::CONTENT_FAIL

Parameters

array

$params

Parameters include:

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

Returns: string|false Content string or false (missing file or I/O error)

Definition at line 1047 of file FileBackend.php.

References $params, and Wikimedia\FileBackend\FileBackend\getFileContentsMulti().

◆ getFileContentsMulti()

Wikimedia\FileBackend\FileBackend::getFileContentsMulti ( array $params )

abstract

Like getFileContents() except it takes an array of storage paths and returns an order preserved map of storage paths to their content.

See also: FileBackend::getFileContents()

Parameters

array

$params

Parameters include:

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

Returns: string[]|false[] Map of (path name => file content or false on failure)

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\getFileContents().

◆ getFileHttpUrl()

Wikimedia\FileBackend\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.

See also: FileBackend::TEMPURL_ERROR

Parameters

array

$params

Parameters include:

src : source storage path
ttl : lifetime (seconds) if pre-authenticated; default is 1 day
latest : use the latest available data
method : the allowed method; default GET
ipRange : the allowed IP range; default unlimited

Returns: string|null URL or null (not supported or I/O error)

Since: 1.21

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, Wikimedia\FileBackend\FileBackendStore, and Wikimedia\FileBackend\SwiftFileBackend.

◆ getFileList()

Wikimedia\FileBackend\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.

Failures during iteration can result in FileBackendError exceptions (since 1.22).

See also: FileBackend::LIST_ERROR

Parameters

array

$params

Parameters include:

dir : storage directory
topOnly : only return direct child files of the directory (since 1.20)
adviseStat : set to true if stat requests will be made on the files (since 1.22)
forWrite : true if the list will inform a write operations (since 1.41)

Returns: \Traversable|array|null File list enumerator or null (initial I/O error)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by CopyFileBackend\getListingDiffRel(), and Wikimedia\FileBackend\FileBackend\getTopFileList().

◆ getFileProps()

Wikimedia\FileBackend\FileBackend::getFileProps ( array $params )

abstract

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

This gives the result of FSFile::getProps() on a local copy of the file.

Parameters

array

$params

Parameters include:

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

Returns: array Properties map; FSFile::placeholderProps() if file missing or on I/O error

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ getFileSha1Base36()

Wikimedia\FileBackend\FileBackend::getFileSha1Base36 ( array $params )

abstract

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

See also: FileBackend::SHA1_FAIL

Parameters

array

$params

Parameters include:

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

Returns: string|false Hash string or false (missing file or I/O error)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by CopyFileBackend\filesAreSame().

◆ getFileSize()

Wikimedia\FileBackend\FileBackend::getFileSize ( array $params )

abstract

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

See also: FileBackend::SIZE_FAIL

Parameters

array

$params

Parameters include:

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

Returns: int|false File size in bytes or false (missing file or I/O error)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ getFileStat()

Wikimedia\FileBackend\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.

See also: FileBackend::STAT_ABSENT; FileBackend::STAT_ERROR

Parameters

array

$params

Parameters include:

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

Returns: array|false|null Attribute map, false (missing file), or null (I/O error)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by CopyFileBackend\filesAreSame().

◆ getFileTimestamp()

Wikimedia\FileBackend\FileBackend::getFileTimestamp ( array $params )

abstract

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

See also: FileBackend::TIMESTAMP_FAIL

Parameters

array

$params

Parameters include:

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

Returns: string|false TS_MW timestamp or false (missing file or I/O error)

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by ForeignAPIRepo\getThumbUrlFromCache().

◆ getFileXAttributes()

Wikimedia\FileBackend\FileBackend::getFileXAttributes ( array $params )

abstract

Get metadata 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:

headers : map of HTTP headers used for GET/HEAD requests (name => value)
metadata : map of file metadata (name => value) Metadata keys and headers names will be returned in all lower-case. Additional values may be included for internal use only.

Use FileBackend::hasFeatures() to check how well this is supported.

See also: FileBackend::XATTRS_FAIL

Parameters

array

$params

$params include:

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

Returns: array|false File metadata array or false (missing file or I/O error)

Since: 1.23

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ getLocalCopy()

Wikimedia\FileBackend\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.

Multiple calls to this method for the same path will create new copies.

Parameters

array

$params

Parameters include:

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

Returns: TempFSFile|null|false Temporary local file copy or false (missing) or null (error)

Definition at line 1219 of file FileBackend.php.

References $params, and Wikimedia\FileBackend\FileBackend\getLocalCopyMulti().

Referenced by Wikimedia\FileBackend\SwiftFileBackend\addMissingHashMetadata().

◆ getLocalCopyMulti()

Wikimedia\FileBackend\FileBackend::getLocalCopyMulti ( array $params )

abstract

Like getLocalCopy() except it takes an array of storage paths and yields an order preserved-map of storage paths to temporary local file copies.

Multiple calls to this method for the same path will create new copies.

See also: FileBackend::getLocalCopy()

Parameters

array

$params

Parameters 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 false (missing) or null (error))

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by Wikimedia\FileBackend\FileBackend\getLocalCopy().

◆ getLocalReference()

Wikimedia\FileBackend\FileBackend::getLocalReference ( array $params )

final

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

The file returned is either:

a) A TempFSFile local copy of the file at a storage path in the backend. The temporary copy will have the same extension as the source. Temporary files may be purged when the file object falls out of scope.
b) An FSFile pointing to the original file at a storage path in the backend. This is applicable for backends layered directly on top of file systems.

Never modify the returned file since it might be the original, it might be shared among multiple callers of this method, or the backend might internally keep FSFile references for deferred operations.

Parameters

array

$params

Parameters include:

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

Returns: FSFile|null|false Local file copy or false (missing) or null (error)

Definition at line 1182 of file FileBackend.php.

References $params, and Wikimedia\FileBackend\FileBackend\getLocalReferenceMulti().

Referenced by Wikimedia\FileBackend\FileBackendStore\addShellboxInputFile(), CopyFileBackend\copyFileBatch(), Wikimedia\FileBackend\FileBackendStore\doConcatenate(), Wikimedia\FileBackend\FileBackendStore\doGetFileSha1Base36(), Wikimedia\FileBackend\FileBackendStore\doStreamFile(), and Wikimedia\FileBackend\FileBackendStore\getFileProps().

◆ getLocalReferenceMulti()

Wikimedia\FileBackend\FileBackend::getLocalReferenceMulti ( array $params )

abstract

Like getLocalReference() except it takes an array of storage paths and yields an order-preserved map of storage paths to temporary local file copies.

Never modify the returned files since they might be originals, they might be shared among multiple callers of this method, or the backend might internally keep FSFile references for deferred operations.

See also: FileBackend::getLocalReference()

Parameters

array

$params

Parameters 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 false (missing) or null (error))

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

Referenced by CopyFileBackend\copyFileBatch(), and Wikimedia\FileBackend\FileBackend\getLocalReference().

◆ getName()

Wikimedia\FileBackend\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 277 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\$name.

Referenced by FileBackendDBRepoWrapper\__construct(), FileOpPerfTest\doPerfTest(), and Wikimedia\FileBackend\FileBackendMultiWrite\unsubstPaths().

◆ getReadOnlyReason()

Wikimedia\FileBackend\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 316 of file FileBackend.php.

◆ getRootStoragePath()

Wikimedia\FileBackend\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 1514 of file FileBackend.php.

Referenced by CopyFileBackend\copyFileBatch(), CopyFileBackend\delFileBatch(), Wikimedia\FileBackend\FileBackend\getContainerStoragePath(), and CopyFileBackend\getListingDiffRel().

◆ getScopedFileLocks()

Wikimedia\FileBackend\FileBackend::getScopedFileLocks	(	array	$paths,
			$type,
		StatusValue	$status,
			$timeout = 0 )

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 StatusValue object will be updated with errors.

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

See also: ScopedLock::factory()

Parameters

array	$paths	List of storage paths or map of lock types to path lists
int \| string	$type	LockManager::LOCK_* constant or "mixed"
StatusValue	$status	StatusValue to update on lock/unlock
int	$timeout	Timeout in seconds (0 means non-blocking) (since 1.24)

Returns: ScopedLock|null RAII-style self-unlocking lock or null on failure

Definition at line 1475 of file FileBackend.php.

References ScopedLock\factory().

Referenced by Wikimedia\FileBackend\SwiftFileBackend\addMissingHashMetadata(), Wikimedia\FileBackend\FileBackendStore\concatenate(), Wikimedia\FileBackend\FileBackendStore\doClean(), Wikimedia\FileBackend\FileBackendStore\doOperationsInternal(), Wikimedia\FileBackend\FileBackendMultiWrite\getScopedLocksForOps(), and Wikimedia\FileBackend\FileBackendStore\getScopedLocksForOps().

◆ getScopedLocksForOps()

Wikimedia\FileBackend\FileBackend::getScopedLocksForOps	(	array	$ops,
		StatusValue	$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

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

Returns: ScopedLock|null RAII-style self-unlocking lock or null on failure

Since: 1.20

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ getStreamerOptions()

Wikimedia\FileBackend\FileBackend::getStreamerOptions ( )

Return options for use with HTTPFileStreamer.

Access: internal

Definition at line 1775 of file FileBackend.php.

◆ getTopDirectoryList()

Wikimedia\FileBackend\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.

Failures during iteration can result in FileBackendError exceptions (since 1.22).

See also: FileBackend::LIST_ERROR; FileBackend::directoryExists()

Parameters

array

$params

Parameters include:

dir : storage directory

Returns: \Traversable|array|null Directory list enumerator or null (initial I/O error)

Since: 1.20

Definition at line 1346 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\getDirectoryList().

Referenced by Wikimedia\FileBackend\FileBackendStore\doClean().

◆ getTopFileList()

Wikimedia\FileBackend\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.

Failures during iteration can result in FileBackendError exceptions (since 1.22).

See also: FileBackend::LIST_ERROR

Parameters

array

$params

Parameters include:

dir : storage directory
adviseStat : set to true if stat requests will be made on the files (since 1.22)

Returns: \Traversable|array|null File list enumerator or null on failure

Since: 1.20

Definition at line 1389 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\getFileList().

◆ getWikiId()

Wikimedia\FileBackend\FileBackend::getWikiId ( )

final

Alias to getDomainId()

Returns: string

Since: 1.20

Deprecated: Since 1.34 Use getDomainId()

Definition at line 298 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\getDomainId().

◆ hasFeatures()

Wikimedia\FileBackend\FileBackend::hasFeatures ( $bitfield )

final

Check if the backend medium supports a field of extra features.

Parameters

int $bitfield Bitfield of FileBackend::ATTR_* flags

Returns: bool

Since: 1.23

Definition at line 338 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\getFeatures().

◆ header()

Wikimedia\FileBackend\FileBackend::header ( $header )

protected

Definition at line 256 of file FileBackend.php.

References $header.

Referenced by Wikimedia\FileBackend\SwiftFileBackend\doStreamFile().

◆ isPathTraversalFree()

static Wikimedia\FileBackend\FileBackend::isPathTraversalFree ( $path )

staticfinal

Check if a relative path has no directory traversals.

Parameters

string $path

Returns: bool

Since: 1.20

Definition at line 1654 of file FileBackend.php.

References $path.

◆ isReadOnly()

Wikimedia\FileBackend\FileBackend::isReadOnly ( )

final

Check if this backend is read-only.

Returns: bool

Definition at line 307 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackend\clean(), Wikimedia\FileBackend\FileBackend\doOperations(), Wikimedia\FileBackend\FileBackend\doQuickOperations(), Wikimedia\FileBackend\FileBackend\prepare(), Wikimedia\FileBackend\FileBackend\publish(), and Wikimedia\FileBackend\FileBackend\secure().

◆ isStoragePath()

static Wikimedia\FileBackend\FileBackend::isStoragePath ( $path )

staticfinal

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

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

Parameters

string | null $path

Returns: bool

Definition at line 1558 of file FileBackend.php.

References $path.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\normalizeIfValidStoragePath(), and MediaWiki\Output\StreamFile\stream().

◆ lockFiles()

Wikimedia\FileBackend\FileBackend::lockFiles	(	array	$paths,
			$type,
			$timeout = 0 )

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

array	$paths	Storage paths
int	$type	LockManager::LOCK_* constant
int	$timeout	Timeout in seconds (0 means non-blocking) (since 1.24)

Returns: StatusValue

Definition at line 1440 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\wrapStatus().

◆ makeContentDisposition()

static Wikimedia\FileBackend\FileBackend::makeContentDisposition	(		$type,
			$filename = '' )

staticfinal

Build a Content-Disposition header value per RFC 6266.

Parameters

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

Returns: string

Since: 1.20

Definition at line 1666 of file FileBackend.php.

◆ move()

Wikimedia\FileBackend\FileBackend::move	(	array	$params,
		array	$opts = [] )

final

Performs a single move operation.

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

See also: FileBackend::doOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Definition at line 585 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperation().

◆ newStatus()

Wikimedia\FileBackend\FileBackend::newStatus	(		$message = null,
			$params )

finalprotected

Yields the result of the status wrapper callback on either:

StatusValue::newGood(), if this method is called without a message
StatusValue::newFatal( ... ) with all parameters to this method, if a message was given

Parameters

null \| string	$message	Message key @phpcs:ignore Generic.Files.LineLength
	MessageParam\|MessageSpecifier\|string\|int\|float\|list<MessageParam\|MessageSpecifier\|string\|int\|float>	...$params See Message::params()

Returns: StatusValue

Definition at line 1727 of file FileBackend.php.

References $params, and Wikimedia\FileBackend\FileBackend\wrapStatus().

◆ normalizeContainerPath()

static Wikimedia\FileBackend\FileBackend::normalizeContainerPath ( $path )

staticfinalprotected

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

string $path Storage path relative to a container

Returns: string|null Normalized container path or null on failure

Definition at line 1692 of file FileBackend.php.

References $path.

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

◆ normalizeStoragePath()

static Wikimedia\FileBackend\FileBackend::normalizeStoragePath ( $storagePath )

staticfinal

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

string $storagePath

Returns: string|null Normalized storage path or null on failure

Definition at line 1593 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\normalizeContainerPath(), and Wikimedia\FileBackend\FileBackend\splitStoragePath().

Referenced by Wikimedia\FileBackend\FileBackendStore\deleteFileCache(), Wikimedia\FileBackend\FileBackendStore\getFileSha1Base36(), Wikimedia\FileBackend\FileBackendStore\getFileStat(), Wikimedia\FileBackend\FileBackendStore\getFileXAttributes(), Wikimedia\FileBackend\FileBackendStore\getLocalReferenceMulti(), Wikimedia\FileBackend\FileOps\FileOp\normalizeIfValidStoragePath(), Wikimedia\FileBackend\FileBackendStore\primeFileCache(), and Wikimedia\FileBackend\FileBackendStore\setFileCache().

◆ parentStoragePath()

static Wikimedia\FileBackend\FileBackend::parentStoragePath ( $storagePath )

staticfinal

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

string $storagePath

Returns: string|null Parent storage path or null on failure

Definition at line 1615 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\splitStoragePath().

◆ preloadCache()

Wikimedia\FileBackend\FileBackend::preloadCache ( array $paths )

abstract

Preload persistent file stat cache 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.

See also: FileBackend::getFileStat()

Parameters

array $paths Storage paths

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ preloadFileStat()

Wikimedia\FileBackend\FileBackend::preloadFileStat ( array $params )

abstract

Preload file stat information (concurrently if possible) into in-process cache.

This should be used when stat calls will be made on a known list of a many files. This does not make use of the persistent file stat cache.

See also: FileBackend::getFileStat()

Parameters

array

$params

Parameters include:

srcs : list of source storage paths
latest : use the latest available data

Returns: bool Whether all requests proceeded without I/O errors (since 1.24)

Since: 1.23

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ prepare()

Wikimedia\FileBackend\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. However, setting them is not guaranteed to actually do anything. Additional server configuration may be needed to achieve the desired effect.

Parameters

array

$params

Parameters 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: StatusValue Good status without value for success, fatal otherwise.

Definition at line 897 of file FileBackend.php.

References $params, Wikimedia\FileBackend\FileBackend\doPrepare(), Wikimedia\FileBackend\FileBackend\isReadOnly(), and Wikimedia\FileBackend\FileBackend\newStatus().

Referenced by CopyFileBackend\copyFileBatch(), FileOpPerfTest\doPerfTest(), and ForeignAPIRepo\getThumbUrlFromCache().

◆ publish()

Wikimedia\FileBackend\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.

This is not guaranteed to actually make files or listings publicly viewable. Additional server configuration may be needed to achieve the desired effect.

Parameters

array

$params

Parameters 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: StatusValue

Since: 1.20

Definition at line 963 of file FileBackend.php.

References $params, Wikimedia\FileBackend\FileBackend\doPublish(), Wikimedia\FileBackend\FileBackend\isReadOnly(), and Wikimedia\FileBackend\FileBackend\newStatus().

◆ quickCopy()

Wikimedia\FileBackend\FileBackend::quickCopy	(	array	$params,
		array	$opts = [] )

final

Performs a single quick copy operation.

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

See also: FileBackend::doQuickOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.20

Definition at line 816 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperation().

◆ quickCreate()

Wikimedia\FileBackend\FileBackend::quickCreate	(	array	$params,
		array	$opts = [] )

final

Performs a single quick create operation.

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

See also: FileBackend::doQuickOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.20

Definition at line 786 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperation().

Referenced by ForeignAPIRepo\getThumbUrlFromCache().

◆ quickDelete()

Wikimedia\FileBackend\FileBackend::quickDelete	(	array	$params,
		array	$opts = [] )

final

Performs a single quick delete operation.

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

See also: FileBackend::doQuickOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.20

Definition at line 846 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperation().

◆ quickDescribe()

Wikimedia\FileBackend\FileBackend::quickDescribe	(	array	$params,
		array	$opts = [] )

final

Performs a single quick describe operation.

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

See also: FileBackend::doQuickOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.21

Definition at line 861 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperation().

◆ quickMove()

Wikimedia\FileBackend\FileBackend::quickMove	(	array	$params,
		array	$opts = [] )

final

Performs a single quick move operation.

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

See also: FileBackend::doQuickOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.20

Definition at line 831 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperation().

◆ quickStore()

Wikimedia\FileBackend\FileBackend::quickStore	(	array	$params,
		array	$opts = [] )

final

Performs a single quick store operation.

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

See also: FileBackend::doQuickOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Since: 1.20

Definition at line 801 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doQuickOperation().

◆ resetOutputBuffer()

Wikimedia\FileBackend\FileBackend::resetOutputBuffer ( )

protected

Definition at line 260 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\SwiftFileBackend\doStreamFile().

◆ resetOutputBufferTheDefaultWay()

static Wikimedia\FileBackend\FileBackend::resetOutputBufferTheDefaultWay ( )

static

Default behavior of resetOutputBuffer().

Access: internal

Definition at line 1758 of file FileBackend.php.

◆ resolveFSFileObjects()

Wikimedia\FileBackend\FileBackend::resolveFSFileObjects ( array $ops )

protected

Convert FSFile 'src' paths to string paths (with an 'srcRef' field set to the FSFile)

The 'srcRef' field keeps any TempFSFile objects in scope for the backend to have it around as long it needs (which may vary greatly depending on configuration)

Parameters

array $ops File operation batch for FileBaclend::doOperations()

Returns: array File operation batch

Definition at line 1538 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackend\doOperations(), and Wikimedia\FileBackend\FileBackend\doQuickOperations().

◆ scopedProfileSection()

Wikimedia\FileBackend\FileBackend::scopedProfileSection ( $section )

protected

Parameters

string $section

Returns: ScopedCallback|null

Definition at line 1749 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\$profiler.

◆ secure()

Wikimedia\FileBackend\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 make files or listings publicly hidden. Additional server configuration may be needed to achieve the desired effect.

Parameters

array

$params

Parameters 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: StatusValue

Definition at line 929 of file FileBackend.php.

References $params, Wikimedia\FileBackend\FileBackend\doSecure(), Wikimedia\FileBackend\FileBackend\isReadOnly(), and Wikimedia\FileBackend\FileBackend\newStatus().

◆ setLogger()

Wikimedia\FileBackend\FileBackend::setLogger ( LoggerInterface $logger )

Reimplemented in Wikimedia\FileBackend\SwiftFileBackend.

Definition at line 265 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\$logger.

◆ splitStoragePath()

static Wikimedia\FileBackend\FileBackend::splitStoragePath ( $storagePath )

staticfinal

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

string $storagePath

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

Definition at line 1570 of file FileBackend.php.

◆ store()

Wikimedia\FileBackend\FileBackend::store	(	array	$params,
		array	$opts = [] )

final

Performs a single store operation.

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

See also: FileBackend::doOperation()

Parameters

array	$params	Operation parameters
array	$opts	Operation options

Returns: StatusValue

Definition at line 557 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\doOperation().

◆ streamFile()

Wikimedia\FileBackend\FileBackend::streamFile ( array $params )

abstract

Stream the content of 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

array

$params

Parameters include:

src : source storage path
headers : list of additional HTTP headers to send if the file exists
options : HTTP request header map with lower case keys (since 1.28). Supports: range : format is "bytes=(\\d*-\\d*)" if-modified-since : format is an HTTP date
headless : do not send HTTP headers (including those of "headers") (since 1.28)
latest : use the latest available data
allowOB : preserve any output buffers (since 1.28)

Returns: StatusValue

Reimplemented in FileBackendDBRepoWrapper, Wikimedia\FileBackend\FileBackendMultiWrite, and Wikimedia\FileBackend\FileBackendStore.

◆ unlockFiles()

Wikimedia\FileBackend\FileBackend::unlockFiles	(	array	$paths,
			$type )

final

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

Parameters

array	$paths	Storage paths
int	$type	LockManager::LOCK_* constant

Returns: StatusValue

Definition at line 1453 of file FileBackend.php.

References Wikimedia\FileBackend\FileBackend\wrapStatus().

◆ wrapStatus()

Wikimedia\FileBackend\FileBackend::wrapStatus ( StatusValue $sv )

finalprotected

Parameters

StatusValue $sv

Returns: StatusValue Modified status or StatusValue subclass

Definition at line 1741 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackend\lockFiles(), Wikimedia\FileBackend\FileBackend\newStatus(), and Wikimedia\FileBackend\FileBackend\unlockFiles().

Member Data Documentation

◆ $concurrency

int Wikimedia\FileBackend\FileBackend::$concurrency

protected

How many operations can be done in parallel.

Definition at line 126 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackendStore\doQuickOperationsInternal(), and Wikimedia\FileBackend\FileBackendStore\setConcurrencyFlags().

◆ $domainId

string Wikimedia\FileBackend\FileBackend::$domainId

protected

Unique domain name.

Definition at line 117 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackendMultiWrite\__construct(), and Wikimedia\FileBackend\FileBackend\getDomainId().

◆ $lockManager

LockManager Wikimedia\FileBackend\FileBackend::$lockManager

protected

Definition at line 132 of file FileBackend.php.

◆ $logger

LoggerInterface Wikimedia\FileBackend\FileBackend::$logger

protected

Definition at line 134 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackendMultiWrite\__construct(), Wikimedia\FileBackend\FileBackend\setLogger(), and Wikimedia\FileBackend\SwiftFileBackend\setLogger().

◆ $name

string Wikimedia\FileBackend\FileBackend::$name

protected

Unique backend name.

Definition at line 114 of file FileBackend.php.

◆ $parallelize

string Wikimedia\FileBackend\FileBackend::$parallelize

protected

When to do operations in parallel.

Definition at line 123 of file FileBackend.php.

◆ $profiler

callable null Wikimedia\FileBackend\FileBackend::$profiler

protected

Definition at line 136 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackend\scopedProfileSection().

◆ $readOnly

string Wikimedia\FileBackend\FileBackend::$readOnly

protected

Read-only explanation message.

Definition at line 120 of file FileBackend.php.

◆ $statusWrapper

callable null Wikimedia\FileBackend\FileBackend::$statusWrapper

protected

Definition at line 145 of file FileBackend.php.

◆ $streamerOptions

array Wikimedia\FileBackend\FileBackend::$streamerOptions

protected

Option map for use with HTTPFileStreamer.

Definition at line 143 of file FileBackend.php.

◆ $tmpFileFactory

TempFSFileFactory Wikimedia\FileBackend\FileBackend::$tmpFileFactory

protected

Definition at line 129 of file FileBackend.php.

◆ ATTR_HEADERS

const Wikimedia\FileBackend\FileBackend::ATTR_HEADERS = 1

Bitfield flags for supported features.

Definition at line 148 of file FileBackend.php.

◆ ATTR_METADATA

const Wikimedia\FileBackend\FileBackend::ATTR_METADATA = 2

Definition at line 149 of file FileBackend.php.

◆ ATTR_UNICODE_PATHS

const Wikimedia\FileBackend\FileBackend::ATTR_UNICODE_PATHS = 4

Definition at line 150 of file FileBackend.php.

Referenced by Wikimedia\FileBackend\FileBackend\getFeatures(), Wikimedia\FileBackend\FSFileBackend\getFeatures(), and Wikimedia\FileBackend\MemoryFileBackend\getFeatures().

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

includes/libs/filebackend/FileBackend.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addShellboxInputFile()

◆ clean()

◆ clearCache()

◆ concatenate()

◆ copy()

◆ create()

◆ delete()

◆ describe()

◆ directoryExists()

◆ doClean()

◆ doOperation()

◆ doOperations()

◆ doOperationsInternal()

◆ doPrepare()

◆ doPublish()

◆ doQuickOperation()

◆ doQuickOperations()

◆ doQuickOperationsInternal()

◆ doSecure()

◆ extensionFromPath()

◆ fileExists()

◆ getContainerStoragePath()

◆ getDirectoryList()

◆ getDomainId()

◆ getFeatures()

◆ getFileContents()

◆ getFileContentsMulti()

◆ getFileHttpUrl()

◆ getFileList()

◆ getFileProps()

◆ getFileSha1Base36()

◆ getFileSize()

◆ getFileStat()

◆ getFileTimestamp()

◆ getFileXAttributes()

◆ getLocalCopy()

◆ getLocalCopyMulti()

◆ getLocalReference()

◆ getLocalReferenceMulti()

◆ getName()

◆ getReadOnlyReason()

◆ getRootStoragePath()

◆ getScopedFileLocks()

◆ getScopedLocksForOps()

◆ getStreamerOptions()

◆ getTopDirectoryList()

◆ getTopFileList()

◆ getWikiId()

◆ hasFeatures()

◆ header()

◆ isPathTraversalFree()

◆ isReadOnly()

◆ isStoragePath()

◆ lockFiles()

◆ makeContentDisposition()

◆ move()

◆ newStatus()

◆ normalizeContainerPath()

◆ normalizeStoragePath()

◆ parentStoragePath()

◆ preloadCache()

◆ preloadFileStat()

◆ prepare()

◆ publish()

◆ quickCopy()

◆ quickCreate()

◆ quickDelete()

◆ quickDescribe()

◆ quickMove()

◆ quickStore()