FileBackend helper class for representing operations. More...

Inherited by Wikimedia\FileBackend\FileOps\CopyFileOp, Wikimedia\FileBackend\FileOps\CreateFileOp, Wikimedia\FileBackend\FileOps\DeleteFileOp, Wikimedia\FileBackend\FileOps\DescribeFileOp, Wikimedia\FileBackend\FileOps\MoveFileOp, Wikimedia\FileBackend\FileOps\NullFileOp, and Wikimedia\FileBackend\FileOps\StoreFileOp.

Collaboration diagram for Wikimedia\FileBackend\FileOps\FileOp:

[legend]

Public Member Functions
	__construct (FileBackendStore $backend, array $params, LoggerInterface $logger)
	Build a new batch file operation transaction.

	applyDependencies (array $deps)
	Update a dependency tracking array to account for this operation.

	attempt ()
	Attempt the operation.

	attemptAsync ()
	Attempt the operation in the background.

	attemptAsyncQuick ()
	Attempt the operation in the background without regards to prechecks.

	attemptQuick ()
	Attempt the operation without regards to prechecks.

	dependsOn (array $deps)
	Check if this operation changes files listed in $paths.

	failed ()
	Check if this operation failed precheck() or attempt()

	getBackend ()
	Get the backend this operation is for.

	getParam ( $name)
	Get the value of the parameter with the given name.

	logFailure ( $action)
	Log a file operation failure and preserve any temp files.

	precheck (FileStatePredicates $predicates)
	Do a dry-run precondition check of the operation in the context of op batch.

	storagePathsChanged ()
	Get a list of storage paths written to for this operation.

	storagePathsRead ()
	Get a list of storage paths read from for this operation.

	storagePathsReadOrChanged ()
	Get a list of storage paths read from or written to for this operation.

Static Public Member Functions
static	newDependencies ()
	Get a new empty dependency tracking array for paths read/written to.

Protected Member Functions
	allowedParams ()
	Get the file operation parameters.

	doAttempt ()

	doPrecheck (FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates)
	Do a dry-run precondition check of the operation in the context of op batch.

	precheckDestExistence (FileStatePredicates $opPredicates, $sourceSize, $sourceSha1)
	Check for errors with regards to the destination file already existing.

	resolveFileExistence ( $source, FileStatePredicates $opPredicates)
	Check if a file will exist in storage when this operation is attempted.

	resolveFileSha1Base36 ( $source, FileStatePredicates $opPredicates)
	Get the SHA-1 of a file in storage when this operation is attempted.

	resolveFileSize ( $source, FileStatePredicates $opPredicates)
	Get the size a file in storage will have when this operation is attempted.

	setFlags (array $params)
	Adjust params to FileBackendStore internal file calls.

Static Protected Member Functions
static	normalizeIfValidStoragePath ( $path)
	Normalize a string if it is a valid storage path.

Protected Attributes
bool	$async = false
	Whether the operation is part of a concurrent sub-batch of operation.

FileBackendStore	$backend

bool null	$destExists

bool	$failed = false
	Whether the operation pre-check or attempt stage failed.

LoggerInterface	$logger

bool	$noOp = false
	Whether the operation pre-check stage marked the attempt stage as a no-op.

bool null	$overwriteSameCase

array	$params = []

int	$state = self::STATE_NEW
	Stage in the operation life-cycle.

Detailed Description

FileBackend helper class for representing operations.

Do not use this class from places outside FileBackend.

Methods called from FileOpBatch::attempt() should avoid throwing exceptions at all costs. FileOp objects should be lightweight in order to support large arrays in memory and serialization.

Since: 1.19

Definition at line 46 of file FileOp.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\FileBackend\FileOps\FileOp::__construct	(	FileBackendStore	$backend,
		array	$params,
		LoggerInterface	$logger )

final

Build a new batch file operation transaction.

Parameters

FileBackendStore	$backend
array	$params
LoggerInterface	$logger	PSR logger instance

Definition at line 83 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\$backend, Wikimedia\FileBackend\FileOps\FileOp\$logger, Wikimedia\FileBackend\FileOps\FileOp\$params, Wikimedia\FileBackend\FileOps\FileOp\allowedParams(), and Wikimedia\FileBackend\FileOps\FileOp\normalizeIfValidStoragePath().

