includes/page/PageReference.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\WikiAwareEntity;
  24 use Stringable;
  25
  26 /**
  27  * Interface for objects (potentially) representing a page that can be viewable and linked to
  28  * on a wiki. This includes special pages.
  29  *
  30  * The identity of any PageReference object is defined by the
  31  * namespace, the dbkey, and the wiki ID.
  32  * If the wiki ID is self::LOCAL, the identity is relative to the local wiki.
  33  *
  34  * @note For compatibility with the Title class, PageReference instances
  35  *   may for represent things that are not viewable pages, such as interwiki links
  36  *   and section links. This is intended to change in the future.
  37  *
  38  * @note Instances of Title shall be the only instances of PageReference that are not
  39  *   viewable pages. Other classes implementing PageReference must not permit an empty DB key.
  40  *   The idea is that once Title has been removed, all PageReference are then viewable pages.
  41  *
  42  * @note Code that deserializes instances of PageReference must ensure that the original
  43  *   meaning of the "local" Wiki ID is preserved if the PageReference originated on
  44  *   another wiki.
  45  *
  46  * @see https://www.mediawiki.org/wiki/Manual:Modeling_pages
  47  *
  48  * @stable to type
  49  * @since 1.37
  50  * @ingroup Page
  51  */
  52 interface PageReference extends Stringable, WikiAwareEntity {
  53
  54         /**
  55          * Get the ID of the wiki this page belongs to.
  56          *
  57          * @return string|false The wiki's logical name,
  58          *         or self::LOCAL to indicate the local wiki.
  59          */
  60         public function getWikiId();
  61
  62         /**
  63          * Returns the page's namespace number.
  64          *
  65          * The value returned by this method should represent a valid namespace,
  66          * but this cannot be guaranteed in all cases.
  67          *
  68          * @return int
  69          */
  70         public function getNamespace(): int;
  71
  72         /**
  73          * Get the page title in DB key form.
  74          *
  75          * @note This may return a string starting with a hash, if the PageReference represents
  76          *       the target of a block or unblock operation. This is due to the way the block target
  77          *       is represented in the logging table. This is intended to change in the future.
  78          *
  79          * @note This may return an empty string, if this PageReference is a Title that represents
  80          *       a relative section link. This is intended to change in the future.
  81          *
  82          * @return string
  83          */
  84         public function getDBkey(): string;
  85
  86         /**
  87          * Checks whether the given PageReference refers to the same page as this PageReference.
  88          *
  89          * Two PageReference instances are considered to refer to the same page if
  90          * they belong to the same wiki, and have the same namespace and DB key.
  91          *
  92          * @param PageReference $other
  93          *
  94          * @return bool
  95          */
  96         public function isSamePageAs( PageReference $other ): bool;
  97
  98         /**
  99          * Returns an informative human readable unique representation of the page identity,
 100          * for use as a cache key and for logging and debugging.
 101          *
 102          * @return string
 103          */
 104         public function __toString(): string;
 105
 106 }