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