classes
7 years ago
deprecated
7 years ago
lib
7 years ago
action-scheduler.php
7 years ago
functions.php
7 years ago
license.txt
7 years ago
functions.php
210 lines
| 1 | <?php |
| 2 | |
| 3 | /** |
| 4 | * General API functions for scheduling actions |
| 5 | */ |
| 6 | |
| 7 | /** |
| 8 | * Schedule an action to run one time |
| 9 | * |
| 10 | * @param int $timestamp When the job will run |
| 11 | * @param string $hook The hook to trigger |
| 12 | * @param array $args Arguments to pass when the hook triggers |
| 13 | * @param string $group The group to assign this job to |
| 14 | * |
| 15 | * @return string The job ID |
| 16 | */ |
| 17 | function as_schedule_single_action( $timestamp, $hook, $args = array(), $group = '' ) { |
| 18 | return ActionScheduler::factory()->single( $hook, $args, $timestamp, $group ); |
| 19 | } |
| 20 | |
| 21 | /** |
| 22 | * Schedule a recurring action |
| 23 | * |
| 24 | * @param int $timestamp When the first instance of the job will run |
| 25 | * @param int $interval_in_seconds How long to wait between runs |
| 26 | * @param string $hook The hook to trigger |
| 27 | * @param array $args Arguments to pass when the hook triggers |
| 28 | * @param string $group The group to assign this job to |
| 29 | * |
| 30 | * @return string The job ID |
| 31 | */ |
| 32 | function as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args = array(), $group = '' ) { |
| 33 | return ActionScheduler::factory()->recurring( $hook, $args, $timestamp, $interval_in_seconds, $group ); |
| 34 | } |
| 35 | |
| 36 | /** |
| 37 | * Schedule an action that recurs on a cron-like schedule. |
| 38 | * |
| 39 | * @param int $timestamp The schedule will start on or after this time |
| 40 | * @param string $schedule A cron-link schedule string |
| 41 | * @see http://en.wikipedia.org/wiki/Cron |
| 42 | * * * * * * * |
| 43 | * ┬ ┬ ┬ ┬ ┬ ┬ |
| 44 | * | | | | | | |
| 45 | * | | | | | + year [optional] |
| 46 | * | | | | +----- day of week (0 - 7) (Sunday=0 or 7) |
| 47 | * | | | +---------- month (1 - 12) |
| 48 | * | | +--------------- day of month (1 - 31) |
| 49 | * | +-------------------- hour (0 - 23) |
| 50 | * +------------------------- min (0 - 59) |
| 51 | * @param string $hook The hook to trigger |
| 52 | * @param array $args Arguments to pass when the hook triggers |
| 53 | * @param string $group The group to assign this job to |
| 54 | * |
| 55 | * @return string The job ID |
| 56 | */ |
| 57 | function as_schedule_cron_action( $timestamp, $schedule, $hook, $args = array(), $group = '' ) { |
| 58 | return ActionScheduler::factory()->cron( $hook, $args, $timestamp, $schedule, $group ); |
| 59 | } |
| 60 | |
| 61 | /** |
| 62 | * Cancel the next occurrence of a scheduled action. |
| 63 | * |
| 64 | * While only the next instance of a recurring or cron action is unscheduled by this method, that will also prevent |
| 65 | * all future instances of that recurring or cron action from being run. Recurring and cron actions are scheduled in |
| 66 | * a sequence instead of all being scheduled at once. Each successive occurrence of a recurring action is scheduled |
| 67 | * only after the former action is run. If the next instance is never run, because it's unscheduled by this function, |
| 68 | * then the following instance will never be scheduled (or exist), which is effectively the same as being unscheduled |
| 69 | * by this method also. |
| 70 | * |
| 71 | * @param string $hook The hook that the job will trigger |
| 72 | * @param array $args Args that would have been passed to the job |
| 73 | * @param string $group |
| 74 | * |
| 75 | * @return string The scheduled action ID if a scheduled action was found, or empty string if no matching action found. |
| 76 | */ |
| 77 | function as_unschedule_action( $hook, $args = array(), $group = '' ) { |
| 78 | $params = array(); |
| 79 | if ( is_array($args) ) { |
| 80 | $params['args'] = $args; |
| 81 | } |
| 82 | if ( !empty($group) ) { |
| 83 | $params['group'] = $group; |
| 84 | } |
| 85 | $job_id = ActionScheduler::store()->find_action( $hook, $params ); |
| 86 | |
| 87 | if ( ! empty( $job_id ) ) { |
| 88 | ActionScheduler::store()->cancel_action( $job_id ); |
| 89 | } |
| 90 | |
| 91 | return $job_id; |
| 92 | } |
| 93 | |
| 94 | /** |
| 95 | * Cancel all occurrences of a scheduled action. |
| 96 | * |
| 97 | * @param string $hook The hook that the job will trigger |
| 98 | * @param array $args Args that would have been passed to the job |
| 99 | * @param string $group |
| 100 | */ |
| 101 | function as_unschedule_all_actions( $hook, $args = array(), $group = '' ) { |
| 102 | do { |
| 103 | $unscheduled_action = as_unschedule_action( $hook, $args, $group ); |
| 104 | } while ( ! empty( $unscheduled_action ) ); |
| 105 | } |
| 106 | |
| 107 | /** |
| 108 | * @param string $hook |
| 109 | * @param array $args |
| 110 | * @param string $group |
| 111 | * |
| 112 | * @return int|bool The timestamp for the next occurrence, or false if nothing was found |
| 113 | */ |
| 114 | function as_next_scheduled_action( $hook, $args = NULL, $group = '' ) { |
| 115 | $params = array(); |
| 116 | if ( is_array($args) ) { |
| 117 | $params['args'] = $args; |
| 118 | } |
| 119 | if ( !empty($group) ) { |
| 120 | $params['group'] = $group; |
| 121 | } |
| 122 | $job_id = ActionScheduler::store()->find_action( $hook, $params ); |
| 123 | if ( empty($job_id) ) { |
| 124 | return false; |
| 125 | } |
| 126 | $job = ActionScheduler::store()->fetch_action( $job_id ); |
| 127 | $next = $job->get_schedule()->next(); |
| 128 | if ( $next ) { |
| 129 | return (int)($next->format('U')); |
| 130 | } |
| 131 | return false; |
| 132 | } |
| 133 | |
| 134 | /** |
| 135 | * Find scheduled actions |
| 136 | * |
| 137 | * @param array $args Possible arguments, with their default values: |
| 138 | * 'hook' => '' - the name of the action that will be triggered |
| 139 | * 'args' => NULL - the args array that will be passed with the action |
| 140 | * 'date' => NULL - the scheduled date of the action. Expects a DateTime object, a unix timestamp, or a string that can parsed with strtotime(). Used in UTC timezone. |
| 141 | * 'date_compare' => '<=' - operator for testing "date". accepted values are '!=', '>', '>=', '<', '<=', '=' |
| 142 | * 'modified' => NULL - the date the action was last updated. Expects a DateTime object, a unix timestamp, or a string that can parsed with strtotime(). Used in UTC timezone. |
| 143 | * 'modified_compare' => '<=' - operator for testing "modified". accepted values are '!=', '>', '>=', '<', '<=', '=' |
| 144 | * 'group' => '' - the group the action belongs to |
| 145 | * 'status' => '' - ActionScheduler_Store::STATUS_COMPLETE or ActionScheduler_Store::STATUS_PENDING |
| 146 | * 'claimed' => NULL - TRUE to find claimed actions, FALSE to find unclaimed actions, a string to find a specific claim ID |
| 147 | * 'per_page' => 5 - Number of results to return |
| 148 | * 'offset' => 0 |
| 149 | * 'orderby' => 'date' - accepted values are 'hook', 'group', 'modified', or 'date' |
| 150 | * 'order' => 'ASC' |
| 151 | * |
| 152 | * @param string $return_format OBJECT, ARRAY_A, or ids |
| 153 | * |
| 154 | * @return array |
| 155 | */ |
| 156 | function as_get_scheduled_actions( $args = array(), $return_format = OBJECT ) { |
| 157 | $store = ActionScheduler::store(); |
| 158 | foreach ( array('date', 'modified') as $key ) { |
| 159 | if ( isset($args[$key]) ) { |
| 160 | $args[$key] = as_get_datetime_object($args[$key]); |
| 161 | } |
| 162 | } |
| 163 | $ids = $store->query_actions( $args ); |
| 164 | |
| 165 | if ( $return_format == 'ids' || $return_format == 'int' ) { |
| 166 | return $ids; |
| 167 | } |
| 168 | |
| 169 | $actions = array(); |
| 170 | foreach ( $ids as $action_id ) { |
| 171 | $actions[$action_id] = $store->fetch_action( $action_id ); |
| 172 | } |
| 173 | |
| 174 | if ( $return_format == ARRAY_A ) { |
| 175 | foreach ( $actions as $action_id => $action_object ) { |
| 176 | $actions[$action_id] = get_object_vars($action_object); |
| 177 | } |
| 178 | } |
| 179 | |
| 180 | return $actions; |
| 181 | } |
| 182 | |
| 183 | /** |
| 184 | * Helper function to create an instance of DateTime based on a given |
| 185 | * string and timezone. By default, will return the current date/time |
| 186 | * in the UTC timezone. |
| 187 | * |
| 188 | * Needed because new DateTime() called without an explicit timezone |
| 189 | * will create a date/time in PHP's timezone, but we need to have |
| 190 | * assurance that a date/time uses the right timezone (which we almost |
| 191 | * always want to be UTC), which means we need to always include the |
| 192 | * timezone when instantiating datetimes rather than leaving it up to |
| 193 | * the PHP default. |
| 194 | * |
| 195 | * @param mixed $date_string A date/time string. Valid formats are explained in http://php.net/manual/en/datetime.formats.php |
| 196 | * @param string $timezone A timezone identifier, like UTC or Europe/Lisbon. The list of valid identifiers is available http://php.net/manual/en/timezones.php |
| 197 | * |
| 198 | * @return ActionScheduler_DateTime |
| 199 | */ |
| 200 | function as_get_datetime_object( $date_string = null, $timezone = 'UTC' ) { |
| 201 | if ( is_object( $date_string ) && $date_string instanceof DateTime ) { |
| 202 | $date = new ActionScheduler_DateTime( $date_string->format( 'Y-m-d H:i:s' ), new DateTimeZone( $timezone ) ); |
| 203 | } elseif ( is_numeric( $date_string ) ) { |
| 204 | $date = new ActionScheduler_DateTime( '@' . $date_string, new DateTimeZone( $timezone ) ); |
| 205 | } else { |
| 206 | $date = new ActionScheduler_DateTime( $date_string, new DateTimeZone( $timezone ) ); |
| 207 | } |
| 208 | return $date; |
| 209 | } |
| 210 |