includes/page/PageReferenceValue.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 namespace MediaWiki\Page;
  22
  23 use MediaWiki\DAO\WikiAwareEntityTrait;
  24 use Stringable;
  25 use Wikimedia\Assert\Assert;
  26 use Wikimedia\NonSerializable\NonSerializableTrait;
  27
  28 /**
  29  * Immutable value object representing a page reference.
  30  *
  31  * Instances of this class are expected to always represent a viewable pages, that is,
  32  * pages that can at least potentially be visited on the wiki.
  33  * This class may represent Special pages, but not interwiki links, section links, etc.
  34  *
  35  * Code that deserializes instances of PageReferenceValue must ensure that the original
  36  * meaning of the "local" Wiki ID is preserved: When an instance of PageReferenceValue
  37  * is created with self::LOCAL as the Wiki ID on one wiki, gets serialized,
  38  * stored, and later read and unserialized on another wiki, the value of the Wiki ID
  39  * must be adjusted to refer to the original wiki.
  40  *
  41  * @since 1.37
  42  */
  43 class PageReferenceValue implements Stringable, PageReference {
  44
  45         /* Use JSON, but beware the note on serialization above. */
  46         use NonSerializableTrait;
  47         use WikiAwareEntityTrait;
  48
  49         /** @var int */
  50         private $namespace;
  51
  52         /** @var string */
  53         private $dbKey;
  54
  55         /** @var string|false */
  56         private $wikiId;
  57
  58         /**
  59          * @param int $namespace A valid namespace ID. Validation is the caller's responsibility!
  60          * @param string $dbKey A valid DB key. Validation is the caller's responsibility!
  61          * @param string|false $wikiId The Id of the wiki this page belongs to,
  62          *        or self::LOCAL for the local wiki.
  63          */
  64         public function __construct( int $namespace, string $dbKey, $wikiId ) {
  65                 $this->assertWikiIdParam( $wikiId );
  66
  67                 Assert::parameter( $dbKey !== '', '$dbKey', 'must not be empty' );
  68
  69                 // Replace spaces with underscores
  70                 $dbKey = str_replace( ' ', '_', $dbKey );
  71
  72                 $this->wikiId = $wikiId;
  73                 $this->namespace = $namespace;
  74                 $this->dbKey = $dbKey;
  75         }
  76
  77         /**
  78          * Create PageReference for a local page.
  79          *
  80          * @param int $namespace
  81          * @param string $dbKey
  82          * @return PageReferenceValue
  83          */
  84         public static function localReference( int $namespace, string $dbKey ): self {
  85                 return new self( $namespace, $dbKey, self::LOCAL );
  86         }
  87
  88         /**
  89          * Get the ID of the wiki provided to the constructor.
  90          *
  91          * @return string|false
  92          */
  93         public function getWikiId() {
  94                 return $this->wikiId;
  95         }
  96
  97         /**
  98          * @inheritDoc
  99          *
 100          * @return int
 101          */
 102         public function getNamespace(): int {
 103                 return $this->namespace;
 104         }
 105
 106         /**
 107          * @inheritDoc
 108          *
 109          * @return string
 110          */
 111         public function getDBkey(): string {
 112                 return $this->dbKey;
 113         }
 114
 115         /**
 116          * @inheritDoc
 117          */
 118         public function isSamePageAs( PageReference $other ): bool {
 119                 // NOTE: keep in sync with Title::isSamePageAs()!
 120                 // NOTE: keep in sync with WikiPage::isSamePageAs()!
 121                 return $this->getWikiId() === $other->getWikiId()
 122                         && $this->getNamespace() === $other->getNamespace()
 123                         && $this->getDBkey() === $other->getDBkey();
 124         }
 125
 126         /**
 127          * Returns a string representation of the title, for logging. This is purely informative
 128          * and must not be used programmatically.
 129          *
 130          * @return string
 131          */
 132         public function __toString(): string {
 133                 $s = '[' . $this->namespace . ':' . $this->dbKey . ']';
 134
 135                 if ( $this->wikiId ) {
 136                         $s .= '@' . $this->wikiId;
 137                 }
 138
 139                 return $s;
 140         }
 141
 142 }