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	}