includes/page/PageIdentityValue.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 InvalidArgumentException;
  24 use Wikimedia\Assert\Assert;
  25
  26 /**
  27  * Immutable value object representing a page identity.
  28  *
  29  * Instances of this class are expected to always represent proper pages, that is,
  30  * pages that can at least potentially exist as editable pages on the wiki.
  31  * This class cannot represent Special pages, interwiki links, section links, etc.
  32  *
  33  * Code that deserializes instances of PageIdentityValue must ensure that the original
  34  * meaning of the "local" Wiki ID is preserved: When an instance of PageIdentityValue
  35  * is created with self::LOCAL as the Wiki ID on one wiki, gets serialized,
  36  * stored, and later read and unserialized on another wiki, the value of the Wiki ID
  37  * must be adjusted to refer to the original wiki.
  38  *
  39  * @see https://www.mediawiki.org/wiki/Manual:Modeling_pages
  40  *
  41  * @since 1.36
  42  */
  43 class PageIdentityValue extends PageReferenceValue implements ProperPageIdentity {
  44
  45         /** @var int */
  46         private $pageId;
  47
  48         /**
  49          * Constructs a PageIdentityValue, or returns null if the parameters are not valid.
  50          *
  51          * @note This does not perform any normalization, and only basic validation.
  52          * For full normalization and validation, use TitleParser::makeTitleValueSafe()
  53          * together with PageLookup::getPageForLink().
  54          *
  55          * @param int $pageId The ID of this page, or 0 if the page does not exist.
  56          * @param int $namespace A valid namespace ID. Validation is the caller's responsibility!
  57          * @param string $dbKey A valid DB key. Validation is the caller's responsibility!
  58          * @param string|false $wikiId The Id of the wiki this page belongs to,
  59          *        or self::LOCAL for the local wiki.
  60          *
  61          * @return PageIdentityValue|null
  62          */
  63         public static function tryNew( int $pageId, int $namespace, string $dbKey, $wikiId ) {
  64                 try {
  65                         return new static( $pageId, $namespace, $dbKey, $wikiId );
  66                 } catch ( InvalidArgumentException $ex ) {
  67                         return null;
  68                 }
  69         }
  70
  71         /**
  72          * @param int $pageId The ID of this page, or 0 if the page does not exist.
  73          * @param int $namespace A valid namespace ID. Validation is the caller's responsibility!
  74          * @param string $dbKey A valid DB key. Validation is the caller's responsibility!
  75          * @param string|false $wikiId The Id of the wiki this page belongs to,
  76          *        or self::LOCAL for the local wiki.
  77          */
  78         public function __construct( int $pageId, int $namespace, string $dbKey, $wikiId ) {
  79                 Assert::parameter( $pageId >= 0, '$pageId', 'must not be negative' );
  80                 Assert::parameter( $namespace >= 0, '$namespace', 'must not be negative' );
  81
  82                 // Not full validation, intended to help detect lack of validation in the caller.
  83                 Assert::parameter(
  84                         !preg_match( '/[#|]/', $dbKey ),
  85                         '$dbKey',
  86                         'must not contain pipes or hashes: ' . $dbKey
  87                 );
  88
  89                 parent::__construct( $namespace, $dbKey, $wikiId );
  90
  91                 $this->pageId = $pageId;
  92         }
  93
  94         /**
  95          * Create PageIdentity for a local page.
  96          *
  97          * @param int $pageId
  98          * @param int $namespace
  99          * @param string $dbKey
 100          * @return PageIdentityValue
 101          */
 102         public static function localIdentity( int $pageId, int $namespace, string $dbKey ): self {
 103                 return new self( $pageId, $namespace, $dbKey, self::LOCAL );
 104         }
 105
 106         /**
 107          * The numerical page ID provided to the constructor.
 108          *
 109          * @param string|false $wikiId The wiki ID expected by the caller.
 110          *        Omit if expecting the local wiki.
 111          *
 112          * @return int
 113          */
 114         public function getId( $wikiId = self::LOCAL ): int {
 115                 $this->assertWiki( $wikiId );
 116                 return $this->pageId;
 117         }
 118
 119         /**
 120          * Returns whether the page currently exists.
 121          * Returns true if getId() returns a value greater than zero.
 122          * @return bool
 123          */
 124         public function exists(): bool {
 125                 return $this->getId( $this->getWikiId() ) > 0;
 126         }
 127
 128         /**
 129          * @return bool always true
 130          */
 131         public function canExist(): bool {
 132                 return true;
 133         }
 134
 135 }