Use as_ prefix not wc_ prefix for public APIs

To avoid confusion once Action Scheduler is included in WooCommerce core,
and it provides a different set of public APIs for working with the action
queue.

Author: Brent Shepherd

README.md

@@ -137,13 +137,13 @@ The Action Scheduler API functions are designed to mirror the WordPress [WP-Cron
 
 Functions return similar values and accept similar arguments to their WP-Cron counterparts. The notable differences are:
 
-* `wc_schedule_single_action()` & `wc_schedule_recurring_action()` will return the post ID of the scheduled action rather than boolean indicating whether the event was scheduled
-* `wc_schedule_recurring_action()` takes an interval in seconds as the recurring interval rather than an arbitrary string
-* `wc_schedule_single_action()` & `wc_schedule_recurring_action()` can accept a `$group` parameter to group different actions for the one plugin together.
-* the `wp_` prefix is substituted with `wc_` and the term `event` is replaced with `action`
+* `as_schedule_single_action()` & `as_schedule_recurring_action()` will return the post ID of the scheduled action rather than boolean indicating whether the event was scheduled
+* `as_schedule_recurring_action()` takes an interval in seconds as the recurring interval rather than an arbitrary string
+* `as_schedule_single_action()` & `as_schedule_recurring_action()` can accept a `$group` parameter to group different actions for the one plugin together.
+* the `wp_` prefix is substituted with `as_` and the term `event` is replaced with `action`
 
 
-#### Function Reference / `wc_schedule_single_action()`
+#### Function Reference / `as_schedule_single_action()`
 
 ##### Description
 
@@ -152,7 +152,7 @@ Schedule an action to run one time.
 ##### Usage
 
 ```php
-<?php wc_schedule_single_action( $timestamp, $hook, $args, $group ); ?>
+<?php as_schedule_single_action( $timestamp, $hook, $args, $group ); ?>
 ````
 
 ##### Parameters
@@ -167,7 +167,7 @@ Schedule an action to run one time.
 (integer) the action's ID in the [posts](http://codex.wordpress.org/Database_Description#Table_Overview) table.
 
 
-#### Function Reference / `wc_schedule_recurring_action()`
+#### Function Reference / `as_schedule_recurring_action()`
 
 ##### Description
 
@@ -176,7 +176,7 @@ Schedule an action to run repeatedly with a specified interval in seconds.
 ##### Usage
 
 ```php
-<?php wc_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args, $group ); ?>
+<?php as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args, $group ); ?>
 ````
 
 ##### Parameters
@@ -192,7 +192,7 @@ Schedule an action to run repeatedly with a specified interval in seconds.
 (integer) the action's ID in the [posts](http://codex.wordpress.org/Database_Description#Table_Overview) table.
 
 
-#### Function Reference / `wc_schedule_cron_action()`
+#### Function Reference / `as_schedule_cron_action()`
 
 ##### Description
 
@@ -201,7 +201,7 @@ Schedule an action that recurs on a cron-like schedule.
 ##### Usage
 
 ```php
-<?php wc_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group ); ?>
+<?php as_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group ); ?>
 ````
 
 ##### Parameters
@@ -217,7 +217,7 @@ Schedule an action that recurs on a cron-like schedule.
 (integer) the action's ID in the [posts](http://codex.wordpress.org/Database_Description#Table_Overview) table.
 
 
-#### Function Reference / `wc_unschedule_action()`
+#### Function Reference / `as_unschedule_action()`
 
 ##### Description
 
@@ -226,7 +226,7 @@ Cancel the next occurrence of a job.
 ##### Usage
 
 ```php
-<?php wc_unschedule_action( $hook, $args, $group ); ?>
+<?php as_unschedule_action( $hook, $args, $group ); ?>
 ````
 
 ##### Parameters
@@ -240,7 +240,7 @@ Cancel the next occurrence of a job.
 (null)
 
 
-#### Function Reference / `wc_next_scheduled_action()`
+#### Function Reference / `as_next_scheduled_action()`
 
 ##### Description
 
