Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 16
0.00% covered (danger)
0.00%
0 / 6
 CRAP
0.00% covered (danger)
0.00%
0 / 1
MentorProvider
0.00% covered (danger)
0.00%
0 / 16
0.00% covered (danger)
0.00%
0 / 6
 90
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getSignupTitle
n/a
0 / 0
n/a
0 / 0
 0
 newMentorFromUserIdentity
n/a
0 / 0
n/a
0 / 0
 0
 getSourceTitles
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 invalidateCache
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isMentor
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 6
 getMentors
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
 2
 getMentorsSafe
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
 12
 getAutoAssignedMentors
n/a
0 / 0
n/a
0 / 0
 0
 getWeightedAutoAssignedMentors
n/a
0 / 0
n/a
0 / 0
 0
 getManuallyAssignedMentors
n/a
0 / 0
n/a
0 / 0
 0
1<?php
2
3namespace GrowthExperiments\Mentorship\Provider;
4
5use GrowthExperiments\Mentorship\Mentor;
6use GrowthExperiments\WikiConfigException;
7use MediaWiki\Title\Title;
8use MediaWiki\User\UserIdentity;
9use Psr\Log\LoggerAwareTrait;
10use Psr\Log\NullLogger;
11
12abstract class MentorProvider {
13    use LoggerAwareTrait;
14
15    public function __construct() {
16        $this->setLogger( new NullLogger() );
17    }
18
19    /** @var int Maximum mentor intro length. */
20    public const INTRO_TEXT_LENGTH = 240;
21
22    /**
23     * Returns a Title to the signup page, if it exists
24     *
25     * @return Title|null
26     */
27    abstract public function getSignupTitle(): ?Title;
28
29    /**
30     * Construct a Mentor object for given UserIdentity
31     *
32     * This is useful for when you know the mentor's username, and need MentorManager to provide
33     * specific details about them.
34     *
35     * The caller needs to ensure $mentorUser is a mentor (otherwise, implementation may
36     * throw). You can use MentorProvider::isMentor() for that purpose.
37     *
38     * @param UserIdentity $mentorUser Caller needs to ensure $mentorUser is a mentor
39     * @param UserIdentity|null $menteeUser If passed, may be used to customize message using
40     * mentee's username.
41     * @return Mentor
42     */
43    abstract public function newMentorFromUserIdentity(
44        UserIdentity $mentorUser,
45        ?UserIdentity $menteeUser = null
46    ): Mentor;
47
48    /**
49     * Get list of source Title objects
50     *
51     * A hook will run MentorProvider::invalidateCache() if it sees an edit made on any of those
52     * pages.
53     *
54     * @internal To be used from MentorHooks only
55     * @return Title[]
56     */
57    public function getSourceTitles(): array {
58        return [];
59    }
60
61    /**
62     * Invalidate the WAN cache
63     *
64     * @note Default implementation does not do anything.
65     */
66    public function invalidateCache(): void {
67    }
68
69    /**
70     * Checks if an user is a mentor (regardless of their auto-assignment status)
71     * @param UserIdentity $user
72     * @return bool
73     */
74    public function isMentor( UserIdentity $user ): bool {
75        return $user->isRegistered() && in_array( $user->getName(), $this->getMentorsSafe() );
76    }
77
78    /**
79     * Get all mentors, regardless on their auto-assignment status
80     * @throws WikiConfigException If the mentor page cannot be fetched due to misconfiguration.
81     * @return string[] List of mentors usernames.
82     */
83    public function getMentors(): array {
84        return array_unique(
85            array_merge(
86                $this->getAutoAssignedMentors(),
87                $this->getManuallyAssignedMentors()
88            )
89        );
90    }
91
92    /**
93     * Get all mentors, regardless of their auto-assignment status
94     *
95     * This does the same thing as getMentors(), but it suppresses any instance
96     * of WikiConfigException (and returns an empty array instead).
97     *
98     * @return string[]
99     */
100    public function getMentorsSafe(): array {
101        $mentors = [];
102        try {
103            $mentors = array_merge( $mentors, $this->getAutoAssignedMentors() );
104        } catch ( WikiConfigException $e ) {
105        }
106        try {
107            $mentors = array_merge( $mentors, $this->getManuallyAssignedMentors() );
108        } catch ( WikiConfigException $e ) {
109        }
110        return array_unique( $mentors );
111    }
112
113    /**
114     * Get all the mentors who are automatically assigned to mentees.
115     * @throws WikiConfigException If the mentor page cannot be fetched due to misconfiguration.
116     * @return string[] List of mentor usernames.
117     */
118    abstract public function getAutoAssignedMentors(): array;
119
120    /**
121     * Get weighted list of automatically assigned mentors
122     *
123     * If a mentor is configured to receive more mentees than others, the returned array will
124     * have their name multiple times.
125     *
126     * @return string[] Array of usernames
127     */
128    abstract public function getWeightedAutoAssignedMentors(): array;
129
130    /**
131     * Get a list of mentors who are not automatically assigned to mentees.
132     * @throws WikiConfigException If the mentor page cannot be fetched due to misconfiguration.
133     * @return string[] List of mentors usernames.
134     */
135    abstract public function getManuallyAssignedMentors(): array;
136}