Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
17 / 17
100.00% covered (success)
100.00%
6 / 6
 CRAP
100.00% covered (success)
100.00%
1 / 1
PageIdentityValue
100.00% covered (success)
100.00%
17 / 17
100.00% covered (success)
100.00%
6 / 6
 7
100.00% covered (success)
100.00%
1 / 1
 tryNew
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 2
 __construct
100.00% covered (success)
100.00%
9 / 9
100.00% covered (success)
100.00%
1 / 1
 1
 localIdentity
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getId
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 exists
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 canExist
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
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
21namespace MediaWiki\Page;
22
23use InvalidArgumentException;
24use 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 */
43class 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}