@@ -249,7 +249,7 @@ Returns the next timestamp for a scheduled action.
 ##### Usage
 
 ```php
-<?php wc_next_scheduled_action( $hook, $args, $group ); ?>
+<?php as_next_scheduled_action( $hook, $args, $group ); ?>
 ````
 
 ##### Parameters
@@ -263,7 +263,7 @@ Returns the next timestamp for a scheduled action.
 (integer|boolean) The timestamp for the next occurrence, or false if nothing was found.
 
 
-#### Function Reference / `wc_get_scheduled_actions()`
+#### Function Reference / `as_get_scheduled_actions()`
 
 ##### Description
 
@@ -272,7 +272,7 @@ Find scheduled actions.
 ##### Usage
 
 ```php
-<?php wc_get_scheduled_actions( $args, $return_format ); ?>
+<?php as_get_scheduled_actions( $args, $return_format ); ?>
 ````
 
 ##### Parameters

classes/ActionScheduler.php

@@ -97,6 +97,10 @@ public static function init( $plugin_file ) {
 
 		require_once( self::plugin_path('functions.php') );
 
+		if ( apply_filters( 'action_scheduler_load_deprecated_functions', true ) ) {
+			require_once( self::plugin_path('deprecated/functions.php') );
+		}
+
 		if ( defined( 'WP_CLI' ) && WP_CLI ) {
 			WP_CLI::add_command( 'action-scheduler', 'ActionScheduler_WPCLI_Scheduler_command' );
 		}

deprecated/functions.php

@@ -0,0 +1,126 @@
+<?php
+
+/**
+ * Deprecated API functions for scheduling actions
+ *
+ * Functions with the wc prefix were deprecated to avoid confusion with
+ * Action Scheduler being included in WooCommerce core, and it providing
+ * a different set of APIs for working with the action queue.
+ */
+
+/**
+ * Schedule an action to run one time
+ *
+ * @param int $timestamp When the job will run
+ * @param string $hook The hook to trigger
+ * @param array $args Arguments to pass when the hook triggers
+ * @param string $group The group to assign this job to
+ *
+ * @return string The job ID
+ */
+function wc_schedule_single_action( $timestamp, $hook, $args = array(), $group = '' ) {
+	_deprecated_function( __FUNCTION__, '2.1.0', 'as_schedule_single_action()' );
+	return as_schedule_single_action( $timestamp, $hook, $args, $group );
+}
+
+/**
+ * Schedule a recurring action
+ *
+ * @param int $timestamp When the first instance of the job will run
+ * @param int $interval_in_seconds How long to wait between runs
+ * @param string $hook The hook to trigger
+ * @param array $args Arguments to pass when the hook triggers
+ * @param string $group The group to assign this job to
+ *
+ * @deprecated 2.1.0
+ *
+ * @return string The job ID
+ */
+function wc_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args = array(), $group = '' ) {
+	_deprecated_function( __FUNCTION__, '2.1.0', 'as_schedule_recurring_action()' );
+	return as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args, $group );
+}
+
+/**
+ * Schedule an action that recurs on a cron-like schedule.
+ *
+ * @param int $timestamp The schedule will start on or after this time
+ * @param string $schedule A cron-link schedule string
+ * @see http://en.wikipedia.org/wiki/Cron
+ *   *    *    *    *    *    *
+ *   ┬    ┬    ┬    ┬    ┬    ┬
+ *   |    |    |    |    |    |
+ *   |    |    |    |    |    + year [optional]
+ *   |    |    |    |    +----- day of week (0 - 7) (Sunday=0 or 7)
+ *   |    |    |    +---------- month (1 - 12)
+ *   |    |    +--------------- day of month (1 - 31)
+ *   |    +-------------------- hour (0 - 23)
+ *   +------------------------- min (0 - 59)
+ * @param string $hook The hook to trigger
+ * @param array $args Arguments to pass when the hook triggers
+ * @param string $group The group to assign this job to
+ *
+ * @deprecated 2.1.0
+ *
+ * @return string The job ID
+ */
+function wc_schedule_cron_action( $timestamp, $schedule, $hook, $args = array(), $group = '' ) {
+	_deprecated_function( __FUNCTION__, '2.1.0', 'as_schedule_cron_action()' );
+	return as_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group );
+}
+
+/**
+ * Cancel the next occurrence of a job.
+ *
+ * @param string $hook The hook that the job will trigger
+ * @param array $args Args that would have been passed to the job
+ * @param string $group
+ *
+ * @deprecated 2.1.0
+ */
+function wc_unschedule_action( $hook, $args = array(), $group = '' ) {
+	_deprecated_function( __FUNCTION__, '2.1.0', 'as_unschedule_action()' );
+	as_unschedule_action( $hook, $args, $group );
+}
+
+/**
+ * @param string $hook
+ * @param array $args
+ * @param string $group
+ *
+ * @deprecated 2.1.0
+ *
+ * @return int|bool The timestamp for the next occurrence, or false if nothing was found
+ */
+function wc_next_scheduled_action( $hook, $args = NULL, $group = '' ) {
+	_deprecated_function( __FUNCTION__, '2.1.0', 'as_next_scheduled_action()' );
+	return as_next_scheduled_action( $hook, $args, $group );
+}
+
+/**
+ * Find scheduled actions
+ *
+ * @param array $args Possible arguments, with their default values:
+ *        'hook' => '' - the name of the action that will be triggered
+ *        'args' => NULL - the args array that will be passed with the action
+ *        '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.
+ *        'date_compare' => '<=' - operator for testing "date". accepted values are '!=', '>', '>=', '<', '<=', '='
+ *        '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.
+ *        'modified_compare' => '<=' - operator for testing "modified". accepted values are '!=', '>', '>=', '<', '<=', '='
+ *        'group' => '' - the group the action belongs to
+ *        'status' => '' - ActionScheduler_Store::STATUS_COMPLETE or ActionScheduler_Store::STATUS_PENDING
+ *        'claimed' => NULL - TRUE to find claimed actions, FALSE to find unclaimed actions, a string to find a specific claim ID
+ *        'per_page' => 5 - Number of results to return
+ *        'offset' => 0
+ *        'orderby' => 'date' - accepted values are 'hook', 'group', 'modified', or 'date'
+ *        'order' => 'ASC'
+ * @param string $return_format OBJECT, ARRAY_A, or ids
+ *
+ * @deprecated 2.1.0
+ *
+ * @return array
+ */
+function wc_get_scheduled_actions( $args = array(), $return_format = OBJECT ) {
+	_deprecated_function( __FUNCTION__, '2.1.0', 'as_get_scheduled_actions()' );
+	return as_get_scheduled_actions( $args, $return_format );
+}

