Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
2 / 2
 CRAP
100.00% covered (success)
100.00%
1 / 1
TrackingTool
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
2 / 2
 2
100.00% covered (success)
100.00%
1 / 1
 __construct
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 getDBID
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 validateToolAddition
n/a
0 / 0
n/a
0 / 0
 0
 addToNewEvent
n/a
0 / 0
n/a
0 / 0
 0
 addToExistingEvent
n/a
0 / 0
n/a
0 / 0
 0
 validateToolRemoval
n/a
0 / 0
n/a
0 / 0
 0
 removeFromEvent
n/a
0 / 0
n/a
0 / 0
 0
 validateEventDeletion
n/a
0 / 0
n/a
0 / 0
 0
 onEventDeleted
n/a
0 / 0
n/a
0 / 0
 0
 validateParticipantAdded
n/a
0 / 0
n/a
0 / 0
 0
 addParticipant
n/a
0 / 0
n/a
0 / 0
 0
 validateParticipantsRemoved
n/a
0 / 0
n/a
0 / 0
 0
 removeParticipants
n/a
0 / 0
n/a
0 / 0
 0
 buildToolEventURL
n/a
0 / 0
n/a
0 / 0
 0
 extractEventIDFromURL
n/a
0 / 0
n/a
0 / 0
 0
