1: <?php
  2: /**
  3:  * This class defines the interface for all elgg data repositories.
  4:  *
  5:  * @package    Elgg.Core
  6:  * @subpackage DataStorage
  7:  * @class   ElggFilestore
  8:  */
  9: abstract class ElggFilestore {
 10:     /**
 11:      * Attempt to open the file $file for storage or writing.
 12:      *
 13:      * @param ElggFile $file A file
 14:      * @param string   $mode "read", "write", "append"
 15:      *
 16:      * @return mixed A handle to the opened file or false on error.
 17:      */
 18:     abstract public function open(ElggFile $file, $mode);
 19: 
 20:     /**
 21:      * Write data to a given file handle.
 22:      *
 23:      * @param mixed  $f    The file handle - exactly what this is depends on the file system
 24:      * @param string $data The binary string of data to write
 25:      *
 26:      * @return int Number of bytes written.
 27:      */
 28:     abstract public function write($f, $data);
 29: 
 30:     /**
 31:      * Read data from a filestore.
 32:      *
 33:      * @param mixed $f      The file handle
 34:      * @param int   $length Length in bytes to read.
 35:      * @param int   $offset The optional offset.
 36:      *
 37:      * @return mixed String of data or false on error.
 38:      */
 39:     abstract public function read($f, $length, $offset = 0);
 40: 
 41:     /**
 42:      * Seek a given position within a file handle.
 43:      *
 44:      * @param mixed $f        The file handle.
 45:      * @param int   $position The position.
 46:      *
 47:      * @return void
 48:      */
 49:     abstract public function seek($f, $position);
 50: 
 51:     /**
 52:      * Return a whether the end of a file has been reached.
 53:      *
 54:      * @param mixed $f The file handle.
 55:      *
 56:      * @return boolean
 57:      */
 58:     abstract public function eof($f);
 59: 
 60:     /**
 61:      * Return the current position in an open file.
 62:      *
 63:      * @param mixed $f The file handle.
 64:      *
 65:      * @return int
 66:      */
 67:     abstract public function tell($f);
 68: 
 69:     /**
 70:      * Close a given file handle.
 71:      *
 72:      * @param mixed $f The file handle
 73:      *
 74:      * @return bool
 75:      */
 76:     abstract public function close($f);
 77: 
 78:     /**
 79:      * Delete the file associated with a given file handle.
 80:      *
 81:      * @param ElggFile $file The file
 82:      *
 83:      * @return bool
 84:      */
 85:     abstract public function delete(ElggFile $file);
 86: 
 87:     /**
 88:      * Return the size in bytes for a given file.
 89:      *
 90:      * @param ElggFile $file The file
 91:      *
 92:      * @return int
 93:      */
 94:     abstract public function getFileSize(ElggFile $file);
 95: 
 96:     /**
 97:      * Return the filename of a given file as stored on the filestore.
 98:      *
 99:      * @param ElggFile $file The file
100:      *
101:      * @return string
102:      */
103:     abstract public function getFilenameOnFilestore(ElggFile $file);
104: 
105:     /**
106:      * Get the filestore's creation parameters as an associative array.
107:      * Used for serialisation and for storing the creation details along side a file object.
108:      *
109:      * @return array
110:      */
111:     abstract public function getParameters();
112: 
113:     /**
114:      * Set the parameters from the associative array produced by $this->getParameters().
115:      *
116:      * @param array $parameters A list of parameters
117:      *
118:      * @return bool
119:      */
120:     abstract public function setParameters(array $parameters);
121: 
122:     /**
123:      * Get the contents of the whole file.
124:      *
125:      * @param mixed $file The file handle.
126:      *
127:      * @return mixed The file contents.
128:      */
129:     abstract public function grabFile(ElggFile $file);
130: 
131:     /**
132:      * Return whether a file physically exists or not.
133:      *
134:      * @param ElggFile $file The file
135:      *
136:      * @return bool
137:      */
138:     abstract public function exists(ElggFile $file);
139: }
140: