includes/filerepo/backend/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          * @return FileJournal
  59          */
  60         final public static function factory( array $config, $backend ) {
  61                 $class = $config['class'];
  62                 $jrn = new $class( $config );
  63                 if ( !$jrn instanceof self ) {
  64                         throw new MWException( "Class given is not an instance of FileJournal." );
  65                 }
  66                 $jrn->backend = $backend;
  67                 return $jrn;
  68         }
  69
  70         /**
  71          * Get a statistically unique ID string
  72          *
  73          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  74          */
  75         final public function getTimestampedUUID() {
  76                 $s = '';
  77                 for ( $i = 0; $i < 5; $i++ ) {
  78                         $s .= mt_rand( 0, 2147483647 );
  79                 }
  80                 $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
  81                 return substr( wfBaseConvert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  82         }
  83
  84         /**
  85          * Log changes made by a batch file operation.
  86          * $entries is an array of log entries, each of which contains:
  87          *     op      : Basic operation name (create, store, copy, delete)
  88          *     path    : The storage path of the file
  89          *     newSha1 : The final base 36 SHA-1 of the file
  90          * Note that 'false' should be used as the SHA-1 for non-existing files.
  91          *
  92          * @param $entries Array List of file operations (each an array of parameters)
  93          * @param $batchId string UUID string that identifies the operation batch
  94          * @return Status
  95          */
  96         final public function logChangeBatch( array $entries, $batchId ) {
  97                 if ( !count( $entries ) ) {
  98                         return Status::newGood();
  99                 }
 100                 return $this->doLogChangeBatch( $entries, $batchId );
 101         }
 102
 103         /**
 104          * @see FileJournal::logChangeBatch()
 105          *
 106          * @param $entries Array List of file operations (each an array of parameters)
 107          * @param $batchId string UUID string that identifies the operation batch
 108          * @return Status
 109          */
 110         abstract protected function doLogChangeBatch( array $entries, $batchId );
 111
 112         /**
 113          * Purge any old log entries
 114          *
 115          * @return Status
 116          */
 117         final public function purgeOldLogs() {
 118                 return $this->doPurgeOldLogs();
 119         }
 120
 121         /**
 122          * @see FileJournal::purgeOldLogs()
 123          * @return Status
 124          */
 125         abstract protected function doPurgeOldLogs();
 126 }
 127
 128 /**
 129  * Simple version of FileJournal that does nothing
 130  * @since 1.20
 131  */
 132 class NullFileJournal extends FileJournal {
 133         /**
 134          * @see FileJournal::logChangeBatch()
 135          * @return Status
 136          */
 137         protected function doLogChangeBatch( array $entries, $batchId ) {
 138                 return Status::newGood();
 139         }
 140
 141         /**
 142          * @see FileJournal::purgeOldLogs()
 143          * @return Status
 144          */
 145         protected function doPurgeOldLogs() {
 146                 return Status::newGood();
 147         }
 148 }