MediaWiki master
FileOp Class Reference

FileBackend helper class for representing operations. More...

Inherited by CopyFileOp, CreateFileOp, DeleteFileOp, DescribeFileOp, MoveFileOp, NullFileOp, and StoreFileOp.

Collaboration diagram for FileOp:

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 39 of file FileOp.php.

Constructor & Destructor Documentation

◆ __construct()

FileOp::__construct ( FileBackendStore $backend,
array $params,
LoggerInterface $logger )
final

Build a new batch file operation transaction.

Parameters
FileBackendStore$backend
array$params
LoggerInterface$loggerPSR logger instance
Exceptions
InvalidArgumentException

Definition at line 77 of file FileOp.php.

References $backend, $logger, $params, allowedParams(), and normalizeIfValidStoragePath().

Member Function Documentation

◆ allowedParams()

FileOp::allowedParams ( )
protected

Get the file operation parameters.

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

Reimplemented in CopyFileOp, CreateFileOp, DeleteFileOp, DescribeFileOp, MoveFileOp, and StoreFileOp.

Definition at line 302 of file FileOp.php.

Referenced by __construct().

◆ applyDependencies()

FileOp::applyDependencies ( array $deps)
final

Update a dependency tracking array to account for this operation.

Parameters
array$depsPrior path reads/writes; format of FileOp::newDependencies()
Returns
array

Definition at line 153 of file FileOp.php.

References storagePathsChanged(), and storagePathsRead().

◆ attempt()

FileOp::attempt ( )
final

Attempt the operation.

Returns
StatusValue

Definition at line 235 of file FileOp.php.

References doAttempt(), failed(), and logFailure().

Referenced by attemptAsync(), and attemptQuick().

◆ attemptAsync()

FileOp::attemptAsync ( )
final

Attempt the operation in the background.

Returns
StatusValue

Definition at line 267 of file FileOp.php.

References attempt().

Referenced by attemptAsyncQuick().

◆ attemptAsyncQuick()

FileOp::attemptAsyncQuick ( )
final

Attempt the operation in the background without regards to prechecks.

Returns
StatusValue

Definition at line 291 of file FileOp.php.

References attemptAsync().

◆ attemptQuick()

FileOp::attemptQuick ( )
final

Attempt the operation without regards to prechecks.

Returns
StatusValue

Definition at line 280 of file FileOp.php.

References attempt().

◆ dependsOn()

FileOp::dependsOn ( array $deps)
final

Check if this operation changes files listed in $paths.

Parameters
array$depsPrior path reads/writes; format of FileOp::newDependencies()
Returns
bool

Definition at line 166 of file FileOp.php.

References $path, storagePathsChanged(), and storagePathsRead().

◆ doAttempt()

FileOp::doAttempt ( )
protected
Returns
StatusValue

Reimplemented in CopyFileOp, CreateFileOp, DeleteFileOp, DescribeFileOp, MoveFileOp, and StoreFileOp.

Definition at line 258 of file FileOp.php.

Referenced by attempt().

◆ doPrecheck()

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$opPredicatesCounterfactual file states for op paths at op start
FileStatePredicates$batchPredicatesCounterfactual file states for the op batch
Returns
StatusValue

Reimplemented in CopyFileOp, CreateFileOp, DeleteFileOp, DescribeFileOp, MoveFileOp, and StoreFileOp.

Definition at line 223 of file FileOp.php.

Referenced by precheck().

◆ failed()

FileOp::failed ( )
final

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

Returns
bool

Definition at line 134 of file FileOp.php.

References $failed.

Referenced by attempt(), and precheck().

◆ getBackend()

FileOp::getBackend ( )

Get the backend this operation is for.

Returns
FileBackendStore

Definition at line 456 of file FileOp.php.

References $backend.

◆ getParam()

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 125 of file FileOp.php.

Referenced by CopyFileOp\doAttempt(), MoveFileOp\doAttempt(), CopyFileOp\doPrecheck(), DeleteFileOp\doPrecheck(), MoveFileOp\doPrecheck(), and precheckDestExistence().

◆ logFailure()

FileOp::logFailure ( $action)
final

Log a file operation failure and preserve any temp files.

Parameters
string$action

Definition at line 465 of file FileOp.php.

References $params.

Referenced by attempt().

◆ newDependencies()

static FileOp::newDependencies ( )
staticfinal

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

Returns
array

Definition at line 143 of file FileOp.php.

Referenced by FileOpBatch\attempt().