Member Function Documentation

◆ allowedParams()

Wikimedia\FileBackend\FileOps\FileOp::allowedParams ( )

protected

Get the file operation parameters.

Returns: array (required params list, optional params list, list of params that are paths)

Reimplemented in Wikimedia\FileBackend\FileOps\CopyFileOp, Wikimedia\FileBackend\FileOps\CreateFileOp, Wikimedia\FileBackend\FileOps\DeleteFileOp, Wikimedia\FileBackend\FileOps\DescribeFileOp, Wikimedia\FileBackend\FileOps\MoveFileOp, and Wikimedia\FileBackend\FileOps\StoreFileOp.

Definition at line 308 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\__construct().

◆ applyDependencies()

Wikimedia\FileBackend\FileOps\FileOp::applyDependencies ( array $deps )

final

Update a dependency tracking array to account for this operation.

Parameters

array $deps Prior path reads/writes; format of FileOp::newDependencies()

Returns: array

Definition at line 159 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\storagePathsChanged(), and Wikimedia\FileBackend\FileOps\FileOp\storagePathsRead().

◆ attempt()

Wikimedia\FileBackend\FileOps\FileOp::attempt ( )

final

Attempt the operation.

Returns: StatusValue

Definition at line 241 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\doAttempt(), Wikimedia\FileBackend\FileOps\FileOp\failed(), and Wikimedia\FileBackend\FileOps\FileOp\logFailure().

Referenced by Wikimedia\FileBackend\FileOps\FileOp\attemptAsync(), and Wikimedia\FileBackend\FileOps\FileOp\attemptQuick().

◆ attemptAsync()

Wikimedia\FileBackend\FileOps\FileOp::attemptAsync ( )

final

Attempt the operation in the background.

Returns: StatusValue

Definition at line 273 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\attempt().

Referenced by Wikimedia\FileBackend\FileOps\FileOp\attemptAsyncQuick().

◆ attemptAsyncQuick()

Wikimedia\FileBackend\FileOps\FileOp::attemptAsyncQuick ( )

final

Attempt the operation in the background without regards to prechecks.

Returns: StatusValue

Definition at line 297 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\attemptAsync().

◆ attemptQuick()

Wikimedia\FileBackend\FileOps\FileOp::attemptQuick ( )

final

Attempt the operation without regards to prechecks.

Returns: StatusValue

Definition at line 286 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\attempt().

◆ dependsOn()

Wikimedia\FileBackend\FileOps\FileOp::dependsOn ( array $deps )

final

Check if this operation changes files listed in $paths.

Parameters

array $deps Prior path reads/writes; format of FileOp::newDependencies()

Returns: bool

Definition at line 172 of file FileOp.php.

References $path, Wikimedia\FileBackend\FileOps\FileOp\storagePathsChanged(), and Wikimedia\FileBackend\FileOps\FileOp\storagePathsRead().

◆ doAttempt()

Wikimedia\FileBackend\FileOps\FileOp::doAttempt ( )

protected

Returns: StatusValue

Reimplemented in Wikimedia\FileBackend\FileOps\CopyFileOp, Wikimedia\FileBackend\FileOps\CreateFileOp, Wikimedia\FileBackend\FileOps\DeleteFileOp, Wikimedia\FileBackend\FileOps\DescribeFileOp, Wikimedia\FileBackend\FileOps\MoveFileOp, and Wikimedia\FileBackend\FileOps\StoreFileOp.

Definition at line 264 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\attempt().

◆ doPrecheck()

Wikimedia\FileBackend\FileOps\FileOp::doPrecheck	(	FileStatePredicates	$opPredicates,
		FileStatePredicates	$batchPredicates )

protected

Do a dry-run precondition check of the operation in the context of op batch.

Updates the batch predicates for all paths this op can change if an OK status is returned

Parameters

FileStatePredicates	$opPredicates	Counterfactual file states for op paths at op start
FileStatePredicates	$batchPredicates	Counterfactual file states for the op batch

