FileBackend helper class for representing operations. More...

Inheritance diagram for FileOp:

[legend]

Collaboration diagram for 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.

	getJournalEntries (array $oPredicates, array $nPredicates)
	Get the file journal entries for this file operation.

	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 (array &$predicates)
	Check preconditions of the operation without writing anything.

	setBatchId ( $batchId)
	Set the batch UUID this operation belongs to.

	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.

static	newPredicates ()
	Get a new empty predicates array for precheck()

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

	doAttempt ()

	doPrecheck (array &$predicates)

	fileExists ( $source, array $predicates)
	Check if a file will exist in storage when this operation is attempted.

	fileSha1 ( $source, array $predicates)
	Get the SHA-1 of a file in storage when this operation is attempted.

	fileSize ( $source, array $predicates)
	Get the size a file in storage will have when this operation is attempted.

	getSourceSha1Base36 ()
	precheckDestExistence() helper function to get the source file SHA-1.

	getSourceSize ()
	precheckDestExistence() helper function to get the source file size.

	precheckDestExistence (array $predicates)
	Check for errors with regards to the destination file already existing.

	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

FileBackendStore	$backend

string	$batchId

bool	$cancelled = false

bool	$destExists

bool	$failed = false

LoggerInterface	$logger

bool	$overwriteSameCase

array	$params = []

string bool	$sourceSha1

int bool	$sourceSize

int	$state = self::STATE_NEW

const	ASSUMED_EXISTS = 'exists'

const	ASSUMED_SHA1 = 'sha1'

const	ASSUMED_SIZE = 'size'

Private Attributes
const	STATE_ATTEMPTED = 3

const	STATE_CHECKED = 2

const	STATE_NEW = 1

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 36 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	$logger	PSR logger instance

Exceptions

InvalidArgumentException

Definition at line 84 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 358 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 $deps Prior path reads/writes; format of FileOp::newPredicates()

Returns: array

Definition at line 178 of file FileOp.php.

References storagePathsChanged(), and storagePathsRead().

◆ attempt()

FileOp::attempt ( )

final

Attempt the operation.

Returns: StatusValue

Definition at line 291 of file FileOp.php.

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

Referenced by attemptAsync(), and attemptQuick().

◆ attemptAsync()

FileOp::attemptAsync ( )

final

Attempt the operation in the background.

Returns: StatusValue

Definition at line 323 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 347 of file FileOp.php.

References attemptAsync(), and STATE_CHECKED.

◆ attemptQuick()

FileOp::attemptQuick ( )

final

Attempt the operation without regards to prechecks.

Returns: StatusValue

Definition at line 336 of file FileOp.php.

References attempt(), and STATE_CHECKED.

◆ dependsOn()

FileOp::dependsOn ( array $deps )

final

Check if this operation changes files listed in $paths.

Parameters

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

Returns: bool

Definition at line 191 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 314 of file FileOp.php.

Referenced by attempt().

◆ doPrecheck()

FileOp::doPrecheck ( array & $predicates )

protected

Parameters

array &$predicates

Returns: StatusValue

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

Definition at line 282 of file FileOp.php.

Referenced by precheck().

◆ failed()

FileOp::failed ( )

final

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

Returns: bool

Definition at line 150 of file FileOp.php.

References $failed.

Referenced by attempt(), and precheck().

◆ fileExists()

FileOp::fileExists	(		$source,
		array	$predicates )

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
array	$predicates

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

Definition at line 483 of file FileOp.php.

References $params, $source, ASSUMED_EXISTS, and true.

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

◆ fileSha1()

FileOp::fileSha1	(		$source,
		array	$predicates )

finalprotected

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

Parameters

string	$source	Storage path
array	$predicates

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

Definition at line 526 of file FileOp.php.

References $params, $source, ASSUMED_SHA1, and true.

Referenced by DescribeFileOp\doPrecheck(), getJournalEntries(), and precheckDestExistence().

◆ fileSize()

FileOp::fileSize	(		$source,
		array	$predicates )

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
array	$predicates

Returns: int False on failure

Definition at line 504 of file FileOp.php.

References $params, $source, ASSUMED_SIZE, and true.

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

◆ getBackend()

FileOp::getBackend ( )

Get the backend this operation is for.

Returns: FileBackendStore

Definition at line 546 of file FileOp.php.

References $backend.

◆ getJournalEntries()

FileOp::getJournalEntries	(	array	$oPredicates,
		array	$nPredicates )

final

Get the file journal entries for this file operation.

Parameters

array	$oPredicates	Pre-op info about files (format of FileOp::newPredicates)
array	$nPredicates	Post-op info about files (format of FileOp::newPredicates)

Returns: array

Definition at line 213 of file FileOp.php.

References $path, ASSUMED_SHA1, fileExists(), fileSha1(), storagePathsChanged(), and storagePathsReadOrChanged().

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

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

◆ getSourceSha1Base36()

FileOp::getSourceSha1Base36 ( )

protected

precheckDestExistence() helper function to get the source file SHA-1.

Subclasses should overwrite this if the source is not in storage.

Returns: string|bool Returns false on failure

Reimplemented in CreateFileOp, and StoreFileOp.

Definition at line 469 of file FileOp.php.

Referenced by precheckDestExistence().

◆ getSourceSize()

FileOp::getSourceSize ( )

protected

precheckDestExistence() helper function to get the source file size.

Subclasses should overwrite this if the source is not in storage.

Returns: string|bool Returns false on failure

Reimplemented in CreateFileOp, and StoreFileOp.

Definition at line 459 of file FileOp.php.

Referenced by precheckDestExistence().

◆ logFailure()

FileOp::logFailure ( $action )

final

