includes/filebackend/filejournal/FileJournal.php

   1 <?php
   2 /**
   3  * @defgroup FileJournal File journal
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * File operation journaling.
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @file
  26  * @ingroup FileJournal
  27  * @author Aaron Schulz
  28  */
  29
  30 /**
  31  * @brief Class for handling file operation journaling.
  32  *
  33  * Subclasses should avoid throwing exceptions at all costs.
  34  *
  35  * @ingroup FileJournal
  36  * @since 1.20
  37  */
  38 abstract class FileJournal {
  39         protected $backend; // string
  40         protected $ttlDays; // integer
  41
  42         /**
  43          * Construct a new instance from configuration.
  44          * $config includes:
  45          *     'ttlDays' : days to keep log entries around (false means "forever")
  46          *
  47          * @param $config Array
  48          */
  49         protected function __construct( array $config ) {
  50                 $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  51         }
  52
  53         /**
  54          * Create an appropriate FileJournal object from config
  55          *
  56          * @param $config Array
  57          * @param $backend string A registered file backend name
  58          * @throws MWException
  59          * @return FileJournal
  60          */
  61         final public static function factory( array $config, $backend ) {
  62                 $class = $config['class'];
  63                 $jrn = new $class( $config );
  64                 if ( !$jrn instanceof self ) {
  65                         throw new MWException( "Class given is not an instance of FileJournal." );
  66                 }
  67                 $jrn->backend = $backend;
  68                 return $jrn;
  69         }
  70
  71         /**
  72          * Get a statistically unique ID string
  73          *
  74          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  75          */
  76         final public function getTimestampedUUID() {
  77                 $s = '';
  78                 for ( $i = 0; $i < 5; $i++ ) {
  79                         $s .= mt_rand( 0, 2147483647 );
  80                 }
  81                 $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
  82                 return substr( wfBaseConvert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  83         }
  84
  85         /**
  86          * Log changes made by a batch file operation.
  87          * $entries is an array of log entries, each of which contains:
  88          *     op      : Basic operation name (create, store, copy, delete)
  89          *     path    : The storage path of the file
  90          *     newSha1 : The final base 36 SHA-1 of the file
  91          * Note that 'false' should be used as the SHA-1 for non-existing files.
  92          *
  93          * @param $entries Array List of file operations (each an array of parameters)
  94          * @param $batchId string UUID string that identifies the operation batch
  95          * @return Status
  96          */
  97         final public function logChangeBatch( array $entries, $batchId ) {
  98                 if ( !count( $entries ) ) {
  99                         return Status::newGood();
 100                 }
 101                 return $this->doLogChangeBatch( $entries, $batchId );
 102         }
 103
 104         /**
 105          * @see FileJournal::logChangeBatch()
 106          *
 107          * @param $entries Array List of file operations (each an array of parameters)
 108          * @param $batchId string UUID string that identifies the operation batch
 109          * @return Status
 110          */
 111         abstract protected function doLogChangeBatch( array $entries, $batchId );
 112
 113         /**
 114          * Get an array of file change log entries.
 115          * A starting change ID and/or limit can be specified.
 116          *
 117          * The result as a list of associative arrays, each having:
 118          *     id         : unique, monotonic, ID for this change
 119          *     batch_uuid : UUID for an operation batch
 120          *     backend    : the backend name
 121          *     op         : primitive operation (create,update,delete,null)
 122          *     path       : affected storage path
 123          *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 124          *     timestamp  : TS_MW timestamp of the batch change
 125
 126          * Also, $next is updated to the ID of the next entry.
 127          *
 128          * @param $start integer Starting change ID or null
 129          * @param $limit integer Maximum number of items to return
 130          * @param &$next string
 131          * @return Array
 132          */
 133         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 134                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 135                 if ( $limit && count( $entries ) > $limit ) {
 136                         $last = array_pop( $entries ); // remove the extra entry
 137                         $next = $last['id']; // update for next call
 138                 } else {
 139                         $next = null; // end of list
 140                 }
 141                 return $entries;
 142         }
 143
 144         /**
 145          * @see FileJournal::getChangeEntries()
 146          * @return Array
 147          */
 148         abstract protected function doGetChangeEntries( $start, $limit );
 149
 150         /**
 151          * Purge any old log entries
 152          *
 153          * @return Status
 154          */
 155         final public function purgeOldLogs() {
 156                 return $this->doPurgeOldLogs();
 157         }
 158
 159         /**
 160          * @see FileJournal::purgeOldLogs()
 161          * @return Status
 162          */
 163         abstract protected function doPurgeOldLogs();
 164 }
 165
 166 /**
 167  * Simple version of FileJournal that does nothing
 168  * @since 1.20
 169  */
 170 class NullFileJournal extends FileJournal {
 171         /**
 172          * @see FileJournal::logChangeBatch()
 173          * @param $entries array
 174          * @param $batchId string
 175          * @return Status
 176          */
 177         protected function doLogChangeBatch( array $entries, $batchId ) {
 178                 return Status::newGood();
 179         }
 180
 181         /**
 182          * @see FileJournal::doGetChangeEntries()
 183          * @return Array
 184          */
 185         protected function doGetChangeEntries( $start, $limit ) {
 186                 return array();
 187         }
 188
 189         /**
 190          * @see FileJournal::purgeOldLogs()
 191          * @return Status
 192          */
 193         protected function doPurgeOldLogs() {
 194                 return Status::newGood();
 195         }
 196 }