includes/user/UserIdentityValue.php

   1 <?php
   2 /**
   3  * Value object representing a user's identity.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 namespace MediaWiki\User;
  24
  25 use MediaWiki\DAO\WikiAwareEntityTrait;
  26 use Wikimedia\Assert\Assert;
  27
  28 /**
  29  * Value object representing a user's identity.
  30  *
  31  * @newable
  32  *
  33  * @since 1.31
  34  */
  35 class UserIdentityValue implements UserIdentity {
  36         use WikiAwareEntityTrait;
  37
  38         /**
  39          * @var int
  40          */
  41         private $id;
  42
  43         /**
  44          * @var string
  45          */
  46         private $name;
  47
  48         /** @var string|false */
  49         private $wikiId;
  50
  51         /**
  52          * @stable to call
  53          *
  54          * @note Signature in 1.35 was: ( $id, $name, $actor ). This is still supported for
  55          *        backwards compatibility. $actor is ignored. This has emitted deprecation
  56          *        warnings since 1.41.
  57          *
  58          * @param int $id user ID
  59          * @param string $name user name
  60          * @param string|false $wikiId wiki ID or self::LOCAL for the local wiki
  61          */
  62         public function __construct( int $id, string $name, $wikiId = self::LOCAL ) {
  63                 if ( is_int( $wikiId ) ) {
  64                         // Handle old signature: ( $id, $name, $actor, $wikiId )
  65                         $args = func_get_args();
  66                         $actor = $args[2];
  67                         $wikiId = $args[3] ?? self::LOCAL;
  68
  69                         wfDeprecatedMsg( 'Old constructor signature: $actor is no longer supported', '1.36' );
  70                 }
  71
  72                 $this->assertWikiIdParam( $wikiId );
  73
  74                 $this->id = $id;
  75                 $this->name = $name;
  76                 $this->wikiId = $wikiId;
  77         }
  78
  79         /**
  80          * Create UserIdentity for an anonymous user.
  81          *
  82          * @since 1.36
  83          * @param string $name
  84          * @param string|false $wikiId wiki ID or self::LOCAL for the local wiki
  85          * @return UserIdentityValue
  86          */
  87         public static function newAnonymous( string $name, $wikiId = self::LOCAL ): self {
  88                 return new self( 0, $name, $wikiId );
  89         }
  90
  91         /**
  92          * Create UserIdentity for a registered user.
  93          *
  94          * @since 1.36
  95          * @param int $userId
  96          * @param string $name
  97          * @param string|false $wikiId wiki ID or self::LOCAL for the local wiki
  98          * @return UserIdentityValue
  99          */
 100         public static function newRegistered( int $userId, string $name, $wikiId = self::LOCAL ): self {
 101                 Assert::parameter( $userId > 0, '$userId', 'must be greater than zero (user must exist)' );
 102                 return new self( $userId, $name, $wikiId );
 103         }
 104
 105         /**
 106          * Create UserIdentity for an external user with $prefix and $name
 107          *
 108          * @since 1.36
 109          * @param string $prefix
 110          * @param string $name
 111          * @param string|false $wikiId wiki ID or self::LOCAL for the local wiki
 112          * @return UserIdentityValue
 113          */
 114         public static function newExternal( string $prefix, string $name, $wikiId = self::LOCAL ): self {
 115                 // > is a standard separator for external users in the database, see ExternalUserNames
 116                 return new self( 0, "$prefix>$name", $wikiId );
 117         }
 118
 119         /**
 120          * Get the ID of the wiki this UserIdentity belongs to.
 121          *
 122          * @since 1.36
 123          * @see RevisionRecord::getWikiId()
 124          *
 125          * @return string|false The wiki's logical name or self::LOCAL to indicate the local wiki
 126          */
 127         public function getWikiId() {
 128                 return $this->wikiId;
 129         }
 130
 131         /**
 132          * The numerical user ID provided to the constructor.
 133          *
 134          * @param string|false $wikiId The wiki ID expected by the caller
 135          * @return int The user ID. May be 0 for anonymous users or for users with no local account.
 136          *
 137          */
 138         public function getId( $wikiId = self::LOCAL ): int {
 139                 $this->assertWiki( $wikiId );
 140                 return $this->id;
 141         }
 142
 143         /**
 144          * @return string The user's logical name. May be an IPv4 or IPv6 address for anonymous users.
 145          */
 146         public function getName(): string {
 147                 return $this->name;
 148         }
 149
 150         /**
 151          * @deprecated since 1.36, use ActorNormalization::acquireActorId instead.
 152          *
 153          * @param string|false $wikiId
 154          *
 155          * @return int always 0.
 156          */
 157         public function getActorId( $wikiId = self::LOCAL ): int {
 158                 wfDeprecated( __METHOD__, '1.36' );
 159                 return 0;
 160         }
 161
 162         /**
 163          * @since 1.32
 164          *
 165          * @param UserIdentity|null $user
 166          * @return bool
 167          */
 168         public function equals( ?UserIdentity $user ): bool {
 169                 if ( !$user ) {
 170                         return false;
 171                 }
 172                 // XXX it's not clear whether central ID providers are supposed to obey this
 173                 return $this->getName() === $user->getName();
 174         }
 175
 176         /**
 177          * @since 1.34
 178          *
 179          * @return bool True if user is registered on this wiki, i.e., has a user ID. False if user is
 180          *   anonymous or has no local account (which can happen when importing). This is equivalent to
 181          *   getId() != 0 and is provided for code readability.
 182          */
 183         public function isRegistered(): bool {
 184                 return $this->getId( $this->wikiId ) != 0;
 185         }
 186
 187         public function __toString(): string {
 188                 return $this->getName();
 189         }
 190
 191 }