* A few other minor doc cleanups and obvious type hints.
Change-Id: I454fad0c1942068b4f3632ebd1b605bfbb9dfe7c
* Get an associative array containing information about
* a file with the given storage path.
*
- * @param $ext Mixed: the file extension, or true to extract it from the filename.
+ * @param Mixed $ext: the file extension, or true to extract it from the filename.
* Set it to false to ignore the extension.
*
* @return array
/**
* Exract image size information
*
- * @param $gis array
+ * @param array $gis
* @return Array
*/
protected function extractImageSizeInfo( array $gis ) {
* 160 log 2 / log 36 = 30.95, so the 160-bit hash fills 31 digits in base 36
* fairly neatly.
*
- * @param $recache bool
+ * @param bool $recache
* @return bool|string False on failure
*/
public function getSha1Base36( $recache = false ) {
/**
* Get the final file extension from a file system path
*
- * @param $path string
+ * @param string $path
* @return string
*/
public static function extensionFromPath( $path ) {
* Get an associative array containing information about a file in the local filesystem.
*
* @param string $path absolute local filesystem path
- * @param $ext Mixed: the file extension, or true to extract it from the filename.
+ * @param Mixed $ext: the file extension, or true to extract it from the filename.
* Set it to false to ignore the extension.
*
* @return array
* 160 log 2 / log 36 = 30.95, so the 160-bit hash fills 31 digits in base 36
* fairly neatly.
*
- * @param $path string
- * @param $recache bool
+ * @param string $path
+ * @param bool $recache
*
* @return bool|string False on failure
*/
* Given the short (unresolved) and full (resolved) name of
* a container, return the file system path of the container.
*
- * @param $shortCont string
- * @param $fullCont string
+ * @param string $shortCont
+ * @param string $fullCont
* @return string|null
*/
protected function containerFSRoot( $shortCont, $fullCont ) {
}
/**
- * @param $errno integer
- * @param $errstr string
+ * @param integer $errno
+ * @param string $errstr
* @return bool
* @access private
*/
public $chmodPath; // string; file to chmod
/**
- * @param $backend
- * @param $params array
- * @param $call
- * @param $cmd
- * @param $chmodPath null
+ * @param FSFileBackend $backend
+ * @param array $params
+ * @param string $call
+ * @param string $cmd
+ * @param integer|null $chmodPath
*/
- public function __construct( $backend, array $params, $call, $cmd, $chmodPath = null ) {
+ public function __construct(
+ FSFileBackend $backend, array $params, $call, $cmd, $chmodPath = null
+ ) {
$this->backend = $backend;
$this->params = $params;
$this->call = $call;
/**
* @param string $dir file system directory
- * @param $params array
+ * @param array $params
*/
public function __construct( $dir, array $params ) {
$path = realpath( $dir ); // normalize
* Return only the relative path and normalize slashes to FileBackend-style.
* Uses the "real path" since the suffix is based upon that.
*
- * @param $path string
+ * @param string $path
* @return string
*/
protected function getRelPath( $dir ) {
* Allowed values are "implicit", "explicit" and "off".
* - concurrency : How many file operations can be done in parallel.
*
- * @param $config Array
+ * @param array $config
* @throws MWException
*/
public function __construct( array $config ) {
*
* Storage backends with eventual consistency might return stale data.
*
- * @param $params array
+ * @param array $params
* $params include:
* - dir : storage directory
* @return bool|null Returns null on failure
*
* Storage backends with eventual consistency might return stale data.
*
- * @param $params array
+ * @param array $params
* $params include:
* - dir : storage directory
* - topOnly : only return direct child dirs of the directory
*
* Storage backends with eventual consistency might return stale data.
*
- * @param $params array
+ * @param array $params
* $params include:
* - dir : storage directory
* @return Traversable|Array|null Returns null on failure
*
* Storage backends with eventual consistency might return stale data.
*
- * @param $params array
+ * @param array $params
* $params include:
* - dir : storage directory
* - topOnly : only return direct child files of the directory (since 1.20)
*
* Storage backends with eventual consistency might return stale data.
*
- * @param $params array
+ * @param array $params
* $params include:
* - dir : storage directory
* - adviseStat : set to true if stat requests will be made on the files (since 1.22)
* Callers should consider using getScopedFileLocks() instead.
*
* @param array $paths Storage paths
- * @param $type integer LockManager::LOCK_* constant
+ * @param integer $type LockManager::LOCK_* constant
* @return Status
*/
final public function lockFiles( array $paths, $type ) {
* Unlock the files at the given storage paths in the backend.
*
* @param array $paths Storage paths
- * @param $type integer LockManager::LOCK_* constant
+ * @param integer $type LockManager::LOCK_* constant
* @return Status
*/
final public function unlockFiles( array $paths, $type ) {
* the status updated. Unlock fatals will not change the status "OK" value.
*
* @param array $paths Storage paths
- * @param $type integer LockManager::LOCK_* constant
- * @param $status Status Status to update on lock/unlock
+ * @param integer $type LockManager::LOCK_* constant
+ * @param Status $status Status to update on lock/unlock
* @return ScopedLock|null Returns null on failure
*/
final public function getScopedFileLocks( array $paths, $type, Status $status ) {
* @see FileBackend::doOperations()
*
* @param array $ops List of file operations to FileBackend::doOperations()
- * @param $status Status Status to update on lock/unlock
+ * @param Status $status Status to update on lock/unlock
* @return Array List of ScopedFileLocks or null values
* @since 1.20
*/
* Check if a given path is a "mwstore://" path.
* This does not do any further validation or any existence checks.
*
- * @param $path string
+ * @param string $path
* @return bool
*/
final public static function isStoragePath( $path ) {
* and a relative file path. The relative path may be the empty string.
* This does not do any path normalization or traversal checks.
*
- * @param $storagePath string
+ * @param string $storagePath
* @return Array (backend, container, rel object) or (null, null, null)
*/
final public static function splitStoragePath( $storagePath ) {
* Normalize a storage path by cleaning up directory separators.
* Returns null if the path is not of the format of a valid storage path.
*
- * @param $storagePath string
+ * @param string $storagePath
* @return string|null
*/
final public static function normalizeStoragePath( $storagePath ) {
* This returns a path like "mwstore://backend/container",
* "mwstore://backend/container/...", or null if there is no parent.
*
- * @param $storagePath string
+ * @param string $storagePath
* @return string|null
*/
final public static function parentStoragePath( $storagePath ) {
/**
* Get the final extension from a storage or FS path
*
- * @param $path string
+ * @param string $path
* @return string
*/
final public static function extensionFromPath( $path ) {
/**
* Check if a relative path has no directory traversals
*
- * @param $path string
+ * @param string $path
* @return bool
* @since 1.20
*/
/**
* Register an array of file backend configurations
*
- * @param $configs Array
+ * @param Array $configs
* @return void
* @throws MWException
*/
/**
* Get the backend object with a given name
*
- * @param $name string
+ * @param string $name
* @return FileBackend
* @throws MWException
*/
/**
* Get the config array for a backend object with a given name
*
- * @param $name string
+ * @param string $name
* @return Array
* @throws MWException
*/
/**
* Get an appropriate backend object from a storage path
*
- * @param $storagePath string
+ * @param string $storagePath
* @return FileBackend|null Backend or null on failure
*/
public function backendFromPath( $storagePath ) {
* - noPushQuickOps : (hack) Only apply doQuickOperations() to the master backend.
* - noPushDirConts : (hack) Only apply directory functions to the master backend.
*
- * @param $config Array
+ * @param Array $config
* @throws MWException
*/
public function __construct( array $config ) {
* for a set of operations with that of a given internal backend.
*
* @param array $ops List of file operation arrays
- * @param $backend FileBackendStore
+ * @param FileBackendStore $backend
* @return Array
*/
protected function substOpBatchPaths( array $ops, FileBackendStore $backend ) {
* Same as substOpBatchPaths() but for a single operation
*
* @param array $ops File operation array
- * @param $backend FileBackendStore
+ * @param FileBackendStore $backend
* @return Array
*/
protected function substOpPaths( array $ops, FileBackendStore $backend ) {
* Substitute the backend of storage paths with an internal backend's name
*
* @param array|string $paths List of paths or single string path
- * @param $backend FileBackendStore
+ * @param FileBackendStore $backend
* @return Array|string
*/
protected function substPaths( $paths, FileBackendStore $backend ) {
/**
* @see FileBackend::doSecure()
- * @param $params array
+ * @param array $params
* @return Status
*/
protected function doSecure( array $params ) {
/**
* @see FileBackend::doPublish()
- * @param $params array
+ * @param array $params
* @return Status
*/
protected function doPublish( array $params ) {
/**
* @see FileBackend::doClean()
- * @param $params array
+ * @param array $params
* @return Status
*/
protected function doClean( array $params ) {
/**
* @see FileBackend::concatenate()
- * @param $params array
+ * @param array $params
* @return Status
*/
public function concatenate( array $params ) {
/**
* @see FileBackend::fileExists()
- * @param $params array
+ * @param array $params
* @return bool|null
*/
public function fileExists( array $params ) {
/**
* @see FileBackend::getFileTimestamp()
- * @param $params array
+ * @param array $params
* @return bool|string
*/
public function getFileTimestamp( array $params ) {
/**
* @see FileBackend::getFileSize()
- * @param $params array
+ * @param array $params
* @return bool|int
*/
public function getFileSize( array $params ) {
/**
* @see FileBackend::getFileStat()
- * @param $params array
+ * @param array $params
* @return Array|bool|null
*/
public function getFileStat( array $params ) {
/**
* @see FileBackend::getFileContentsMulti()
- * @param $params array
+ * @param array $params
* @return bool|string
*/
public function getFileContentsMulti( array $params ) {
/**
* @see FileBackend::getFileSha1Base36()
- * @param $params array
+ * @param array $params
* @return bool|string
*/
public function getFileSha1Base36( array $params ) {
/**
* @see FileBackend::getFileProps()
- * @param $params array
+ * @param array $params
* @return Array
*/
public function getFileProps( array $params ) {
/**
* @see FileBackend::streamFile()
- * @param $params array
+ * @param array $params
* @return \Status
*/
public function streamFile( array $params ) {
/**
* @see FileBackend::getLocalReferenceMulti()
- * @param $params array
+ * @param array $params
* @return FSFile|null
*/
public function getLocalReferenceMulti( array $params ) {
/**
* @see FileBackend::getLocalCopyMulti()
- * @param $params array
+ * @param array $params
* @return null|TempFSFile
*/
public function getLocalCopyMulti( array $params ) {
/**
* @see FileBackend::directoryExists()
- * @param $params array
+ * @param array $params
* @return bool|null
*/
public function directoryExists( array $params ) {
/**
* @see FileBackend::getSubdirectoryList()
- * @param $params array
+ * @param array $params
* @return Array|null|Traversable
*/
public function getDirectoryList( array $params ) {
/**
* @see FileBackend::getFileList()
- * @param $params array
+ * @param array $params
* @return Array|null|\Traversable
*/
public function getFileList( array $params ) {
/**
* @see FileBackend::__construct()
*
- * @param $config Array
+ * @param array $config
*/
public function __construct( array $config ) {
parent::__construct( $config );
* written under it, and that any file already there is writable.
* Backends using key/value stores should check if the container exists.
*
- * @param $storagePath string
+ * @param string $storagePath
* @return bool
*/
abstract public function isPathUsableInternal( $storagePath );
* Check if a container name is valid.
* This checks for for length and illegal characters.
*
- * @param $container string
+ * @param string $container
* @return bool
*/
final protected static function isValidContainerName( $container ) {
* this means that the path can only refer to a directory and can only
* be scanned by looking in all the container shards.
*
- * @param $storagePath string
+ * @param string $storagePath
* @return Array (container, path, container suffix) or (null, null, null) if invalid
*/
final protected function resolveStoragePath( $storagePath ) {
*
* @see FileBackendStore::resolveStoragePath()
*
- * @param $storagePath string
+ * @param string $storagePath
* @return Array (container, path) or (null, null) if invalid
*/
final protected function resolveStoragePathReal( $storagePath ) {
* If greater than 0, then all file storage paths within
* the container are required to be hashed accordingly.
*
- * @param $container string
+ * @param string $container
* @return Array (integer levels, integer base, repeat flag) or (0, 0, false)
*/
final protected function getContainerHashLevels( $container ) {
/**
* Get a list of full container shard suffixes for a container
*
- * @param $container string
+ * @param string $container
* @return Array
*/
final protected function getContainerSuffixes( $container ) {
/**
* Get the full container name, including the wiki ID prefix
*
- * @param $container string
+ * @param string $container
* @return string
*/
final protected function fullContainerName( $container ) {
* This is intended for internal use, such as encoding illegal chars.
* Subclasses can override this to be more restrictive.
*
- * @param $container string
+ * @param string $container
* @return string|null
*/
protected function resolveContainerName( $container ) {
* used in a list of container names, storage paths, or FileOp objects.
* This loads the persistent cache values into the process cache.
*
- * @param $items Array
+ * @param Array $items
* @return void
*/
final protected function primeContainerCache( array $items ) {
protected $multiShardPaths = array(); // (rel path => 1)
/**
- * @param $backend FileBackendStore
+ * @param FileBackendStore $backend
* @param string $container Full storage container name
* @param string $dir Storage directory relative to container
* @param array $suffixes List of container shard suffixes
/**
* Build a new batch file operation transaction
*
- * @param $backend FileBackendStore
- * @param $params Array
+ * @param FileBackendStore $backend
+ * @param Array $params
* @throws MWException
*/
final public function __construct( FileBackendStore $backend, array $params ) {
/**
* Normalize $item or anything in $item that is a valid storage path
*
- * @param $item string|array
+ * @param string $item|array
* @return string|Array
*/
protected function normalizeAnyStoragePaths( $item ) {
/**
* Normalize a string if it is a valid storage path
*
- * @param $path string
+ * @param string $path
* @return string
*/
protected static function normalizeIfValidStoragePath( $path ) {
/**
* Set the batch UUID this operation belongs to
*
- * @param $batchId string
+ * @param string $batchId
* @return void
*/
final public function setBatchId( $batchId ) {
/**
* Get the value of the parameter with the given name
*
- * @param $name string
+ * @param string $name
* @return mixed Returns null if the parameter is not set
*/
final public function getParam( $name ) {
* This must update $predicates for each path that the op can change
* except when a failing status object is returned.
*
- * @param $predicates Array
+ * @param Array $predicates
* @return Status
*/
final public function precheck( array &$predicates ) {
/**
* Adjust params to FileBackendStore internal file calls
*
- * @param $params Array
+ * @param Array $params
* @return Array (required params list, optional params list)
*/
protected function setFlags( array $params ) {
* Also set the destExists, overwriteSameCase and sourceSha1 member variables.
* A bad status will be returned if there is no chance it can be overwritten.
*
- * @param $predicates Array
+ * @param Array $predicates
* @return Status
*/
protected function precheckDestExistence( array $predicates ) {
* Check if a file will exist in storage when this operation is attempted
*
* @param string $source Storage path
- * @param $predicates Array
+ * @param Array $predicates
* @return bool
*/
final protected function fileExists( $source, array $predicates ) {
* Get the SHA-1 of a file in storage when this operation is attempted
*
* @param string $source Storage path
- * @param $predicates Array
+ * @param Array $predicates
* @return string|bool False on failure
*/
final protected function fileSha1( $source, array $predicates ) {
/**
* Log a file operation failure and preserve any temp files
*
- * @param $action string
+ * @param string $action
* @return void
*/
final public function logFailure( $action ) {
*
* @param array $performOps List of FileOp operations
* @param array $opts Batch operation options
- * @param $journal FileJournal Journal to log operations to
+ * @param FileJournal $journal Journal to log operations to
* @return Status
*/
public static function attempt( array $performOps, array $opts, FileJournal $journal ) {
* within any given sub-batch do not depend on each other.
* This will abort remaining ops on failure.
*
- * @param $pPerformOps Array
- * @param $status Status
+ * @param Array $pPerformOps
+ * @param Status $status
* @return bool Success
*/
protected static function runParallelBatches( array $pPerformOps, Status $status ) {
}
/**
- * @param $headers array
+ * @param array $headers
* @return array
*/
protected function sanitizeHdrs( array $headers ) {
}
/**
- * @param $disposition string Content-Disposition header value
+ * @param string $disposition Content-Disposition header value
* @return string Truncated Content-Disposition header value to meet Swift limits
*/
protected function truncDisp( $disposition ) {
/**
* Fill in any missing object metadata and save it to Swift
*
- * @param $obj CF_Object
+ * @param CF_Object $obj
* @param string $path Storage path to object
* @return bool Success
* @throws Exception cloudfiles exceptions
* @param string $fullCont Resolved container name
* @param string $dir Resolved storage directory with no trailing slash
* @param string|null $after Storage path of file to list items after
- * @param $limit integer Max number of items to list
+ * @param integer $limit Max number of items to list
* @param array $params Parameters for getDirectoryList()
* @return Array List of resolved paths of directories directly under $dir
*/
* @param string $fullCont Resolved container name
* @param string $dir Resolved storage directory with no trailing slash
* @param string|null $after Storage path of file to list items after
- * @param $limit integer Max number of items to list
+ * @param integer $limit Max number of items to list
* @param array $params Parameters for getDirectoryList()
* @return Array List of resolved paths of files under $dir
*/
* In general, we don't allow listings to end-users. It's not useful, isn't well-defined
* (lists are truncated to 10000 item with no way to page), and is just a performance risk.
*
- * @param $contObj CF_Container Swift container
+ * @param CF_Container $contObj Swift container
* @param array $readGrps List of read access routes
* @param array $writeGrps List of write access routes
* @return Status
/**
* Get the cache key for a container
*
- * @param $username string
+ * @param string $username
* @return string
*/
private function getCredsCacheKey( $username ) {
* Log an unexpected exception for this backend.
* This also sets the Status object to have a fatal error.
*
- * @param $e Exception
- * @param $status Status|null
- * @param $func string
+ * @param Exception $e
+ * @param Status $status|null
+ * @param string $func
* @param array $params
* @return void
*/
/** @var Array */
public $affectedObjects = array();
- public function __construct( $backend, array $params, $call, CF_Async_Op $cfOp ) {
+ /**
+ * @param SwiftFileBackend $backend
+ * @param array $params
+ * @param string $call
+ * @param CF_Async_Op $cfOp
+ */
+ public function __construct(
+ SwiftFileBackend $backend, array $params, $call, CF_Async_Op $cfOp
+ ) {
$this->backend = $backend;
$this->params = $params;
$this->call = $call;
const PAGE_SIZE = 9000; // file listing buffer size
/**
- * @param $backend SwiftFileBackend
+ * @param SwiftFileBackend $backend
* @param string $fullCont Resolved container name
* @param string $dir Resolved directory relative to container
* @param array $params
*
* @param string $container Resolved container name
* @param string $dir Resolved path relative to container
- * @param $after string|null
- * @param $limit integer
+ * @param string $after|null
+ * @param integer $limit
* @param array $params
* @return Traversable|Array|null Returns null on failure
*/
* Make a new temporary file on the file system.
* Temporary files may be purged when the file object falls out of scope.
*
- * @param $prefix string
- * @param $extension string
+ * @param string $prefix
+ * @param string $extension
* @return TempFSFile|null
*/
public static function factory( $prefix, $extension = '' ) {
/**
* Clean up the temporary file only after an object goes out of scope
*
- * @param $object Object
+ * @param Object $object
* @return TempFSFile This object
*/
public function bind( $object ) {
dépôts / lhc / web / wiklou.git / commitdiff