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