includes/externalstore/ExternalStoreMedium.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 use Psr\Log\LoggerAwareInterface;
  22 use Psr\Log\LoggerInterface;
  23 use Psr\Log\NullLogger;
  24
  25 /**
  26  * Base class for external storage.
  27  *
  28  * There can be multiple "locations" for a storage medium type (e.g. DB clusters, filesystems).
  29  * Blobs are stored under URLs of the form `<protocol>://<location>/<path>`. Each type of storage
  30  * medium has an associated protocol.
  31  *
  32  * @see ExternalStoreAccess
  33  * @ingroup ExternalStorage
  34  * @since 1.21
  35  */
  36 abstract class ExternalStoreMedium implements LoggerAwareInterface {
  37         /** @var array Usage context options for this instance */
  38         protected $params = [];
  39         /** @var string Default database domain to store content under */
  40         protected $dbDomain;
  41         /** @var bool Whether this was factoried with an explicit DB domain */
  42         protected $isDbDomainExplicit;
  43
  44         /** @var LoggerInterface */
  45         protected $logger;
  46
  47         /**
  48          * @param array $params Usage context options for this instance:
  49          *   - domain: the DB domain ID of the wiki the content is for [required]
  50          *   - logger: LoggerInterface instance [optional]
  51          *   - isDomainImplicit: whether this was factoried without an explicit DB domain [optional]
  52          */
  53         public function __construct( array $params ) {
  54                 $this->params = $params;
  55                 if ( isset( $params['domain'] ) ) {
  56                         $this->dbDomain = $params['domain'];
  57                         $this->isDbDomainExplicit = empty( $params['isDomainImplicit'] );
  58                 } else {
  59                         throw new InvalidArgumentException( 'Missing DB "domain" parameter.' );
  60                 }
  61
  62                 $this->logger = $params['logger'] ?? new NullLogger();
  63         }
  64
  65         public function setLogger( LoggerInterface $logger ) {
  66                 $this->logger = $logger;
  67         }
  68
  69         /**
  70          * Fetch data from given external store URL
  71          *
  72          * @param string $url An external store URL
  73          * @return string|bool The text stored or false on error
  74          * @throws ExternalStoreException
  75          */
  76         abstract public function fetchFromURL( $url );
  77
  78         /**
  79          * Fetch data from given external store URLs.
  80          *
  81          * @param array $urls A list of external store URLs
  82          * @return string[] Map of (url => text) for the URLs where data was actually found
  83          */
  84         public function batchFetchFromURLs( array $urls ) {
  85                 $retval = [];
  86                 foreach ( $urls as $url ) {
  87                         $data = $this->fetchFromURL( $url );
  88                         // Dont return when false to allow for simpler implementations
  89                         if ( $data !== false ) {
  90                                 $retval[$url] = $data;
  91                         }
  92                 }
  93
  94                 return $retval;
  95         }
  96
  97         /**
  98          * Insert a data item into a given location
  99          *
 100          * @param string $location The location name
 101          * @param string $data The data item
 102          * @return string|bool The URL of the stored data item, or false on error
 103          * @throws ExternalStoreException
 104          */
 105         abstract public function store( $location, $data );
 106
 107         /**
 108          * Check if a given location is read-only
 109          *
 110          * @param string $location The location name
 111          * @return bool Whether this location is read-only
 112          * @since 1.31
 113          */
 114         public function isReadOnly( $location ) {
 115                 return false;
 116         }
 117 }