Page MenuHomePhabricator
Diviner Phabricator Tech Docs PhabricatorFileStorageEngine

abstract class PhabricatorFileStorageEngine
Phabricator Technical Documentation (Files)

Defines a storage engine which can write file data somewhere (like a database, local disk, Amazon S3, the A:\ drive, or a custom filer) and retrieve it later.

You can extend this class to provide new file storage backends.

For more information, see File Storage Technical Documentation.

Tasks

Constructing an Engine

  • final public function __construct() — Construct a new storage engine.

Engine Metadata

  • abstract public function getEngineIdentifier() — Return a unique, nonempty string which identifies this storage engine. This is used to look up the storage engine when files needs to be read or deleted. For instance, if you store files by giving them to a duck for safe keeping in his nest down by the pond, you might return 'duck' from this method.
  • abstract public function getEnginePriority() — Prioritize this engine relative to other engines.
  • abstract public function canWriteFiles() — Return `true` if the engine is currently writable.
  • public function hasFilesizeLimit() — Return `true` if the engine has a filesize limit on storable files.
  • public function getFilesizeLimit() — Return maximum storable file size, in bytes.
  • public function isTestEngine() — Identifies storage engines that support unit tests.
  • public function isChunkEngine() — Identifies chunking storage engines.

Managing File Data

  • abstract public function writeFile($data, $params) — Write file data to the backing storage and return a handle which can later be used to read or delete it. For example, if the backing storage is local disk, the handle could be the path to the file.
  • abstract public function readFile($handle) — Read the contents of a file previously written by @{method:writeFile}.
  • abstract public function deleteFile($handle) — Delete the data for a file previously written by @{method:writeFile}.

Loading Storage Engines

Other Methods

Methods

final public function __construct()

Construct a new storage engine.

Return
this//Implicit.//

abstract public function getEngineIdentifier()

Return a unique, nonempty string which identifies this storage engine. This is used to look up the storage engine when files needs to be read or deleted. For instance, if you store files by giving them to a duck for safe keeping in his nest down by the pond, you might return 'duck' from this method.

Return
stringUnique string for this engine, max length 32.

abstract public function getEnginePriority()

Prioritize this engine relative to other engines.

Engines with a smaller priority number get an opportunity to write files first. Generally, lower-latency filestores should have lower priority numbers, and higher-latency filestores should have higher priority numbers. Setting priority to approximately the number of milliseconds of read latency will generally produce reasonable results.

In conjunction with filesize limits, the goal is to store small files like profile images, thumbnails, and text snippets in lower-latency engines, and store large files in higher-capacity engines.

Return
floatEngine priority.

abstract public function canWriteFiles()

Return true if the engine is currently writable.

Engines that are disabled or missing configuration should return false to prevent new writes. If writes were made with this engine in the past, the application may still try to perform reads.

Return
boolTrue if this engine can support new writes.

public function hasFilesizeLimit()

Return true if the engine has a filesize limit on storable files.

The getFilesizeLimit() method can retrieve the actual limit. This method just removes the ambiguity around the meaning of a 0 limit.

Return
bool`true` if the engine has a filesize limit.

public function getFilesizeLimit()

Return maximum storable file size, in bytes.

Not all engines have a limit; use getFilesizeLimit() to check if an engine has a limit. Engines without a limit can store files of any size.

By default, engines define a limit which supports chunked storage of large files. In most cases, you should not change this limit, even if an engine has vast storage capacity: chunked storage makes large files more manageable and enables features like resumable uploads.

Return
intMaximum storable file size, in bytes.

public function isTestEngine()

Identifies storage engines that support unit tests.

These engines are not used for production writes.

Return
boolTrue if this is a test engine.

public function isChunkEngine()

Identifies chunking storage engines.

If this is a storage engine which splits files into chunks and stores the chunks in other engines, it can return true to signal that other chunking engines should not try to store data here.

Return
boolTrue if this is a chunk engine.

abstract public function writeFile($data, $params)

Write file data to the backing storage and return a handle which can later be used to read or delete it. For example, if the backing storage is local disk, the handle could be the path to the file.

The caller will provide a $params array, which may be empty or may have some metadata keys (like "name" and "author") in it. You should be prepared to handle writes which specify no metadata, but might want to optionally use some keys in this array for debugging or logging purposes. This is the same dictionary passed to PhabricatorFile::newFromFileData(), so you could conceivably do custom things with it.

If you are unable to write for whatever reason (e.g., the disk is full), throw an exception. If there are other satisfactory but less-preferred storage engines available, they will be tried.

Parameters
string$dataThe file data to write.
array$paramsFile metadata (name, author), if available.
Return
stringUnique string which identifies the stored file, max length 255.

abstract public function readFile($handle)

Read the contents of a file previously written by writeFile().

Parameters
string$handleThe handle returned from @{method:writeFile} when the file was written.
Return
stringFile contents.

abstract public function deleteFile($handle)

Delete the data for a file previously written by writeFile().

Parameters
string$handleThe handle returned from @{method:writeFile} when the file was written.
Return
void

public static function loadStorageEngines($length)

Select viable default storage engines according to configuration. We'll select the MySQL and Local Disk storage engines if they are configured to allow a given file.

Parameters
int$lengthFile size in bytes.
Return
wild

public static function loadAllEngines()

This method is not documented.
Return
wild

private static function loadProductionEngines()

This method is not documented.
Return
wild

public static function loadWritableEngines()

This method is not documented.
Return
wild

public static function loadWritableChunkEngines()

This method is not documented.
Return
wild

public static function getChunkThreshold()

Return the largest file size which can not be uploaded in chunks.

Files smaller than this will always upload in one request, so clients can safely skip the allocation step.

Return
int|nullByte size, or `null` if there is no chunk support.

public function getRawFileDataIterator($file, $begin, $end, $format)

This method is not documented.
Parameters
PhabricatorFile$file
$begin
$end
PhabricatorFileStorageFormat$format
Return
wild

public function newIntegrityHash($data, $format)

This method is not documented.
Parameters
$data
PhabricatorFileStorageFormat$format
Return
wild