Returns: StatusValue

Reimplemented in Wikimedia\FileBackend\FileOps\CopyFileOp, Wikimedia\FileBackend\FileOps\CreateFileOp, Wikimedia\FileBackend\FileOps\DeleteFileOp, Wikimedia\FileBackend\FileOps\DescribeFileOp, Wikimedia\FileBackend\FileOps\MoveFileOp, and Wikimedia\FileBackend\FileOps\StoreFileOp.

Definition at line 229 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\precheck().

◆ failed()

Wikimedia\FileBackend\FileOps\FileOp::failed ( )

final

Check if this operation failed precheck() or attempt()

Returns: bool

Definition at line 140 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\$failed.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\attempt(), and Wikimedia\FileBackend\FileOps\FileOp\precheck().

◆ getBackend()

Wikimedia\FileBackend\FileOps\FileOp::getBackend ( )

Get the backend this operation is for.

Returns: FileBackendStore

Definition at line 462 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\$backend.

◆ getParam()

Wikimedia\FileBackend\FileOps\FileOp::getParam ( $name )

final

Get the value of the parameter with the given name.

Parameters

string $name

Returns: mixed Returns null if the parameter is not set

Definition at line 131 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doAttempt(), Wikimedia\FileBackend\FileOps\MoveFileOp\doAttempt(), Wikimedia\FileBackend\FileOps\CopyFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\DeleteFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\MoveFileOp\doPrecheck(), and Wikimedia\FileBackend\FileOps\FileOp\precheckDestExistence().

◆ logFailure()

Wikimedia\FileBackend\FileOps\FileOp::logFailure ( $action )

final

Log a file operation failure and preserve any temp files.

Parameters

string $action

Definition at line 471 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\attempt().

◆ newDependencies()

static Wikimedia\FileBackend\FileOps\FileOp::newDependencies ( )

staticfinal

Get a new empty dependency tracking array for paths read/written to.

Returns: array

Definition at line 149 of file FileOp.php.

◆ normalizeIfValidStoragePath()

static Wikimedia\FileBackend\FileOps\FileOp::normalizeIfValidStoragePath ( $path )

staticprotected

Normalize a string if it is a valid storage path.

Parameters

string $path

Returns: string

Definition at line 115 of file FileOp.php.

References $path, Wikimedia\FileBackend\FileBackend\isStoragePath(), and Wikimedia\FileBackend\FileBackend\normalizeStoragePath().

Referenced by Wikimedia\FileBackend\FileOps\FileOp\__construct().

◆ precheck()

Wikimedia\FileBackend\FileOps\FileOp::precheck ( FileStatePredicates $predicates )

final

Do a dry-run precondition check of the operation in the context of op batch.

Updates the batch predicates for all paths this op can change if an OK status is returned

Parameters

FileStatePredicates $predicates Counterfactual file states for the op batch

Returns: StatusValue

Definition at line 195 of file FileOp.php.

References $path, Wikimedia\FileBackend\FileOps\FileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\FileOp\failed(), Wikimedia\FileBackend\FileOps\FileStatePredicates\snapshot(), and Wikimedia\FileBackend\FileOps\FileOp\storagePathsReadOrChanged().

◆ precheckDestExistence()

Wikimedia\FileBackend\FileOps\FileOp::precheckDestExistence	(	FileStatePredicates	$opPredicates,
			$sourceSize,
			$sourceSha1 )

protected

Check for errors with regards to the destination file already existing.

Also set the destExists and overwriteSameCase member variables. A bad StatusValue will be returned if there is no chance it can be overwritten.

Parameters

FileStatePredicates	$opPredicates	Counterfactual storage path states for this op
int \| false \| Closure	$sourceSize	Source size or idempotent function yielding the size
string \| Closure	$sourceSha1	Source hash, or, idempotent function yielding the hash

Returns: StatusValue

Definition at line 362 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\getParam(), Wikimedia\FileBackend\FileOps\FileOp\resolveFileExistence(), Wikimedia\FileBackend\FileOps\FileOp\resolveFileSha1Base36(), and Wikimedia\FileBackend\FileOps\FileOp\resolveFileSize().

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\CreateFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\MoveFileOp\doPrecheck(), and Wikimedia\FileBackend\FileOps\StoreFileOp\doPrecheck().