functions.php

@@ -14,7 +14,7 @@
  *
  * @return string The job ID
  */
-function wc_schedule_single_action( $timestamp, $hook, $args = array(), $group = '' ) {
+function as_schedule_single_action( $timestamp, $hook, $args = array(), $group = '' ) {
 	return ActionScheduler::factory()->single( $hook, $args, $timestamp, $group );
 }
 
@@ -29,7 +29,7 @@ function wc_schedule_single_action( $timestamp, $hook, $args = array(), $group =
  *
  * @return string The job ID
  */
-function wc_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args = array(), $group = '' ) {
+function as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args = array(), $group = '' ) {
 	return ActionScheduler::factory()->recurring( $hook, $args, $timestamp, $interval_in_seconds, $group );
 }
 
@@ -54,7 +54,7 @@ function wc_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook,
  *
  * @return string The job ID
  */
-function wc_schedule_cron_action( $timestamp, $schedule, $hook, $args = array(), $group = '' ) {
+function as_schedule_cron_action( $timestamp, $schedule, $hook, $args = array(), $group = '' ) {
 	return ActionScheduler::factory()->cron( $hook, $args, $timestamp, $schedule, $group );
 }
 
@@ -65,7 +65,7 @@ function wc_schedule_cron_action( $timestamp, $schedule, $hook, $args = array(),
  * @param array $args Args that would have been passed to the job
  * @param string $group
  */
-function wc_unschedule_action( $hook, $args = array(), $group = '' ) {
+function as_unschedule_action( $hook, $args = array(), $group = '' ) {
 	$params = array();
 	if ( is_array($args) ) {
 		$params['args'] = $args;
@@ -88,7 +88,7 @@ function wc_unschedule_action( $hook, $args = array(), $group = '' ) {
  *
  * @return int|bool The timestamp for the next occurrence, or false if nothing was found
  */
-function wc_next_scheduled_action( $hook, $args = NULL, $group = '' ) {
+function as_next_scheduled_action( $hook, $args = NULL, $group = '' ) {
 	$params = array();
 	if ( is_array($args) ) {
 		$params['args'] = $args;
@@ -130,7 +130,7 @@ function wc_next_scheduled_action( $hook, $args = NULL, $group = '' ) {
  *
  * @return array
  */
-function wc_get_scheduled_actions( $args = array(), $return_format = OBJECT ) {
+function as_get_scheduled_actions( $args = array(), $return_format = OBJECT ) {
 	$store = ActionScheduler::store();
 	foreach ( array('date', 'modified') as $key ) {
 		if ( isset($args[$key]) ) {

tests/phpunit/logging/ActionScheduler_wpCommentLogger_Test.php

@@ -12,7 +12,7 @@ public function test_default_logger() {
 	}
 
 	public function test_add_log_entry() {
-		$action_id = wc_schedule_single_action( time(), 'a hook' );
+		$action_id = as_schedule_single_action( time(), 'a hook' );
 		$logger = ActionScheduler::logger();
 		$message = 'Logging that something happened';
 		$log_id = $logger->log( $action_id, $message );
@@ -42,7 +42,7 @@ public function test_erroneous_entry_id() {
 	}
 
 	public function test_storage_comments() {
-		$action_id = wc_schedule_single_action( time(), 'a hook' );
+		$action_id = as_schedule_single_action( time(), 'a hook' );
 		$logger = ActionScheduler::logger();
 		$logs = $logger->get_logs( $action_id );
 		$expected = new ActionScheduler_LogEntry( $action_id, 'action created' );
@@ -62,7 +62,7 @@ protected function log_entry_to_array( $logs ) {
 	}
 
 	public function test_execution_comments() {
-		$action_id = wc_schedule_single_action( time(), 'a hook' );
+		$action_id = as_schedule_single_action( time(), 'a hook' );
 		$logger = ActionScheduler::logger();
 		$started = new ActionScheduler_LogEntry( $action_id, 'action started' );
 		$finished = new ActionScheduler_LogEntry( $action_id, 'action complete' );
@@ -78,7 +78,7 @@ public function test_execution_comments() {
 	public function test_failed_execution_comments() {
 		$hook = md5(rand());
 		add_action( $hook, array( $this, '_a_hook_callback_that_throws_an_exception' ) );
-		$action_id = wc_schedule_single_action( time(), $hook );
+		$action_id = as_schedule_single_action( time(), $hook );
 		$logger = ActionScheduler::logger();
 		$started = new ActionScheduler_LogEntry( $action_id, 'action started' );
 		$finished = new ActionScheduler_LogEntry( $action_id, 'action complete' );
@@ -95,7 +95,7 @@ public function test_failed_execution_comments() {
 
 	public function test_fatal_error_comments() {
 		$hook = md5(rand());
-		$action_id = wc_schedule_single_action( time(), $hook );
+		$action_id = as_schedule_single_action( time(), $hook );
 		$logger = ActionScheduler::logger();
 		do_action( 'action_scheduler_unexpected_shutdown', $action_id, array(
 			'type' => E_ERROR,
@@ -115,8 +115,8 @@ public function test_fatal_error_comments() {
 	}
 
 	public function test_canceled_action_comments() {
-		$action_id = wc_schedule_single_action( time(), 'a hook' );
-		wc_unschedule_action( 'a hook' );
+		$action_id = as_schedule_single_action( time(), 'a hook' );
+		as_unschedule_action( 'a hook' );
 		$logger = ActionScheduler::logger();
 		$logs = $logger->get_logs( $action_id );
 		$expected = new ActionScheduler_LogEntry( $action_id, 'action canceled' );
@@ -143,7 +143,7 @@ public function test_filtering_of_get_comments() {
 		$this->assertEquals( $comment_id, $comments[0]->comment_ID );
 
 
-		$action_id = wc_schedule_single_action( time(), 'a hook' );
+		$action_id = as_schedule_single_action( time(), 'a hook' );
 		$logger = ActionScheduler::logger();
 		$message = 'Logging that something happened';
 		$log_id = $logger->log( $action_id, $message );