includes/libs/rdbms/database/domain/DatabaseDomain.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  * @ingroup Database
  20  */
  21 namespace Wikimedia\Rdbms;
  22
  23 use InvalidArgumentException;
  24
  25 /**
  26  * Class to handle database/prefix specification for IDatabase domains
  27  */
  28 class DatabaseDomain {
  29         /** @var string|null */
  30         private $database;
  31         /** @var string|null */
  32         private $schema;
  33         /** @var string */
  34         private $prefix;
  35
  36         /** @var string Cache of convertToString() */
  37         private $equivalentString;
  38
  39         /**
  40          * @param string|null $database Database name
  41          * @param string|null $schema Schema name
  42          * @param string $prefix Table prefix
  43          */
  44         public function __construct( $database, $schema, $prefix ) {
  45                 if ( $database !== null && ( !is_string( $database ) || $database === '' ) ) {
  46                         throw new InvalidArgumentException( 'Database must be null or a non-empty string.' );
  47                 }
  48                 $this->database = $database;
  49                 if ( $schema !== null && ( !is_string( $schema ) || $schema === '' ) ) {
  50                         throw new InvalidArgumentException( 'Schema must be null or a non-empty string.' );
  51                 } elseif ( $database === null && $schema !== null ) {
  52                         throw new InvalidArgumentException( 'Schema must be null if database is null.' );
  53                 }
  54                 $this->schema = $schema;
  55                 if ( !is_string( $prefix ) ) {
  56                         throw new InvalidArgumentException( "Prefix must be a string." );
  57                 }
  58                 $this->prefix = $prefix;
  59         }
  60
  61         /**
  62          * @param DatabaseDomain|string $domain Result of DatabaseDomain::toString()
  63          * @return DatabaseDomain
  64          */
  65         public static function newFromId( $domain ) {
  66                 if ( $domain instanceof self ) {
  67                         return $domain;
  68                 }
  69
  70                 $parts = array_map( [ __CLASS__, 'decode' ], explode( '-', $domain ) );
  71
  72                 $schema = null;
  73                 $prefix = '';
  74
  75                 if ( count( $parts ) == 1 ) {
  76                         $database = $parts[0];
  77                 } elseif ( count( $parts ) == 2 ) {
  78                         list( $database, $prefix ) = $parts;
  79                 } elseif ( count( $parts ) == 3 ) {
  80                         list( $database, $schema, $prefix ) = $parts;
  81                 } else {
  82                         throw new InvalidArgumentException( "Domain '$domain' has too few or too many parts." );
  83                 }
  84
  85                 if ( $database === '' ) {
  86                         $database = null;
  87                 }
  88
  89                 if ( $schema === '' ) {
  90                         $schema = null;
  91                 }
  92
  93                 $instance = new self( $database, $schema, $prefix );
  94                 $instance->equivalentString = (string)$domain;
  95
  96                 return $instance;
  97         }
  98
  99         /**
 100          * @return DatabaseDomain
 101          */
 102         public static function newUnspecified() {
 103                 return new self( null, null, '' );
 104         }
 105
 106         /**
 107          * @param DatabaseDomain|string $other
 108          * @return bool Whether the domain instances are the same by value
 109          */
 110         public function equals( $other ) {
 111                 if ( $other instanceof self ) {
 112                         return (
 113                                 $this->database === $other->database &&
 114                                 $this->schema === $other->schema &&
 115                                 $this->prefix === $other->prefix
 116                         );
 117                 }
 118
 119                 return ( $this->getId() === $other );
 120         }
 121
 122         /**
 123          * Check whether the domain $other meets the specifications of this domain
 124          *
 125          * If this instance has a null database specifier, then $other can have any database
 126          * specifier, including null. This is likewise true if the schema specifier is null.
 127          * This is not transitive like equals() since a domain that explicitly wants a certain
 128          * database or schema cannot be satisfied by one of another (nor null). If the prefix
 129          * is empty and the DB and schema are both null, then the entire domain is considered
 130          * unspecified, and any prefix of $other is considered compatible.
 131          *
 132          * @param DatabaseDomain|string $other
 133          * @return bool
 134          * @since 1.32
 135          */
 136         public function isCompatible( $other ) {
 137                 if ( $this->isUnspecified() ) {
 138                         return true; // even the prefix doesn't matter
 139                 }
 140
 141                 $other = self::newFromId( $other );
 142
 143                 return (
 144                         ( $this->database === $other->database || $this->database === null ) &&
 145                         ( $this->schema === $other->schema || $this->schema === null ) &&
 146                         $this->prefix === $other->prefix
 147                 );
 148         }
 149
 150         /**
 151          * @return bool
 152          * @since 1.32
 153          */
 154         public function isUnspecified() {
 155                 return (
 156                         $this->database === null && $this->schema === null && $this->prefix === ''
 157                 );
 158         }
 159
 160         /**
 161          * @return string|null Database name
 162          */
 163         public function getDatabase() {
 164                 return $this->database;
 165         }
 166
 167         /**
 168          * @return string|null Database schema
 169          */
 170         public function getSchema() {
 171                 return $this->schema;
 172         }
 173
 174         /**
 175          * @return string Table prefix
 176          */
 177         public function getTablePrefix() {
 178                 return $this->prefix;
 179         }
 180
 181         /**
 182          * @return string
 183          */
 184         public function getId() {
 185                 if ( $this->equivalentString === null ) {
 186                         $this->equivalentString = $this->convertToString();
 187                 }
 188
 189                 return $this->equivalentString;
 190         }
 191
 192         /**
 193          * @return string
 194          */
 195         private function convertToString() {
 196                 $parts = [ (string)$this->database ];
 197                 if ( $this->schema !== null ) {
 198                         $parts[] = $this->schema;
 199                 }
 200                 if ( $this->prefix != '' || $this->schema !== null ) {
 201                         // If there is a schema, then we need the prefix to disambiguate.
 202                         // For engines like Postgres that use schemas, this awkwardness is hopefully
 203                         // avoided since it is easy to have one DB per server (to avoid having many users)
 204                         // and use schema/prefix to have wiki farms. For example, a domain schemes could be
 205                         // wiki-<project>-<language>, e.g. "wiki-fitness-es"/"wiki-sports-fr"/"wiki-news-en".
 206                         $parts[] = $this->prefix;
 207                 }
 208
 209                 return implode( '-', array_map( [ __CLASS__, 'encode' ], $parts ) );
 210         }
 211
 212         private static function encode( $decoded ) {
 213                 $encoded = '';
 214
 215                 $length = strlen( $decoded );
 216                 for ( $i = 0; $i < $length; ++$i ) {
 217                         $char = $decoded[$i];
 218                         if ( $char === '-' ) {
 219                                 $encoded .= '?h';
 220                         } elseif ( $char === '?' ) {
 221                                 $encoded .= '??';
 222                         } else {
 223                                 $encoded .= $char;
 224                         }
 225                 }
 226
 227                 return $encoded;
 228         }
 229
 230         private static function decode( $encoded ) {
 231                 $decoded = '';
 232
 233                 $length = strlen( $encoded );
 234                 for ( $i = 0; $i < $length; ++$i ) {
 235                         $char = $encoded[$i];
 236                         if ( $char === '?' ) {
 237                                 $nextChar = $encoded[$i + 1] ?? null;
 238                                 if ( $nextChar === 'h' ) {
 239                                         $decoded .= '-';
 240                                         ++$i;
 241                                 } elseif ( $nextChar === '?' ) {
 242                                         $decoded .= '?';
 243                                         ++$i;
 244                                 } else {
 245                                         $decoded .= $char;
 246                                 }
 247                         } else {
 248                                 $decoded .= $char;
 249                         }
 250                 }
 251
 252                 return $decoded;
 253         }
 254
 255         /**
 256          * @return string
 257          */
 258         function __toString() {
 259                 return $this->getId();
 260         }
 261 }