[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Defines a storage engine which can write file data somewhere (like a
   5   * database, local disk, Amazon S3, the A:\ drive, or a custom filer) and
   6   * retrieve it later.
   7   *
   8   * You can extend this class to provide new file storage backends.
   9   *
  10   * For more information, see @{article:File Storage Technical Documentation}.
  11   *
  12   * @task construct Constructing an Engine
  13   * @task meta Engine Metadata
  14   * @task file Managing File Data
  15   */
  16  abstract class PhabricatorFileStorageEngine {
  17  
  18    /**
  19     * Construct a new storage engine.
  20     *
  21     * @task construct
  22     */
  23    final public function __construct() {
  24      // <empty>
  25    }
  26  
  27  
  28  /* -(  Engine Metadata  )---------------------------------------------------- */
  29  
  30  
  31    /**
  32     * Return a unique, nonempty string which identifies this storage engine.
  33     * This is used to look up the storage engine when files needs to be read or
  34     * deleted. For instance, if you store files by giving them to a duck for
  35     * safe keeping in his nest down by the pond, you might return 'duck' from
  36     * this method.
  37     *
  38     * @return string Unique string for this engine, max length 32.
  39     * @task meta
  40     */
  41    abstract public function getEngineIdentifier();
  42  
  43  
  44  /* -(  Managing File Data  )------------------------------------------------- */
  45  
  46  
  47    /**
  48     * Write file data to the backing storage and return a handle which can later
  49     * be used to read or delete it. For example, if the backing storage is local
  50     * disk, the handle could be the path to the file.
  51     *
  52     * The caller will provide a $params array, which may be empty or may have
  53     * some metadata keys (like "name" and "author") in it. You should be prepared
  54     * to handle writes which specify no metadata, but might want to optionally
  55     * use some keys in this array for debugging or logging purposes. This is
  56     * the same dictionary passed to @{method:PhabricatorFile::newFromFileData},
  57     * so you could conceivably do custom things with it.
  58     *
  59     * If you are unable to write for whatever reason (e.g., the disk is full),
  60     * throw an exception. If there are other satisfactory but less-preferred
  61     * storage engines available, they will be tried.
  62     *
  63     * @param  string The file data to write.
  64     * @param  array  File metadata (name, author), if available.
  65     * @return string Unique string which identifies the stored file, max length
  66     *                255.
  67     * @task file
  68     */
  69    abstract public function writeFile($data, array $params);
  70  
  71  
  72    /**
  73     * Read the contents of a file previously written by @{method:writeFile}.
  74     *
  75     * @param   string  The handle returned from @{method:writeFile} when the
  76     *                  file was written.
  77     * @return  string  File contents.
  78     * @task file
  79     */
  80    abstract public function readFile($handle);
  81  
  82  
  83    /**
  84     * Delete the data for a file previously written by @{method:writeFile}.
  85     *
  86     * @param   string  The handle returned from @{method:writeFile} when the
  87     *                  file was written.
  88     * @return  void
  89     * @task file
  90     */
  91    abstract public function deleteFile($handle);
  92  
  93  }