includes/externalstore/ExternalStore.php

   1 <?php
   2 /**
   3  * @defgroup ExternalStorage ExternalStorage
   4  */
   5
   6 /**
   7  * Interface for data storage in external repositories.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  */
  26
  27 /**
  28  * Constructor class for key/value blob data kept in external repositories.
  29  *
  30  * Objects in external stores are defined by a special URL. The URL is of
  31  * the form "<store protocol>://<location>/<object name>". The protocol is used
  32  * to determine what ExternalStoreMedium class is used. The location identifies
  33  * particular storage instances or database clusters for store class to use.
  34  *
  35  * When an object is inserted into a store, the calling code uses a partial URL of
  36  * the form "<store protocol>://<location>" and receives the full object URL on success.
  37  * This is useful since object names can be sequential IDs, UUIDs, or hashes.
  38  * Callers are not responsible for unique name generation.
  39  *
  40  * External repositories might be populated by maintenance/async
  41  * scripts, thus partial moving of data may be possible, as well
  42  * as the possibility to have any storage format (i.e. for archives).
  43  *
  44  * @ingroup ExternalStorage
  45  */
  46 class ExternalStore {
  47         /**
  48          * Get an external store object of the given type, with the given parameters
  49          *
  50          * @param string $proto Type of external storage, should be a value in $wgExternalStores
  51          * @param array $params Associative array of ExternalStoreMedium parameters
  52          * @return ExternalStoreMedium|bool The store class or false on error
  53          */
  54         public static function getStoreObject( $proto, array $params = array() ) {
  55                 global $wgExternalStores;
  56
  57                 if ( !$wgExternalStores || !in_array( $proto, $wgExternalStores ) ) {
  58                         return false; // protocol not enabled
  59                 }
  60
  61                 $class = 'ExternalStore' . ucfirst( $proto );
  62                 // Any custom modules should be added to $wgAutoLoadClasses for on-demand loading
  63                 return class_exists( $class ) ? new $class( $params ) : false;
  64         }
  65
  66         /**
  67          * Fetch data from given URL
  68          *
  69          * @param string $url The URL of the text to get
  70          * @param array $params Associative array of ExternalStoreMedium parameters
  71          * @return string|bool The text stored or false on error
  72          * @throws MWException
  73          */
  74         public static function fetchFromURL( $url, array $params = array() ) {
  75                 $parts = explode( '://', $url, 2 );
  76                 if ( count( $parts ) != 2 ) {
  77                         return false; // invalid URL
  78                 }
  79
  80                 list( $proto, $path ) = $parts;
  81                 if ( $path == '' ) { // bad URL
  82                         return false;
  83                 }
  84
  85                 $store = self::getStoreObject( $proto, $params );
  86                 if ( $store === false ) {
  87                         return false;
  88                 }
  89
  90                 return $store->fetchFromURL( $url );
  91         }
  92
  93         /**
  94          * Store a data item to an external store, identified by a partial URL
  95          * The protocol part is used to identify the class, the rest is passed to the
  96          * class itself as a parameter.
  97          *
  98          * @param string $url A partial external store URL ("<store type>://<location>")
  99          * @param $data string
 100          * @param array $params Associative array of ExternalStoreMedium parameters
 101          * @return string|bool The URL of the stored data item, or false on error
 102          * @throws MWException
 103          */
 104         public static function insert( $url, $data, array $params = array() ) {
 105                 $parts = explode( '://', $url, 2 );
 106                 if ( count( $parts ) != 2 ) {
 107                         return false; // invalid URL
 108                 }
 109
 110                 list( $proto, $path ) = $parts;
 111                 if ( $path == '' ) { // bad URL
 112                         return false;
 113                 }
 114
 115                 $store = self::getStoreObject( $proto, $params );
 116                 if ( $store === false ) {
 117                         return false;
 118                 } else {
 119                         return $store->store( $path, $data );
 120                 }
 121         }
 122
 123         /**
 124          * Like insert() above, but does more of the work for us.
 125          * This function does not need a url param, it builds it by
 126          * itself. It also fails-over to the next possible clusters.
 127          *
 128          * @param $data string
 129          * @param array $params Associative array of ExternalStoreMedium parameters
 130          * @return string|bool The URL of the stored data item, or false on error
 131          * @throws MWException
 132          */
 133         public static function insertToDefault( $data, array $params = array() ) {
 134                 global $wgDefaultExternalStore;
 135
 136                 $error = false;
 137                 $tryStores = (array)$wgDefaultExternalStore;
 138                 while ( count( $tryStores ) > 0 ) {
 139                         $index = mt_rand( 0, count( $tryStores ) - 1 );
 140                         $storeUrl = $tryStores[$index];
 141                         wfDebug( __METHOD__ . ": trying $storeUrl\n" );
 142                         list( $proto, $path ) = explode( '://', $storeUrl, 2 );
 143                         $store = self::getStoreObject( $proto, $params );
 144                         if ( $store === false ) {
 145                                 throw new MWException( "Invalid external storage protocol - $storeUrl" );
 146                         }
 147                         try {
 148                                 $url = $store->store( $path, $data ); // Try to save the object
 149                         } catch ( MWException $error ) {
 150                                 $url = false;
 151                         }
 152                         if ( strlen( $url ) ) {
 153                                 return $url; // Done!
 154                         } else {
 155                                 unset( $tryStores[$index] ); // Don't try this one again!
 156                                 $tryStores = array_values( $tryStores ); // Must have consecutive keys
 157                                 wfDebugLog( 'ExternalStorage',
 158                                         "Unable to store text to external storage $storeUrl" );
 159                         }
 160                 }
 161                 // All stores failed
 162                 if ( $error ) {
 163                         throw $error; // rethrow the last error
 164                 } else {
 165                         throw new MWException( "Unable to store text to external storage" );
 166                 }
 167         }
 168
 169         /**
 170          * @param $data string
 171          * @param $wiki string
 172          * @return string|bool The URL of the stored data item, or false on error
 173          * @throws MWException
 174          */
 175         public static function insertToForeignDefault( $data, $wiki ) {
 176                 return self::insertToDefault( $data, array( 'wiki' => $wiki ) );
 177         }
 178 }