1	<?php
2
3	namespace GrowthExperiments\NewcomerTasks\TaskSuggester;
4
5	use GrowthExperiments\NewcomerTasks\Task\TaskSet;
6	use GrowthExperiments\NewcomerTasks\Task\TaskSetFilters;
7	use MediaWiki\User\UserIdentity;
8	use StatusValue;
9
10	/**
11	* Service for getting task recommendations for inexperienced users.
12	* @see https://www.mediawiki.org/wiki/Growth/Personalized_first_day/Newcomer_tasks
13	*/
14	interface TaskSuggester {
15
16	/**
17	* @param UserIdentity $user
18	* @param TaskSetFilters $taskSetFilters Filters to apply to the suggestions
19	* @param int|null $limit Number of suggestions to return.
20	* @param int|null $offset Offset within full result set, for continuation.
21	* @param array $options Associative array of options:
22	*   - useCache (bool, default true): enable/disable caching if the implementation has any.
23	*   - resetCache (bool, default false): ignore and replace the cached result. Overrides
24	*     useCache.
25	*   - revalidateCache (bool, default true): whether cached results should be revalidated
26	*     by filtering out tasks where the page changed in such a way that makes the task
27	*     inapplicable (e.g. in the case of a template-based task, the template was removed).
28	*     This is more accurate but slower. No effect when useCache or resetCache is used.
29	*   - debug (bool, default false): Debug mode. Depending on the implementation, might
30	*     result in filling TaskSet::getDebugData(). Might also disable optimizations such as
31	*     caching.
32	* @return TaskSet|StatusValue A set of suggestions or an error in the form of a
33	*   StatusValue.
34	*/
35	public function suggest(
36	UserIdentity $user,
37	TaskSetFilters $taskSetFilters,
38	?int $limit = null,
39	?int $offset = null,
40	array $options = []
41	);
42
43	/**
44	* Remove elements of a taskset which are not valid tasks anymore.
45	* @param UserIdentity $user
46	* @param TaskSet $taskSet
47	* @return TaskSet|StatusValue A set of suggestions or an error in the form of a StatusValue.
48	* @note The interchangeability of TaskTypes/Topics and task type / topic IDs (via
49	*   ConfigurationLoader) is relied on in some places, so passing in TaskType / Topic objects
50	*   for filtering can be fragile. It is OK to use it as long the result is never shown to
51	*   a user and $user is not a real user, though.
52	*/
53	public function filter( UserIdentity $user, TaskSet $taskSet );
54
55	}