Log a file operation failure and preserve any temp files.

Parameters

string $action

Definition at line 555 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 168 of file FileOp.php.

Referenced by FileOpBatch\attempt().

◆ newPredicates()

static FileOp::newPredicates ( )

staticfinal

Get a new empty predicates array for precheck()

Returns: array

Definition at line 159 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 116 of file FileOp.php.

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

Referenced by __construct().

◆ precheck()

FileOp::precheck ( array & $predicates )

final

Check preconditions of the operation without writing anything.

This must update $predicates for each path that the op can change except when a failing StatusValue object is returned.

Parameters

array &$predicates

Returns: StatusValue

Definition at line 254 of file FileOp.php.

References $path, doPrecheck(), failed(), STATE_CHECKED, and storagePathsReadOrChanged().

◆ precheckDestExistence()

FileOp::precheckDestExistence ( array $predicates )

protected

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

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

Parameters

array $predicates

Returns: StatusValue

Definition at line 409 of file FileOp.php.

References fileExists(), fileSha1(), fileSize(), getParam(), getSourceSha1Base36(), and getSourceSize().

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

◆ setBatchId()

FileOp::setBatchId ( $batchId )

final

Set the batch UUID this operation belongs to.

Parameters

string $batchId

Definition at line 131 of file FileOp.php.

References $batchId.

◆ 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 368 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 386 of file FileOp.php.

Referenced by applyDependencies(), dependsOn(), getJournalEntries(), 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 377 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 395 of file FileOp.php.

References storagePathsChanged(), and storagePathsRead().

Referenced by getJournalEntries(), and precheck().

Member Data Documentation

◆ $async

bool FileOp::$async = false

protected

Definition at line 50 of file FileOp.php.

Referenced by setFlags().

◆ $backend

FileBackendStore FileOp::$backend

protected

Definition at line 38 of file FileOp.php.

Referenced by __construct(), and getBackend().

◆ $batchId

string FileOp::$batchId

protected

Definition at line 52 of file FileOp.php.

Referenced by setBatchId().

◆ $cancelled

bool FileOp::$cancelled = false

protected

Definition at line 54 of file FileOp.php.

◆ $destExists

bool FileOp::$destExists

protected

Definition at line 65 of file FileOp.php.

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

◆ $failed

bool FileOp::$failed = false

protected

Definition at line 48 of file FileOp.php.

Referenced by failed().

◆ $logger

LoggerInterface FileOp::$logger

protected

Definition at line 40 of file FileOp.php.

Referenced by __construct().

◆ $overwriteSameCase

bool FileOp::$overwriteSameCase

protected

Definition at line 62 of file FileOp.php.

◆ $params

array FileOp::$params = []

protected

Definition at line 43 of file FileOp.php.

Referenced by __construct(), fileExists(), fileSha1(), fileSize(), logFailure(), and setFlags().

◆ $sourceSha1

string bool FileOp::$sourceSha1

protected

Definition at line 59 of file FileOp.php.

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

◆ $sourceSize

int bool FileOp::$sourceSize

protected

Definition at line 57 of file FileOp.php.

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

◆ $state

int FileOp::$state = self::STATE_NEW

protected

Definition at line 46 of file FileOp.php.

◆ ASSUMED_EXISTS

const FileOp::ASSUMED_EXISTS = 'exists'

protected

Definition at line 73 of file FileOp.php.

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

◆ ASSUMED_SHA1

const FileOp::ASSUMED_SHA1 = 'sha1'

protected

Definition at line 72 of file FileOp.php.

Referenced by CopyFileOp\doPrecheck(), CreateFileOp\doPrecheck(), DeleteFileOp\doPrecheck(), DescribeFileOp\doPrecheck(), MoveFileOp\doPrecheck(), StoreFileOp\doPrecheck(), fileSha1(), and getJournalEntries().

◆ ASSUMED_SIZE

const FileOp::ASSUMED_SIZE = 'size'

protected

Definition at line 74 of file FileOp.php.

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

◆ STATE_ATTEMPTED

const FileOp::STATE_ATTEMPTED = 3

private

Definition at line 70 of file FileOp.php.

Referenced by attempt().

◆ STATE_CHECKED

const FileOp::STATE_CHECKED = 2

private

Definition at line 69 of file FileOp.php.

Referenced by attemptAsyncQuick(), attemptQuick(), and precheck().

◆ STATE_NEW

const FileOp::STATE_NEW = 1

private

Definition at line 68 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

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ allowedParams()

◆ applyDependencies()

◆ attempt()

◆ attemptAsync()

◆ attemptAsyncQuick()

◆ attemptQuick()

◆ dependsOn()

◆ doAttempt()

◆ doPrecheck()

◆ failed()

◆ fileExists()

◆ fileSha1()

◆ fileSize()

◆ getBackend()

◆ getJournalEntries()

◆ getParam()

◆ getSourceSha1Base36()

◆ getSourceSize()

◆ logFailure()

◆ newDependencies()

◆ newPredicates()

◆ normalizeIfValidStoragePath()

◆ precheck()

◆ precheckDestExistence()

◆ setBatchId()

◆ setFlags()

◆ storagePathsChanged()

◆ storagePathsRead()

◆ storagePathsReadOrChanged()

Member Data Documentation

◆ $async

◆ $backend

◆ $batchId

◆ $cancelled

◆ $destExists

◆ $failed

◆ $logger

◆ $overwriteSameCase

◆ $params

◆ $sourceSha1

◆ $sourceSize

◆ $state

◆ ASSUMED_EXISTS

◆ ASSUMED_SHA1

◆ ASSUMED_SIZE

◆ STATE_ATTEMPTED

◆ STATE_CHECKED

◆ STATE_NEW