◆ resolveFileExistence()

Wikimedia\FileBackend\FileOps\FileOp::resolveFileExistence	(		$source,
		FileStatePredicates	$opPredicates )

finalprotected

Check if a file will exist in storage when this operation is attempted.

Ideally, the file stat entry should already be preloaded via preloadFileStat(). Otherwise, this will query the backend.

Parameters

string	$source	Storage path
FileStatePredicates	$opPredicates	Counterfactual storage path states for this op

Returns: bool|null Whether the file will exist or null on error

Definition at line 412 of file FileOp.php.

References $path, $source, and Wikimedia\FileBackend\FileOps\FileStatePredicates\resolveFileExistence().

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\DeleteFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\DescribeFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\MoveFileOp\doPrecheck(), and Wikimedia\FileBackend\FileOps\FileOp\precheckDestExistence().

◆ resolveFileSha1Base36()

Wikimedia\FileBackend\FileOps\FileOp::resolveFileSha1Base36	(		$source,
		FileStatePredicates	$opPredicates )

finalprotected

Get the SHA-1 of a file in storage when this operation is attempted.

Parameters

string	$source	Storage path
FileStatePredicates	$opPredicates	Counterfactual storage path states for this op

Returns: string|false The SHA-1 hash the file will have or false if non-existent or on error

Definition at line 448 of file FileOp.php.

References $path, $source, and Wikimedia\FileBackend\FileOps\FileStatePredicates\resolveFileSha1Base36().

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\DescribeFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\MoveFileOp\doPrecheck(), and Wikimedia\FileBackend\FileOps\FileOp\precheckDestExistence().

◆ resolveFileSize()

Wikimedia\FileBackend\FileOps\FileOp::resolveFileSize	(		$source,
		FileStatePredicates	$opPredicates )

finalprotected

Get the size a file in storage will have when this operation is attempted.

Ideally, file the stat entry should already be preloaded via preloadFileStat() and the backend tracks hashes as extended attributes. Otherwise, this will query the backend. Get the size of a file in storage when this operation is attempted

Parameters

string	$source	Storage path
FileStatePredicates	$opPredicates	Counterfactual storage path states for this op

Returns: int|false False on failure

Definition at line 432 of file FileOp.php.

References $path, $source, and Wikimedia\FileBackend\FileOps\FileStatePredicates\resolveFileSize().

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\DescribeFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\MoveFileOp\doPrecheck(), and Wikimedia\FileBackend\FileOps\FileOp\precheckDestExistence().

◆ setFlags()

Wikimedia\FileBackend\FileOps\FileOp::setFlags ( array $params )

protected

Adjust params to FileBackendStore internal file calls.

Parameters

array $params

Returns: array (required params list, optional params list)

Definition at line 318 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\$async, and Wikimedia\FileBackend\FileOps\FileOp\$params.

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doAttempt(), Wikimedia\FileBackend\FileOps\CreateFileOp\doAttempt(), Wikimedia\FileBackend\FileOps\DeleteFileOp\doAttempt(), Wikimedia\FileBackend\FileOps\DescribeFileOp\doAttempt(), Wikimedia\FileBackend\FileOps\MoveFileOp\doAttempt(), and Wikimedia\FileBackend\FileOps\StoreFileOp\doAttempt().

◆ storagePathsChanged()

Wikimedia\FileBackend\FileOps\FileOp::storagePathsChanged ( )

Get a list of storage paths written to for this operation.

Returns: array

Reimplemented in Wikimedia\FileBackend\FileOps\CopyFileOp, Wikimedia\FileBackend\FileOps\CreateFileOp, Wikimedia\FileBackend\FileOps\DeleteFileOp, Wikimedia\FileBackend\FileOps\DescribeFileOp, Wikimedia\FileBackend\FileOps\MoveFileOp, and Wikimedia\FileBackend\FileOps\StoreFileOp.