1<?php
2
3declare( strict_types=1 );
4
5namespace MediaWiki\Extension\CampaignEvents\TrackingTool\Tool;
6
7use MediaWiki\Extension\CampaignEvents\Event\EventRegistration;
8use MediaWiki\Extension\CampaignEvents\Event\ExistingEventRegistration;
9use MediaWiki\Extension\CampaignEvents\MWEntity\CentralUser;
10use MediaWiki\Extension\CampaignEvents\TrackingTool\InvalidToolURLException;
11use StatusValue;
12
13/**
14 * This is the base class for every tracking tool. Each subclass represents a specific tool, and can potentially be
15 * used for multiple instances of that tool. These objects are not value objects; instead, they follow the handler
16 * pattern, and are used to perform actions on each tracking tool.
17 * Subclasses must NOT be instantiated directly, use TrackingToolRegistry instead.
18 *
19 * There are exactly two methods defined for each action, one that validates the change and one that executes it (like
20 * validateToolRemoval() and removeFromEvent()), in a sort of two-phase commit approach. In particular:
21 *  - validation methods are called before any write action occurs, giving tracking tools a chance to validate the
22 *    change before any data is committed. Any anticipated error should be reported at this stage.
23 *  - action methods are called when data may have already been written. It is still possible to fail at this stage,
24 *    in which case the change to the data will be rolled back if possible, but this is not guaranteed and failures at
25 *    this stage should be avoided as much as possible. Ideally, only unpredictable failures (e.g., network errors)
26 *    should happen here.
27 * @see \MediaWiki\Extension\CampaignEvents\TrackingTool\TrackingToolEventWatcher which uses these methods.
28 *
29 * Note that in the future, when more tools are added, these methods may be moved to separate interfaces,
30 * depending on the capabilities of each tool.
31 */
32abstract class TrackingTool {
33    private int $dbID;
34    protected string $baseURL;
35
36    /**
37     * @param int $dbID ID that identifies this specific tracking tool in the DB
38     * @param string $baseURL Base URL of this instance
39     * @param array $extra Any additional information needed by this instance.
40     */
41    public function __construct( int $dbID, string $baseURL, array $extra ) {
42        $this->dbID = $dbID;
43        $this->baseURL = $baseURL;
44    }
45
46    /**
47     * Returns the ID that should be used to store this specific tracking tool into the database.
48     * @return int
49     */
50    public function getDBID(): int {
51        return $this->dbID;
52    }
53
54    /**
55     * @param EventRegistration $event That the tool will be added to
56     * @param CentralUser[] $organizers
57     * @param string $toolEventID
58     * @return StatusValue
59     */
60    abstract public function validateToolAddition(
61        EventRegistration $event,
62        array $organizers,
63        string $toolEventID
64    ): StatusValue;
65
66    /**
67     * @param int $eventID
68     * @param EventRegistration $event That the tool will be added to
69     * @param CentralUser[] $organizers
70     * @param string $toolEventID
71     * @return StatusValue
72     */
73    abstract public function addToNewEvent(
74        int $eventID,
75        EventRegistration $event,
76        array $organizers,
77        string $toolEventID
78    ): StatusValue;
79
80    /**
81     * @param ExistingEventRegistration $event That the tool will be added to
82     * @param CentralUser[] $organizers
83     * @param string $toolEventID
84     * @return StatusValue
85     */
86    abstract public function addToExistingEvent(
87        ExistingEventRegistration $event,
88        array $organizers,
89        string $toolEventID
90    ): StatusValue;
91
92    /**
93     * @param ExistingEventRegistration $event That the tool will be removed from
94     * @param string $toolEventID
95     * @return StatusValue
96     */
97    abstract public function validateToolRemoval(
98        ExistingEventRegistration $event,
99        string $toolEventID
100    ): StatusValue;
101
102    /**
103     * @param ExistingEventRegistration $event That the tool will be removed from
104     * @param string $toolEventID
105     * @return StatusValue
106     */
107    abstract public function removeFromEvent(
108        ExistingEventRegistration $event,
109        string $toolEventID
110    ): StatusValue;
111
112    /**
113     * @param ExistingEventRegistration $event
114     * @param string $toolEventID
115     * @return StatusValue
116     */
117    abstract public function validateEventDeletion(
118        ExistingEventRegistration $event,
119        string $toolEventID
120    ): StatusValue;
121
122    /**
123     * @param ExistingEventRegistration $event
124     * @param string $toolEventID
125     * @return StatusValue
126     */
127    abstract public function onEventDeleted(
128        ExistingEventRegistration $event,
129        string $toolEventID
130    ): StatusValue;
131
132    /**
133     * @param ExistingEventRegistration $event
134     * @param string $toolEventID
135     * @param CentralUser $participant
136     * @param bool $private
137     * @return StatusValue
138     */
139    abstract public function validateParticipantAdded(
140        ExistingEventRegistration $event,
141        string $toolEventID,
142        CentralUser $participant,
143        bool $private
144    ): StatusValue;
145
146    /**
147     * @param ExistingEventRegistration $event
148     * @param string $toolEventID
149     * @param CentralUser $participant
150     * @param bool $private
151     * @return StatusValue
152     */
153    abstract public function addParticipant(
154        ExistingEventRegistration $event,
155        string $toolEventID,
156        CentralUser $participant,
157        bool $private
158    ): StatusValue;
159
160    /**
161     * @param ExistingEventRegistration $event
162     * @param string $toolEventID
163     * @param CentralUser[]|null $participants Array of participants to remove if $invertSelection is false,
164     * or array of participants to keep if $invertSelection is true. Null means remove everyone, regardless of
165     * $invertSelection.
166     * @param bool $invertSelection
167     * @return StatusValue
168     */
169    abstract public function validateParticipantsRemoved(
170        ExistingEventRegistration $event,
171        string $toolEventID,
172        ?array $participants,
173        bool $invertSelection
174    ): StatusValue;
175
176    /**
177     * @param ExistingEventRegistration $event
178     * @param string $toolEventID
179     * @param CentralUser[]|null $participants Array of participants to remove if $invertSelection is false,
180     * or array of participants to keep if $invertSelection is true. Null means remove everyone, regardless of
181     * $invertSelection.
182     * @param bool $invertSelection
183     * @return StatusValue
184     */
185    abstract public function removeParticipants(
186        ExistingEventRegistration $event,
187        string $toolEventID,
188        ?array $participants,
189        bool $invertSelection
190    ): StatusValue;
191
192    /**
193     * Given the ID of an event in this tool, return the URL of the resource corresponding to the event on the tool
194     * itself.
195     *
196     * @param string $baseURL
197     * @param string $toolEventID
198     * @return string
199     */
200    abstract public static function buildToolEventURL( string $baseURL, string $toolEventID ): string;
201
202    /**
203     * Given the URL of an event in this tool, return the corresponding event ID in the tool.
204     *
205     * @param string $baseURL
206     * @param string $url
207     * @return string
208     * @throws InvalidToolURLException
209     */
210    abstract public static function extractEventIDFromURL( string $baseURL, string $url ): string;
211}