◆ normalizeIfValidStoragePath()

static FileOp::normalizeIfValidStoragePath ( $path)
staticprotected

Normalize a string if it is a valid storage path.

Parameters
string$path
Returns
string

Definition at line 109 of file FileOp.php.

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

Referenced by __construct().

◆ precheck()

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$predicatesCounterfactual file states for the op batch
Returns
StatusValue

Definition at line 189 of file FileOp.php.

References $path, doPrecheck(), failed(), FileStatePredicates\snapshot(), and storagePathsReadOrChanged().

◆ precheckDestExistence()

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$opPredicatesCounterfactual storage path states for this op
int | false | Closure$sourceSizeSource size or idempotent function yielding the size
string | Closure$sourceSha1Source hash, or, idempotent function yielding the hash
Returns
StatusValue

Definition at line 356 of file FileOp.php.

References getParam(), resolveFileExistence(), resolveFileSha1Base36(), and resolveFileSize().

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

◆ resolveFileExistence()

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$sourceStorage path
FileStatePredicates$opPredicatesCounterfactual storage path states for this op
Returns
bool|null Whether the file will exist or null on error

Definition at line 406 of file FileOp.php.

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

Referenced by CopyFileOp\doPrecheck(), DeleteFileOp\doPrecheck(), DescribeFileOp\doPrecheck(), MoveFileOp\doPrecheck(), and precheckDestExistence().

◆ resolveFileSha1Base36()

FileOp::resolveFileSha1Base36 ( $source,
FileStatePredicates $opPredicates )
finalprotected

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

Parameters
string$sourceStorage path
FileStatePredicates$opPredicatesCounterfactual 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 442 of file FileOp.php.

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

Referenced by CopyFileOp\doPrecheck(), DescribeFileOp\doPrecheck(), MoveFileOp\doPrecheck(), and precheckDestExistence().

◆ resolveFileSize()

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$sourceStorage path
FileStatePredicates$opPredicatesCounterfactual storage path states for this op
Returns
int|false False on failure

Definition at line 426 of file FileOp.php.

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

Referenced by CopyFileOp\doPrecheck(), DescribeFileOp\doPrecheck(), MoveFileOp\doPrecheck(), and precheckDestExistence().

◆ setFlags()

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 312 of file FileOp.php.

References $async, and $params.

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

◆ storagePathsChanged()

FileOp::storagePathsChanged ( )

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

Returns
array

Reimplemented in CopyFileOp, CreateFileOp, DeleteFileOp, DescribeFileOp, MoveFileOp, and StoreFileOp.

Definition at line 330 of file FileOp.php.

Referenced by applyDependencies(), dependsOn(), and storagePathsReadOrChanged().

◆ storagePathsRead()

FileOp::storagePathsRead ( )

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

Returns
array

Reimplemented in CopyFileOp, and MoveFileOp.

Definition at line 321 of file FileOp.php.

Referenced by applyDependencies(), dependsOn(), and storagePathsReadOrChanged().

◆ storagePathsReadOrChanged()

FileOp::storagePathsReadOrChanged ( )
final

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

Returns
array

Definition at line 339 of file FileOp.php.

References storagePathsChanged(), and storagePathsRead().

Referenced by precheck().

Member Data Documentation

◆ $async

bool FileOp::$async = false
protected

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

Definition at line 53 of file FileOp.php.

Referenced by setFlags().

◆ $backend

FileBackendStore FileOp::$backend
protected

Definition at line 41 of file FileOp.php.

Referenced by __construct(), and getBackend().

◆ $destExists

bool null FileOp::$destExists
protected

◆ $failed

bool FileOp::$failed = false
protected

Whether the operation pre-check or attempt stage failed.

Definition at line 51 of file FileOp.php.

Referenced by failed().

◆ $logger

LoggerInterface FileOp::$logger
protected

Definition at line 43 of file FileOp.php.

Referenced by __construct().

◆ $noOp

bool FileOp::$noOp = false
protected

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

Definition at line 55 of file FileOp.php.

◆ $overwriteSameCase

bool null FileOp::$overwriteSameCase
protected

Definition at line 58 of file FileOp.php.

◆ $params

array FileOp::$params = []
protected

Definition at line 46 of file FileOp.php.

Referenced by __construct(), logFailure(), and setFlags().

◆ $state

int FileOp::$state = self::STATE_NEW
protected

Stage in the operation life-cycle.

Definition at line 49 of file FileOp.php.


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