Definition at line 336 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\applyDependencies(), Wikimedia\FileBackend\FileOps\FileOp\dependsOn(), and Wikimedia\FileBackend\FileOps\FileOp\storagePathsReadOrChanged().

◆ storagePathsRead()

Wikimedia\FileBackend\FileOps\FileOp::storagePathsRead ( )

Get a list of storage paths read from for this operation.

Returns: array

Reimplemented in Wikimedia\FileBackend\FileOps\CopyFileOp, and Wikimedia\FileBackend\FileOps\MoveFileOp.

Definition at line 327 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\applyDependencies(), Wikimedia\FileBackend\FileOps\FileOp\dependsOn(), and Wikimedia\FileBackend\FileOps\FileOp\storagePathsReadOrChanged().

◆ storagePathsReadOrChanged()

Wikimedia\FileBackend\FileOps\FileOp::storagePathsReadOrChanged ( )

final

Get a list of storage paths read from or written to for this operation.

Returns: array

Definition at line 345 of file FileOp.php.

References Wikimedia\FileBackend\FileOps\FileOp\storagePathsChanged(), and Wikimedia\FileBackend\FileOps\FileOp\storagePathsRead().

Referenced by Wikimedia\FileBackend\FileOps\FileOp\precheck().

Member Data Documentation

◆ $async

bool Wikimedia\FileBackend\FileOps\FileOp::$async = false

protected

Whether the operation is part of a concurrent sub-batch of operation.

Definition at line 60 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\setFlags().

◆ $backend

FileBackendStore Wikimedia\FileBackend\FileOps\FileOp::$backend

protected

Definition at line 48 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\__construct(), and Wikimedia\FileBackend\FileOps\FileOp\getBackend().

◆ $destExists

bool null Wikimedia\FileBackend\FileOps\FileOp::$destExists

protected

Definition at line 67 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\CopyFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\CreateFileOp\doPrecheck(), Wikimedia\FileBackend\FileOps\MoveFileOp\doPrecheck(), and Wikimedia\FileBackend\FileOps\StoreFileOp\doPrecheck().

◆ $failed

bool Wikimedia\FileBackend\FileOps\FileOp::$failed = false

protected

Whether the operation pre-check or attempt stage failed.

Definition at line 58 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\failed().

◆ $logger

LoggerInterface Wikimedia\FileBackend\FileOps\FileOp::$logger

protected

Definition at line 50 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\__construct().

◆ $noOp

bool Wikimedia\FileBackend\FileOps\FileOp::$noOp = false

protected

Whether the operation pre-check stage marked the attempt stage as a no-op.

Definition at line 62 of file FileOp.php.

◆ $overwriteSameCase

bool null Wikimedia\FileBackend\FileOps\FileOp::$overwriteSameCase

protected

Definition at line 65 of file FileOp.php.

◆ $params

array Wikimedia\FileBackend\FileOps\FileOp::$params = []

protected

Definition at line 53 of file FileOp.php.

Referenced by Wikimedia\FileBackend\FileOps\FileOp\__construct(), and Wikimedia\FileBackend\FileOps\FileOp\setFlags().

◆ $state

int Wikimedia\FileBackend\FileOps\FileOp::$state = self::STATE_NEW

protected

Stage in the operation life-cycle.

Definition at line 56 of file FileOp.php.

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

includes/libs/filebackend/fileop/FileOp.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ allowedParams()

◆ applyDependencies()

◆ attempt()

◆ attemptAsync()

◆ attemptAsyncQuick()

◆ attemptQuick()

◆ dependsOn()

◆ doAttempt()

◆ doPrecheck()

◆ failed()

◆ getBackend()

◆ getParam()

◆ logFailure()

◆ newDependencies()

◆ normalizeIfValidStoragePath()

◆ precheck()

◆ precheckDestExistence()

◆ resolveFileExistence()

◆ resolveFileSha1Base36()

◆ resolveFileSize()

◆ setFlags()

◆ storagePathsChanged()

◆ storagePathsRead()

◆ storagePathsReadOrChanged()

Member Data Documentation

◆ $async

◆ $backend

◆ $destExists

◆ $failed

◆ $logger

◆ $noOp

◆ $overwriteSameCase

◆ $params

◆ $state