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 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 $params['writableLocations'] = [];
92 // Determine the locations for this protocol/store still receiving writes
93 foreach ( $this->writeBaseUrls
as $storeUrl ) {
94 list( $storeProto, $storePath ) = self
::splitStorageUrl( $storeUrl );
95 if ( $protoLowercase === strtolower( $storeProto ) ) {
96 $params['writableLocations'][] = $storePath;
99 // @TODO: ideally, this class should not hardcode what classes need what backend factory
100 // objects. For now, inject the factory instances into __construct() for those that do.
101 if ( $protoLowercase === 'db' ) {
102 $params['lbFactory'] = MediaWikiServices
::getInstance()->getDBLoadBalancerFactory();
103 } elseif ( $protoLowercase === 'mwstore' ) {
104 $params['fbGroup'] = FileBackendGroup
::singleton();
106 $params['logger'] = $this->logger
;
108 if ( !class_exists( $class ) ) {
109 throw new ExternalStoreException( "Class '$class' is not defined." );
112 // Any custom modules should be added to $wgAutoLoadClasses for on-demand loading
113 return new $class( $params );
117 * Get the ExternalStoreMedium for a given URL
119 * $url is either of the form:
120 * - a) "<proto>://<location>/<path>", for retrieval, or
121 * - b) "<proto>://<location>", for storage
124 * @param array $params Map of ExternalStoreMedium::__construct context parameters
125 * @return ExternalStoreMedium
126 * @throws ExternalStoreException When the protocol is missing or not recognized
129 public function getStoreForUrl( $url, array $params = [] ) {
130 list( $proto, $path ) = self
::splitStorageUrl( $url );
131 if ( $path == '' ) { // bad URL
132 throw new ExternalStoreException( "Invalid URL '$url'" );
135 return $this->getStore( $proto, $params );
139 * Get the location within the appropriate store for a given a URL
143 * @throws ExternalStoreException
146 public function getStoreLocationFromUrl( $url ) {
147 list( , $location ) = self
::splitStorageUrl( $url );
148 if ( $location == '' ) { // bad URL
149 throw new ExternalStoreException( "Invalid URL '$url'" );
156 * @param string[] $urls
157 * @return array[] Map of (protocol => list of URLs)
158 * @throws ExternalStoreException
161 public function getUrlsByProtocol( array $urls ) {
162 $urlsByProtocol = [];
163 foreach ( $urls as $url ) {
164 list( $proto, ) = self
::splitStorageUrl( $url );
165 $urlsByProtocol[$proto][] = $url;
168 return $urlsByProtocol;
172 * @param string $storeUrl
173 * @return string[] (protocol, store location or location-qualified path)
174 * @throws ExternalStoreException
176 private static function splitStorageUrl( $storeUrl ) {
177 $parts = explode( '://', $storeUrl );
178 if ( count( $parts ) != 2 ||
$parts[0] === '' ||
$parts[1] === '' ) {
179 throw new ExternalStoreException( "Invalid storage URL '$storeUrl'" );