Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 8
0.00% covered (danger)
0.00%
0 / 4
 CRAP
0.00% covered (danger)
0.00%
0 / 1
MentorManager
0.00% covered (danger)
0.00%
0 / 8
0.00% covered (danger)
0.00%
0 / 4
 0
0.00% covered (danger)
0.00%
0 / 1
 getMentorForUserIfExists
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 0
 getMentorForUser
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 0
 getMentorForUserSafe
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 0
 getEffectiveMentorForUser
n/a
0 / 0
n/a
0 / 0
 0
 getEffectiveMentorForUserSafe
n/a
0 / 0
n/a
0 / 0
 0
 getMentorshipStateForUser
n/a
0 / 0
n/a
0 / 0
 0
 setMentorshipStateForUser
n/a
0 / 0
n/a
0 / 0
 0
 getRandomAutoAssignedMentor
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 0
1<?php
2
3namespace GrowthExperiments\Mentorship;
4
5use GrowthExperiments\Mentorship\Store\MentorStore;
6use GrowthExperiments\WikiConfigException;
7use InvalidArgumentException;
8use MediaWiki\User\UserIdentity;
9use Wikimedia\LightweightObjectStore\ExpirationAwareness;
10
11/**
12 * A service for handling mentors.
13 */
14abstract class MentorManager implements ExpirationAwareness {
15
16    /** @var int */
17    public const MENTORSHIP_DISABLED = 0;
18    /** @var int */
19    public const MENTORSHIP_ENABLED = 1;
20    /** @var int */
21    public const MENTORSHIP_OPTED_OUT = 2;
22
23    /** @var int[] */
24    protected const MENTORSHIP_STATES = [
25        self::MENTORSHIP_DISABLED,
26        self::MENTORSHIP_ENABLED,
27        self::MENTORSHIP_OPTED_OUT
28    ];
29
30    /**
31     * Get the mentor assigned to this user, if it exists.
32     * @param UserIdentity $user
33     * @param string $role MentorStore::ROLE_* constant
34     * @return Mentor|null
35     */
36    abstract public function getMentorForUserIfExists(
37        UserIdentity $user,
38        string $role = MentorStore::ROLE_PRIMARY
39    ): ?Mentor;
40
41    /**
42     * Get the mentor assigned to this user.
43     * If the user did not have a mentor before, this will assign one on the fly.
44     * @param UserIdentity $user
45     * @param string $role MentorStore::ROLE_* constant
46     * @return Mentor
47     * @throws WikiConfigException If it is not possible to obtain a mentor due to misconfiguration.
48     */
49    abstract public function getMentorForUser(
50        UserIdentity $user,
51        string $role = MentorStore::ROLE_PRIMARY
52    ): Mentor;
53
54    /**
55     * Get the mentor assigned to this user. Suppress configuration errors and return null
56     * if a mentor cannot be assigned.
57     * @param UserIdentity $user
58     * @param string $role MentorStore::ROLE_* constant
59     * @return Mentor|null
60     */
61    abstract public function getMentorForUserSafe(
62        UserIdentity $user,
63        string $role = MentorStore::ROLE_PRIMARY
64    ): ?Mentor;
65
66    /**
67     * Get the effective mentor assigned to this user.
68     *
69     * This returns the primary mentor if they're active, otherwise,
70     * it returns the backup mentor.
71     *
72     * @param UserIdentity $menteeUser
73     * @return Mentor
74     * @throws WikiConfigException If it is not possible to obtain a mentor due to misconfiguration.
75     */
76    abstract public function getEffectiveMentorForUser( UserIdentity $menteeUser ): Mentor;
77
78    /**
79     * Get the effective mentor assigned to this user, suppressing configuration errors.
80     *
81     * This returns the primary mentor if they're active, otherwise,
82     * it returns the backup mentor.
83     *
84     * @param UserIdentity $menteeUser
85     * @return Mentor|null
86     */
87    abstract public function getEffectiveMentorForUserSafe( UserIdentity $menteeUser ): ?Mentor;
88
89    /**
90     * Checks state of mentorship for an user
91     *
92     * @param UserIdentity $user
93     * @return int One of MentorManager::MENTORSHIP_*
94     */
95    abstract public function getMentorshipStateForUser( UserIdentity $user ): int;
96
97    /**
98     * Set state of mentorship for an user
99     *
100     * @param UserIdentity $user
101     * @param int $state One of MentorManager::MENTORSHIP_*
102     * @throws InvalidArgumentException In case of invalid $state
103     */
104    abstract public function setMentorshipStateForUser( UserIdentity $user, int $state ): void;
105
106    /**
107     * Randomly selects a mentor from the available mentors.
108     *
109     * @param UserIdentity $mentee
110     * @param UserIdentity[] $excluded A list of users who should not be selected.
111     * @return UserIdentity|null The selected mentor; null if none available.
112     * @throws WikiConfigException If the mentor list is invalid.
113     */
114    abstract public function getRandomAutoAssignedMentor(
115        UserIdentity $mentee, array $excluded = []
116    ): ?UserIdentity;
117}