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