includes/user/ActorNormalization.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\User;
  22
  23 use CannotCreateActorException;
  24 use InvalidArgumentException;
  25 use stdClass;
  26 use Wikimedia\Rdbms\IDatabase;
  27 use Wikimedia\Rdbms\IReadableDatabase;
  28
  29 /**
  30  * Service for dealing with the actor table.
  31  * @since 1.36
  32  */
  33 interface ActorNormalization {
  34
  35         /**
  36          * Instantiate a new UserIdentity object based on a $row from the actor table.
  37          *
  38          * Use this method when an actor row was already fetched from the DB via a join.
  39          * This method just constructs a new instance and does not try fetching missing
  40          * values from the DB again, use {@link UserIdentityLookup} for that.
  41          *
  42          * @param stdClass $row with the following fields:
  43          *  - int actor_id
  44          *  - string actor_name
  45          *  - int|null actor_user
  46          * @return UserIdentity
  47          * @throws InvalidArgumentException
  48          */
  49         public function newActorFromRow( stdClass $row ): UserIdentity;
  50
  51         /**
  52          * Instantiate a new UserIdentity object based on field values from a DB row.
  53          *
  54          * Until {@link ActorMigration} is completed, the actor table joins alias actor field names
  55          * to legacy field names. This method is convenience to construct the UserIdentity based on
  56          * legacy field names. It's more relaxed with typing then ::newFromRow to better support legacy
  57          * code, so always prefer ::newFromRow in new code. Eventually, once {@link ActorMigration}
  58          * is completed and all queries use explicit join with actor table, this method will be
  59          * deprecated and removed.
  60          *
  61          * @throws InvalidArgumentException
  62          * @param int|null $userId
  63          * @param string|null $name
  64          * @param int|null $actorId
  65          * @return UserIdentity
  66          */
  67         public function newActorFromRowFields( $userId, $name, $actorId ): UserIdentity;
  68
  69         /**
  70          * Find the actor_id for the given name.
  71          *
  72          * @param string $name
  73          * @param IReadableDatabase $db The database connection to operate on.
  74          *        The database must correspond to the wiki this ActorNormalization is bound to.
  75          * @return int|null
  76          */
  77         public function findActorIdByName( string $name, IReadableDatabase $db ): ?int;
  78
  79         /**
  80          * Find the actor_id of the given $user.
  81          *
  82          * @param UserIdentity $user
  83          * @param IReadableDatabase $db The database connection to operate on.
  84          *        The database must correspond to the wiki this ActorNormalization is bound to.
  85          * @return int|null
  86          */
  87         public function findActorId( UserIdentity $user, IReadableDatabase $db ): ?int;
  88
  89         /**
  90          * Attempt to assign an actor ID to the given $user
  91          * If it is already assigned, return the existing ID.
  92          *
  93          * @param UserIdentity $user
  94          * @param IDatabase $dbw The database connection to acquire the ID from.
  95          *        The database must correspond to the wiki this ActorNormalization is bound to.
  96          * @return int greater then 0
  97          * @throws CannotCreateActorException if no actor ID has been assigned to this $user
  98          */
  99         public function acquireActorId( UserIdentity $user, IDatabase $dbw ): int;
 100
 101         /**
 102          * Find an actor by $id.
 103          *
 104          * @param int $actorId
 105          * @param IReadableDatabase $db The database connection to operate on.
 106          *        The database must correspond to the wiki this ActorNormalization is bound to.
 107          * @return UserIdentity|null Returns null if no actor with this $actorId exists in the database.
 108          */
 109         public function getActorById( int $actorId, IReadableDatabase $db ): ?UserIdentity;
 110
 111         /**
 112          * In case all reasonable attempts of initializing a proper actor from the
 113          * database have failed, entities can be attributed to special 'Unknown user' actor.
 114          *
 115          * @return UserIdentity
 116          */
 117         public function getUnknownActor(): UserIdentity;
 118 }