recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1<?php
2
3/**
4 * A trigger clock implements scheduling rules for an event.
5 *
6 * Two examples of triggered events are a subscription which bills on the 12th
7 * of every month, or a meeting reminder which sends an email 15 minutes before
8 * an event. A trigger clock contains the logic to figure out exactly when
9 * those times are.
10 *
11 * For example, it might schedule an event every hour, or every Thursday, or on
12 * the 15th of every month at 3PM, or only at a specific time.
13 */
14abstract class PhabricatorTriggerClock extends Phobject {
15
16 private $properties;
17
18 public function __construct(array $properties) {
19 $this->validateProperties($properties);
20 $this->properties = $properties;
21 }
22
23 public function getProperties() {
24 return $this->properties;
25 }
26
27 public function getProperty($key, $default = null) {
28 return idx($this->properties, $key, $default);
29 }
30
31
32 /**
33 * Validate clock configuration.
34 *
35 * @param map<string, mixed> $properties Map of clock properties.
36 * @return void
37 */
38 abstract public function validateProperties(array $properties);
39
40
41 /**
42 * Get the next occurrence of this event.
43 *
44 * This method takes two parameters: the last time this event occurred (or
45 * null if it has never triggered before) and a flag distinguishing between
46 * a normal reschedule (after a successful trigger) or an update because of
47 * a trigger change.
48 *
49 * If this event does not occur again, return `null` to stop it from being
50 * rescheduled. For example, a meeting reminder may be sent only once before
51 * the meeting.
52 *
53 * If this event does occur again, return the epoch timestamp of the next
54 * occurrence.
55 *
56 * When performing routine reschedules, the event must move forward in time:
57 * any timestamp you return must be later than the last event. For instance,
58 * if this event triggers an invoice, the next invoice date must be after
59 * the previous invoice date. This prevents an event from looping more than
60 * once per second.
61 *
62 * In contrast, after an update (not a routine reschedule), the next event
63 * may be scheduled at any time. For example, if a meeting is moved from next
64 * week to 3 minutes from now, the clock may reschedule the notification to
65 * occur 12 minutes ago. This will cause it to execute immediately.
66 *
67 * @param int|null $last_epoch Last time the event occurred, or null if it
68 * has never triggered before.
69 * @param bool $is_reschedule True if this is a reschedule after a successful
70 * trigger.
71 * @return int|null Next event, or null to decline to reschedule.
72 */
73 abstract public function getNextEventEpoch($last_epoch, $is_reschedule);
74
75}