includes/filerepo/backend/filejournal/FileJournal.php

   1 <?php
   2 /**
   3  * @defgroup FileJournal File journal
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * @file
   9  * @ingroup FileJournal
  10  * @author Aaron Schulz
  11  */
  12
  13 /**
  14  * @brief Class for handling file operation journaling.
  15  *
  16  * Subclasses should avoid throwing exceptions at all costs.
  17  *
  18  * @ingroup FileJournal
  19  * @since 1.20
  20  */
  21 abstract class FileJournal {
  22         protected $backend; // string
  23         protected $ttlDays; // integer
  24
  25         /**
  26          * Construct a new instance from configuration.
  27          * $config includes:
  28          *     'ttlDays' : days to keep log entries around (false means "forever")
  29          *
  30          * @param $config Array
  31          */
  32         protected function __construct( array $config ) {
  33                 $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  34         }
  35
  36         /**
  37          * Create an appropriate FileJournal object from config
  38          *
  39          * @param $config Array
  40          * @param $backend string A registered file backend name
  41          * @return FileJournal
  42          */
  43         final public static function factory( array $config, $backend ) {
  44                 $class = $config['class'];
  45                 $jrn = new $class( $config );
  46                 if ( !$jrn instanceof self ) {
  47                         throw new MWException( "Class given is not an instance of FileJournal." );
  48                 }
  49                 $jrn->backend = $backend;
  50                 return $jrn;
  51         }
  52
  53         /**
  54          * Get a statistically unique ID string
  55          *
  56          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  57          */
  58         final public function getTimestampedUUID() {
  59                 $s = '';
  60                 for ( $i = 0; $i < 5; $i++ ) {
  61                         $s .= mt_rand( 0, 2147483647 );
  62                 }
  63                 $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
  64                 return substr( wfBaseConvert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  65         }
  66
  67         /**
  68          * Log changes made by a batch file operation.
  69          * $entries is an array of log entries, each of which contains:
  70          *     op      : Basic operation name (create, store, copy, delete)
  71          *     path    : The storage path of the file
  72          *     newSha1 : The final base 36 SHA-1 of the file
  73          * Note that 'false' should be used as the SHA-1 for non-existing files.
  74          *
  75          * @param $entries Array List of file operations (each an array of parameters)
  76          * @param $batchId string UUID string that identifies the operation batch
  77          * @return Status
  78          */
  79         final public function logChangeBatch( array $entries, $batchId ) {
  80                 if ( !count( $entries ) ) {
  81                         return Status::newGood();
  82                 }
  83                 return $this->doLogChangeBatch( $entries, $batchId );
  84         }
  85
  86         /**
  87          * @see FileJournal::logChangeBatch()
  88          *
  89          * @param $entries Array List of file operations (each an array of parameters)
  90          * @param $batchId string UUID string that identifies the operation batch
  91          * @return Status
  92          */
  93         abstract protected function doLogChangeBatch( array $entries, $batchId );
  94
  95         /**
  96          * Purge any old log entries
  97          *
  98          * @return Status
  99          */
 100         final public function purgeOldLogs() {
 101                 return $this->doPurgeOldLogs();
 102         }
 103
 104         /**
 105          * @see FileJournal::purgeOldLogs()
 106          * @return Status
 107          */
 108         abstract protected function doPurgeOldLogs();
 109 }
 110
 111 /**
 112  * Simple version of FileJournal that does nothing
 113  * @since 1.20
 114  */
 115 class NullFileJournal extends FileJournal {
 116         /**
 117          * @see FileJournal::logChangeBatch()
 118          * @return Status
 119          */
 120         protected function doLogChangeBatch( array $entries, $batchId ) {
 121                 return Status::newGood();
 122         }
 123
 124         /**
 125          * @see FileJournal::purgeOldLogs()
 126          * @return Status
 127          */
 128         protected function doPurgeOldLogs() {
 129                 return Status::newGood();
 130         }
 131 }