* @since 1.19
*/
abstract class FileBackend {
- protected $name; // string; unique backend name
- protected $wikiId; // string; unique wiki name
- protected $readOnly; // string; read-only explanation message
- protected $parallelize; // string; when to do operations in parallel
- protected $concurrency; // integer; how many operations can be done in parallel
+ /** @var string Unique backend name */
+ protected $name;
+
+ /** @var string Unique wiki name */
+ protected $wikiId;
+
+ /** @var string Read-only explanation message */
+ protected $readOnly;
+
+ /** @var string When to do operations in parallel */
+ protected $parallelize;
+
+ /** @var int How many operations can be done in parallel */
+ protected $concurrency;
/** @var LockManager */
protected $lockManager;
+
/** @var FileJournal */
protected $fileJournal;
* Create a new backend instance from configuration.
* This should only be called from within FileBackendGroup.
*
- * $config includes:
+ * @param 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 (e.g. with journaling).
* - 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.
- *
- * @param array $config
* @throws MWException
*/
public function __construct( array $config ) {
* otherwise safe from modification from other processes. Normally,
* the file will be a new temp file, which should be adequate.
*
- * @param array $params Operation parameters
- * $params include:
+ * @param 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
* However, setting them is not guaranteed to actually do anything.
* Additional server configuration may be needed to achieve the desired effect.
*
- * @param array $params
- * $params include:
+ * @param 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)
* This is not guaranteed to actually make files or listings publically hidden.
* Additional server configuration may be needed to achieve the desired effect.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - dir : storage directory
* - noAccess : try to deny file access
* - noListing : try to deny file listing
* This is not guaranteed to actually make files or listings publically viewable.
* Additional server configuration may be needed to achieve the desired effect.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - dir : storage directory
* - access : try to allow file access
* - listing : try to allow file listing
* Backends using key/value stores may do nothing unless the directory
* is that of an empty container, in which case it will be deleted.
*
- * @param array $params
- * $params include:
+ * @param 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)
* @return ScopedCallback|null
*/
final protected function getScopedPHPBehaviorForOps() {
- if ( php_sapi_name() != 'cli' ) { // http://bugs.php.net/bug.php?id=47540
+ if ( PHP_SAPI != 'cli' ) { // http://bugs.php.net/bug.php?id=47540
$old = ignore_user_abort( true ); // avoid half-finished operations
- return new ScopedCallback( function() use ( $old ) {
+ return new ScopedCallback( function () use ( $old ) {
ignore_user_abort( $old );
} );
}
+
return null;
}
* Check if a file exists at a storage path in the backend.
* This returns false if only a directory exists at the path.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
* @return bool|null Returns null on failure
/**
* Get the last-modified timestamp of the file at a storage path.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
* @return string|bool TS_MW timestamp or false on failure
* Get the contents of a file at a storage path in the backend.
* This should be avoided for potentially large files.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
* @return string|bool Returns false on failure
*
* @see FileBackend::getFileContents()
*
- * @param array $params
- * $params include:
+ * @param 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
- * @return Array Map of (path name => string or false on failure)
+ * @return array Map of (path name => string or false on failure)
* @since 1.20
*/
abstract public function getFileContentsMulti( array $params );
/**
* Get the size (bytes) of a file at a storage path in the backend.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
- * @return integer|bool Returns false on failure
+ * @return int|bool Returns false on failure
*/
abstract public function getFileSize( array $params );
* - size : the file size (bytes)
* Additional values may be included for internal use only.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
- * @return Array|bool|null Returns null on failure
+ * @return array|bool|null Returns null on failure
*/
abstract public function getFileStat( array $params );
/**
* Get a SHA-1 hash of the file at a storage path in the backend.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
* @return string|bool Hash string or false on failure
* Get the properties of the file at a storage path in the backend.
* This gives the result of FSFile::getProps() on a local copy of the file.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
- * @return Array Returns FSFile::placeholderProps() on failure
+ * @return array Returns FSFile::placeholderProps() on failure
*/
abstract public function getFileProps( array $params );
* will be sent if streaming began, while none will be sent otherwise.
* Implementations should flush the output buffer before sending data.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - headers : list of additional HTTP headers to send on success
* - latest : use the latest available data
* In that later case, there are copies of the file that must stay in sync.
* Additionally, further calls to this function may return the same file.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
* @return FSFile|null Returns null on failure
*
* @see FileBackend::getLocalReference()
*
- * @param array $params
- * $params include:
+ * @param 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
- * @return Array Map of (path name => FSFile or null on failure)
+ * @return array Map of (path name => FSFile or null on failure)
* @since 1.20
*/
abstract public function getLocalReferenceMulti( array $params );
* 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.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - latest : use the latest available data
* @return TempFSFile|null Returns null on failure
*
* @see FileBackend::getLocalCopy()
*
- * @param array $params
- * $params include:
+ * @param 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
- * @return Array Map of (path name => TempFSFile or null on failure)
+ * @return array Map of (path name => TempFSFile or null on failure)
* @since 1.20
*/
abstract public function getLocalCopyMulti( array $params );
* Otherwise, one would need to use getLocalReference(), which involves loading
* the entire file on to local disk.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - src : source storage path
* - ttl : lifetime (seconds) if pre-authenticated; default is 1 day
* @return string|null
*
* Storage backends with eventual consistency might return stale data.
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - dir : storage directory
* @return bool|null Returns null on failure
* @since 1.20
*
* Failures during iteration can result in FileBackendError exceptions (since 1.22).
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - dir : storage directory
* - topOnly : only return direct child dirs of the directory
* @return Traversable|Array|null Returns null on failure
*
* Failures during iteration can result in FileBackendError exceptions (since 1.22).
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - dir : storage directory
* @return Traversable|Array|null Returns null on failure
* @since 1.20
*
* Failures during iteration can result in FileBackendError exceptions (since 1.22).
*
- * @param array $params
- * $params include:
+ * @param 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)
*
* Failures during iteration can result in FileBackendError exceptions (since 1.22).
*
- * @param array $params
- * $params include:
+ * @param array $params Parameters include:
* - dir : storage directory
* - adviseStat : set to true if stat requests will be made on the files (since 1.22)
* @return Traversable|Array|null Returns null on failure
* This should be used when stat calls will be made on a known list of a many files.
*
* @param array $paths Storage paths
- * @return void
*/
- public function preloadCache( array $paths ) {}
+ public function preloadCache( array $paths ) {
+ }
/**
* Invalidate any in-process file stat and property cache.
* If $paths is given, then only the cache for those files will be cleared.
*
* @param array $paths Storage paths (optional)
- * @return void
*/
- public function clearCache( array $paths = null ) {}
+ public function clearCache( array $paths = null ) {
+ }
/**
* Lock the files at the given storage paths in the backend.
* Callers should consider using getScopedFileLocks() instead.
*
* @param array $paths Storage paths
- * @param integer $type LockManager::LOCK_* constant
+ * @param int $type LockManager::LOCK_* constant
* @return Status
*/
final public function lockFiles( array $paths, $type ) {
$paths = array_map( 'FileBackend::normalizeStoragePath', $paths );
+
return $this->lockManager->lock( $paths, $type );
}
* Unlock the files at the given storage paths in the backend.
*
* @param array $paths Storage paths
- * @param integer $type LockManager::LOCK_* constant
+ * @param int $type LockManager::LOCK_* constant
* @return Status
*/
final public function unlockFiles( array $paths, $type ) {
$paths = array_map( 'FileBackend::normalizeStoragePath', $paths );
+
return $this->lockManager->unlock( $paths, $type );
}
* Once the return value goes out scope, the locks will be released and
* the status updated. Unlock fatals will not change the status "OK" value.
*
- * @param array $paths Storage paths
- * @param integer $type LockManager::LOCK_* constant
+ * @see ScopedLock::factory()
+ *
+ * @param array $paths List of storage paths or map of lock types to path lists
+ * @param int|string $type LockManager::LOCK_* constant or "mixed"
* @param Status $status Status to update on lock/unlock
* @return ScopedLock|null Returns null on failure
*/
} else {
$paths = array_map( 'FileBackend::normalizeStoragePath', $paths );
}
+
return ScopedLock::factory( $this->lockManager, $paths, $type, $status );
}
*
* @param array $ops List of file operations to FileBackend::doOperations()
* @param Status $status Status to update on lock/unlock
- * @return Array List of ScopedFileLocks or null values
+ * @return array List of ScopedFileLocks or null values
* @since 1.20
*/
abstract public function getScopedLocksForOps( array $ops, Status $status );
* This does not do any path normalization or traversal checks.
*
* @param string $storagePath
- * @return Array (backend, container, rel object) or (null, null, null)
+ * @return array (backend, container, rel object) or (null, null, null)
*/
final public static function splitStoragePath( $storagePath ) {
if ( self::isStoragePath( $storagePath ) ) {
}
}
}
+
return array( null, null, null );
}
: "mwstore://{$backend}/{$container}";
}
}
+
return null;
}
final public static function parentStoragePath( $storagePath ) {
$storagePath = dirname( $storagePath );
list( , , $rel ) = self::splitStoragePath( $storagePath );
+
return ( $rel === null ) ? null : $storagePath;
}
*/
final public static function extensionFromPath( $path ) {
$i = strrpos( $path, '.' );
+
return strtolower( $i ? substr( $path, $i + 1 ) : '' );
}
return null;
}
}
+
return $path;
}
}
* @ingroup FileBackend
* @since 1.22
*/
-class FileBackendError extends MWException {}
+class FileBackendError extends MWException {
+}
dépôts / lhc / web / wiklou.git / blobdiff