1	<?php
2
3	namespace GrowthExperiments\NewcomerTasks;
4
5	use GrowthExperiments\NewcomerTasks\TaskType\TaskType;
6	use MediaWiki\Page\ProperPageIdentity;
7	use MediaWiki\User\UserIdentity;
8	use StatusValue;
9
10	/**
11	* Submission handlers process user submissions of recommendations (such as a user
12	* accepting or rejecting a recommendation).
13	*
14	* Since the structured task UI heavily relies on integration with the editor UI,
15	* edits happen via the normal APIs used for editing (typically, visualeditoredit),
16	* so turning the submission into an edit is not the handler's responsibility.
17	*/
18	interface SubmissionHandler {
19
20	/**
21	* Validate a recommendation submission. If validation fails, the submission won't
22	* be turned into an edit.
23	*
24	* @param TaskType $taskType The type of the recommendation.
25	* @param ProperPageIdentity $page The article the recommendation was about.
26	* @param UserIdentity $user The user who acted on the recommendation.
27	* @param int|null $baseRevId Revision that the recommendation was for, or null if no
28	*   revision ID is set in the 'oldid' parameter from VisualEditor.
29	* @param array $data Tasktype-specific data. Typically, this is the data returned via
30	*   the visualeditoredit API's plugin mechanism.
31	* @return StatusValue Success status. A good status is required to pass. When there are
32	*   errors, the OK flag determines whether those should be logged as production errors.
33	*   The StatusValue should always contain a single error.
34	*/
35	public function validate(
36	TaskType $taskType,
37	ProperPageIdentity $page,
38	UserIdentity $user,
39	?int $baseRevId,
40	array $data
41	): StatusValue;
42
43	/**
44	* Handle a recommendation submission. This is called after validation was successful
45	* and the recommendation has been turned into an edit and saved, but within the same
46	* transaction round.
47	*
48	* @param TaskType $taskType The type of the recommendation.
49	* @param ProperPageIdentity $page The article the recommendation was about.
50	* @param UserIdentity $user The user who acted on the recommendation.
51	* @param int|null $baseRevId Revision that the recommendation was for, or null if no
52	*   revision ID is set in the 'oldid' parameter from VisualEditor.
53	* @param int|null $editRevId New revision created (when the recommendation was accepted
54	*   or partially accepted).
55	* @param array $data Tasktype-specific data. Typically, this is the data returned via
56	*   the visualeditoredit API's plugin mechanism.
57	* @return StatusValue A success status. When it contains errors, its OK flag determines
58	*   whether those should be logged as production errors. When it does not contain errors,
59	*   it holds an array with the following fields:
60	*   - logId (int, optional): ID of the log entry that was created.
61	*/
62	public function handle(
63	TaskType $taskType,
64	ProperPageIdentity $page,
65	UserIdentity $user,
66	?int $baseRevId,
67	?int $editRevId,
68	array $data
69	): StatusValue;
70
71	}