files.diviner

@title File Storage Technical Documentation
@group filestorage

Phabricator file storage details.

= Overview =

Phabricator has a simple, general-purpose file storage system with configurable
storage backends that allows you to choose where files are stored. For a user
guide, see @{article:Configuring File Storage}.

= Class Relationships =

@{class:PhabricatorFile} holds file metadata (name, author, phid), including an
identifier for a @{class:PhabricatorFileStorageEngine} where the actual file
data is stored, and a data handle which identifies the data within that storage
engine.

When writing data, a @{class:PhabricatorFileStorageEngineSelector} is
instantiated (by default, @{class:PhabricatorDefaultFileStorageEngineSelector},
but you can change this by setting the ##storage.engine-selector## key in your
configuration). The selector returns a list of satisfactory
@{class:PhabricatorFileStorageEngine}s, in order of preference.

For instance, suppose the user is uploading a picture. The upload pipeline would
instantiate the configured selector, which might return a
@{class:PhabricatorMySQLFileStorageEngine} and a
@{class:PhabricatorLocalDiskFileStorageEngine}, indicating that the picture may
be stored in either storage engine but MySQL is preferred. If a given storage
engine fails to perform the write, it will fall back to the next engine.

= Adding New Storage Engines =

To add a new storage engine, extend @{class:PhabricatorFileStorageEngine}. In
order to make files actually get written to it, you also need to extend
@{class:PhabricatorFileStorageEngineSelector}, provide an implementation which
selects your storage engine for whatever files you want to store there, and then
configure Phabricator to use your selector by setting
##storage.engine-selector##.