3 * @defgroup ExternalStorage ExternalStorage
6 use MediaWiki\MediaWikiServices
;
7 use Psr\Log\LoggerAwareInterface
;
8 use Psr\Log\LoggerInterface
;
9 use Psr\Log\NullLogger
;
10 use Wikimedia\Assert\Assert
;
13 * @ingroup ExternalStorage
15 class ExternalStoreFactory
implements LoggerAwareInterface
{
16 /** @var string[] List of storage access protocols */
18 /** @var string[] List of base storage URLs that define locations for writes */
19 private $writeBaseUrls;
20 /** @var string Default database domain to store content under */
21 private $localDomainId;
22 /** @var LoggerInterface */
26 * @param string[] $externalStores See $wgExternalStores
27 * @param string[] $defaultStores See $wgDefaultExternalStore
28 * @param string $localDomainId Local database/wiki ID
29 * @param LoggerInterface|null $logger
31 public function __construct(
32 array $externalStores,
35 LoggerInterface
$logger = null
37 Assert
::parameterType( 'string', $localDomainId, '$localDomainId' );
39 $this->protocols
= array_map( 'strtolower', $externalStores );
40 $this->writeBaseUrls
= $defaultStores;
41 $this->localDomainId
= $localDomainId;
42 $this->logger
= $logger ?
: new NullLogger();
45 public function setLogger( LoggerInterface
$logger ) {
46 $this->logger
= $logger;
50 * @return string[] List of active store types/protocols (lowercased), e.g. [ "db" ]
53 public function getProtocols() {
54 return $this->protocols
;
58 * @return string[] List of default base URLs for writes, e.g. [ "DB://cluster1" ]
61 public function getWriteBaseUrls() {
62 return $this->writeBaseUrls
;
66 * Get an external store object of the given type, with the given parameters
68 * The 'domain' field in $params will be set to the local DB domain if it is unset
69 * or false. A special 'isDomainImplicit' flag is set when this happens, which should
70 * only be used to handle legacy DB domain configuration concerns (e.g. T200471).
72 * @param string $proto Type of external storage, should be a value in $wgExternalStores
73 * @param array $params Map of ExternalStoreMedium::__construct context parameters.
74 * @return ExternalStoreMedium The store class or false on error
75 * @throws ExternalStoreException When $proto is not recognized
77 public function getStore( $proto, array $params = [] ) {
78 $protoLowercase = strtolower( $proto ); // normalize
79 if ( !$this->protocols ||
!in_array( $protoLowercase, $this->protocols
) ) {
80 throw new ExternalStoreException( "Protocol '$proto' is not enabled." );
83 $class = 'ExternalStore' . ucfirst( $proto );
84 if ( isset( $params['wiki'] ) ) {
85 $params +
= [ 'domain' => $params['wiki'] ]; // b/c
87 if ( !isset( $params['domain'] ) ||
$params['domain'] === false ) {
88 $params['domain'] = $this->localDomainId
; // default
89 $params['isDomainImplicit'] = true; // b/c for ExternalStoreDB
91 // @TODO: ideally, this class should not hardcode what classes need what backend factory
92 // objects. For now, inject the factory instances into __construct() for those that do.
93 if ( $protoLowercase === 'db' ) {
94 $params['lbFactory'] = MediaWikiServices
::getInstance()->getDBLoadBalancerFactory();
95 } elseif ( $protoLowercase === 'mwstore' ) {
96 $params['fbGroup'] = FileBackendGroup
::singleton();
98 $params['logger'] = $this->logger
;
100 if ( !class_exists( $class ) ) {
101 throw new ExternalStoreException( "Class '$class' is not defined." );
104 // Any custom modules should be added to $wgAutoLoadClasses for on-demand loading
105 return new $class( $params );
109 * Get the ExternalStoreMedium for a given URL
111 * $url is either of the form:
112 * - a) "<proto>://<location>/<path>", for retrieval, or
113 * - b) "<proto>://<location>", for storage
116 * @param array $params Map of ExternalStoreMedium::__construct context parameters
117 * @return ExternalStoreMedium
118 * @throws ExternalStoreException When the protocol is missing or not recognized
121 public function getStoreForUrl( $url, array $params = [] ) {
122 list( $proto, $path ) = self
::splitStorageUrl( $url );
123 if ( $path == '' ) { // bad URL
124 throw new ExternalStoreException( "Invalid URL '$url'" );
127 return $this->getStore( $proto, $params );
131 * Get the location within the appropriate store for a given a URL
135 * @throws ExternalStoreException
138 public function getStoreLocationFromUrl( $url ) {
139 list( , $location ) = self
::splitStorageUrl( $url );
140 if ( $location == '' ) { // bad URL
141 throw new ExternalStoreException( "Invalid URL '$url'" );
148 * @param string[] $urls
149 * @return array[] Map of (protocol => list of URLs)
150 * @throws ExternalStoreException
153 public function getUrlsByProtocol( array $urls ) {
154 $urlsByProtocol = [];
155 foreach ( $urls as $url ) {
156 list( $proto, ) = self
::splitStorageUrl( $url );
157 $urlsByProtocol[$proto][] = $url;
160 return $urlsByProtocol;
164 * @param string $storeUrl
165 * @return string[] (protocol, store location or location-qualified path)
166 * @throws ExternalStoreException
168 private static function splitStorageUrl( $storeUrl ) {
169 $parts = explode( '://', $storeUrl );
170 if ( count( $parts ) != 2 ||
$parts[0] === '' ||
$parts[1] === '' ) {
171 throw new ExternalStoreException( "Invalid storage URL '$storeUrl'" );