From e5a91d27e1385fc816ae722bcad5945a88c412dc Mon Sep 17 00:00:00 2001 From: COQUARD Cyrille Date: Sat, 23 Nov 2024 13:44:31 +0100 Subject: [PATCH 1/5] Added first version from the script --- .../12-Cron/02-Scheduling-WP-Cron-events.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md diff --git a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md new file mode 100644 index 0000000..49253cf --- /dev/null +++ b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md @@ -0,0 +1,70 @@ +# Scheduling WP Cron events + +To schedule a Cron event we will need two things: + +- An job to execute. +- An periodicity for our job. + +## Creating a job to execute + +In WordPress, any action can be a Cron event to schedule that makes it quite easy to write the logic to be run into a WP Cron as it will be a familiar syntax: + +```php +function my_plugin_my_action() { + // my logic +} + +add_action('my_plugin_my_event', 'my_plugin_my_action'); +``` + +However, there is a big thing to not about actions being executed within a Cron job, they run as a front-end request and not an administrator one. + +## Scheduling an event + +Once we get your action with the logic the next step is to schedule it. + +For that, we got a couple of intervals already implemented into WordPress we can use: +- `hourly`: To run the event each hour. +- `twicedaily`: To run the event each 12 hours. +- `daily`: To run the event each 24 hours. +- `weekly`: To run the event each 7 days. + +Then, to actually schedule the event, we need to use the function [`wp_schedule_event`](https://developer.wordpress.org/reference/functions/wp_schedule_event/) within at the WordPress initialization: + +```php +function my_plugin_schedule_my_event() { + wp_schedule_event(time(), 'my_plugin_my_event', 'hourly'); +} + +add_action('init', 'my_plugin_schedule_my_event'); +``` + +That method takes three parameters: +- The timestamp from the next run from that event, we often set it up to the current date. +- The hook that should be executed. +- The recurrence from that event. + +## Preventing an event from scheduling twice + +Even if the action we scheduled previously is executed, there will be an issue with it, WordPress doesn't check if an event is already scheduled before scheduling it. + +Due to that, the event will be scheduled again, and again each time WordPress is loading and that is why we need to use the function [`wp_next_scheduled`](https://developer.wordpress.org/reference/functions/wp_next_scheduled/) to prevent this from happening. + +The [`wp_next_scheduled`](https://developer.wordpress.org/reference/functions/wp_next_scheduled/) provides the timestamp from when is the next occurrence from an event or `false` if it does not have. + +We will use that function to bail out when we already have an event scheduled the following way: + +```php +function my_plugin_schedule_my_event() { + + if( wp_next_scheduled('my_plugin_my_event') ) { + return; + } + + wp_schedule_event(time(), 'my_plugin_my_event', 'hourly'); +} + +add_action('init', 'my_plugin_schedule_my_event'); +``` + +Now we are sure that the event will be scheduled only once. From c20702fe59c8c9780a696f94fe123f3f868206d4 Mon Sep 17 00:00:00 2001 From: Jonathan Bossenger Date: Wed, 4 Dec 2024 16:55:21 +0200 Subject: [PATCH 2/5] First round of review changes --- .../12-Cron/02-Scheduling-WP-Cron-events.md | 53 ++++++++++++++++--- 1 file changed, 45 insertions(+), 8 deletions(-) diff --git a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md index 49253cf..fb41b27 100644 --- a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md +++ b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md @@ -1,20 +1,57 @@ # Scheduling WP Cron events -To schedule a Cron event we will need two things: +In order to make use of the built in WP-Cron functionality, you need to know how to schedule WP-Cron events. -- An job to execute. -- An periodicity for our job. +Let's take a look how this is done. -## Creating a job to execute +## Example plugin -In WordPress, any action can be a Cron event to schedule that makes it quite easy to write the logic to be run into a WP Cron as it will be a familiar syntax: +To start, create a new plugin in your local WordPress install, with the following plugin header: ```php -function my_plugin_my_action() { - // my logic + Date: Wed, 4 Dec 2024 21:05:58 +0200 Subject: [PATCH 3/5] Update 02-Scheduling-WP-Cron-events.md Continued edits --- .../12-Cron/02-Scheduling-WP-Cron-events.md | 50 +++++++++++-------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md index fb41b27..267925e 100644 --- a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md +++ b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md @@ -1,6 +1,6 @@ # Scheduling WP Cron events -In order to make use of the built in WP-Cron functionality, you need to know how to schedule WP-Cron events. +In order to make use of the built-in WP-Cron functionality, you need to know how to schedule and unschedule WP-Cron events. Let's take a look how this is done. @@ -22,13 +22,15 @@ To start, create a new plugin in your local WordPress install, with the followin To schedule a WP Cron event you will need a few things: -- You need to create an action hooked into a callback function. -- Inside the callback function you define the logic to be executed for the event +- You need to create a function that defines the logic for your event to be executed +- The function should be hooked into an action hook that will be triggered by the WP-Cron event - Finally, you schedule the task by passing your action and the interval at which the event should run. -## Creating the action to execute +## Creating the action and callback to execute -In WordPress, any action can be scheduled as a WP-Cron event. To set up an action to be schduled you use the same `add_action` function you would use to hook into any existing action. +In WordPress, any action hook can be scheduled as a WP-Cron event. + +To set up an action hook to be scheduled you use the same `add_action` function you would use to hook into any existing action. ```php add_action('wp_learn_trigger_event', 'wp_learn_trigger_event_callback'); @@ -38,6 +40,8 @@ function wp_learn_trigger_event_callback() { } ``` +This action is not an existing WordPress action, but one that you will create for the purposes of scheduling a WP-Cron event. + For the purposes of this event, just add a simple log message to the callback function: ```php @@ -54,32 +58,36 @@ define( 'WP_DEBUG_DISPLAY', false ); define( 'WP_DEBUG_LOG', true ); ``` -However, there is a big thing to not about actions being executed within a Cron job, they run as a front-end request and not an administrator one. - ## Scheduling an event -Once we get your action with the logic the next step is to schedule it. +Once you have your action and callback function with the logic to be executed for the event, the next step is to schedule it at a specific interval. -For that, we got a couple of intervals already implemented into WordPress we can use: -- `hourly`: To run the event each hour. -- `twicedaily`: To run the event each 12 hours. -- `daily`: To run the event each 24 hours. -- `weekly`: To run the event each 7 days. +WordPress ships with a few predefined intervals you can use: +- `hourly`: runs the event each hour. +- `twicedaily`: runs the event every 12 hours. +- `daily`: runs the event every 24 hours. +- `weekly`: runs the event every 7 days. -Then, to actually schedule the event, we need to use the function [`wp_schedule_event`](https://developer.wordpress.org/reference/functions/wp_schedule_event/) within at the WordPress initialization: +To schedule the event, you use the [`wp_schedule_event`](https://developer.wordpress.org/reference/functions/wp_schedule_event/) function. It's recommended to use this function during WordPress initialization, by hooking into the `init` action. ```php +add_action('init', 'my_plugin_schedule_my_event'); + function my_plugin_schedule_my_event() { - wp_schedule_event(time(), 'my_plugin_my_event', 'hourly'); + wp_schedule_event( time(), 'wp_learn_trigger_event', 'hourly' ); } - -add_action('init', 'my_plugin_schedule_my_event'); ``` -That method takes three parameters: -- The timestamp from the next run from that event, we often set it up to the current date. -- The hook that should be executed. -- The recurrence from that event. +That function takes three parameters: +- The Unix timestamp from when next to run the event, ie the start time. You can use the PHP `time()` [function](https://www.php.net/manual/en/function.time.php) to get the current time. +- The action hook you created that should be executed. +- The internal at which the event should run after the initial start time, as set by the first parameter. + +## Testing the event + +There are a number of ways to check and test your WP Cron events, which you will learn about in a different lesson. However, because you've created this event to run hourly, you can check that it's working by simply loading the front end of your site. + +However, there is a big thing to not about actions being executed within a Cron job, they run as a front-end request and not an administrator one. ## Preventing an event from scheduling twice From bd52b458ae8ebc5d7b9c3c09e42b2f6f07c943b0 Mon Sep 17 00:00:00 2001 From: Jonathan Bossenger Date: Thu, 5 Dec 2024 12:54:49 +0200 Subject: [PATCH 4/5] Review/testing updates --- .../12-Cron/02-Scheduling-WP-Cron-events.md | 28 +++++++++++-------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md index 267925e..a9f7230 100644 --- a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md +++ b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md @@ -28,9 +28,9 @@ To schedule a WP Cron event you will need a few things: ## Creating the action and callback to execute -In WordPress, any action hook can be scheduled as a WP-Cron event. +In order to trigger a scheduled event, WP-Cron performs a similar function to the WordPress `do_action` function, but it's specifically for WP-Cron events. -To set up an action hook to be scheduled you use the same `add_action` function you would use to hook into any existing action. +So to start, you set up an action hook callback to be scheduled by using the same `add_action` function you would use to hook into any existing action. ```php add_action('wp_learn_trigger_event', 'wp_learn_trigger_event_callback'); @@ -40,9 +40,9 @@ function wp_learn_trigger_event_callback() { } ``` -This action is not an existing WordPress action, but one that you will create for the purposes of scheduling a WP-Cron event. +This action is not an existing WordPress action, but one that you will create in the next step for the purposes of scheduling a WP-Cron event. -For the purposes of this event, just add a simple log message to the callback function: +Inside the callback function hooked into this action, you add your event logic. For now, just add a simple log message to the callback function: ```php function wp_learn_trigger_event_callback() { @@ -60,7 +60,7 @@ define( 'WP_DEBUG_LOG', true ); ## Scheduling an event -Once you have your action and callback function with the logic to be executed for the event, the next step is to schedule it at a specific interval. +Once you have hooked the callback function with the logic to be executed for the event into the action hook, the next step is to schedule it at a specific interval. WordPress ships with a few predefined intervals you can use: - `hourly`: runs the event each hour. @@ -68,26 +68,30 @@ WordPress ships with a few predefined intervals you can use: - `daily`: runs the event every 24 hours. - `weekly`: runs the event every 7 days. -To schedule the event, you use the [`wp_schedule_event`](https://developer.wordpress.org/reference/functions/wp_schedule_event/) function. It's recommended to use this function during WordPress initialization, by hooking into the `init` action. +To schedule the event, you use the [`wp_schedule_event`](https://developer.wordpress.org/reference/functions/wp_schedule_event/) function. + +It's recommended to use this function during plugin activation, by using the register_activation_hook() function. ```php -add_action('init', 'my_plugin_schedule_my_event'); +register_activation_hook( __FILE__, 'wp_learn_schedule_event' ); -function my_plugin_schedule_my_event() { - wp_schedule_event( time(), 'wp_learn_trigger_event', 'hourly' ); +function wp_learn_schedule_event() { + wp_schedule_event( time(), 'hourly', 'wp_learn_trigger_event' ); } ``` That function takes three parameters: - The Unix timestamp from when next to run the event, ie the start time. You can use the PHP `time()` [function](https://www.php.net/manual/en/function.time.php) to get the current time. -- The action hook you created that should be executed. - The internal at which the event should run after the initial start time, as set by the first parameter. +- The action hook you created that should be executed. ## Testing the event -There are a number of ways to check and test your WP Cron events, which you will learn about in a different lesson. However, because you've created this event to run hourly, you can check that it's working by simply loading the front end of your site. +There are a number of ways to check and test your WP Cron events, which you will learn about in a different lesson. + +However, because you've created this event to run hourly, you can check that it's working by activating the plugin, and then loading the front end of your site after about an hour. -However, there is a big thing to not about actions being executed within a Cron job, they run as a front-end request and not an administrator one. +This is an important thing to note about WP-Cron events, they are only triggered by requests to the front-end of your site, and not the administration dashboard. ## Preventing an event from scheduling twice From 130561e97bafcd994dd3305aa1d1efc4af52998b Mon Sep 17 00:00:00 2001 From: Jonathan Bossenger Date: Thu, 5 Dec 2024 17:00:12 +0200 Subject: [PATCH 5/5] Final review --- .../12-Cron/02-Scheduling-WP-Cron-events.md | 97 ++++++++++++++----- 1 file changed, 74 insertions(+), 23 deletions(-) diff --git a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md index a9f7230..ae6f521 100644 --- a/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md +++ b/plugin-developer-learning-pathway/12-Cron/02-Scheduling-WP-Cron-events.md @@ -33,20 +33,20 @@ In order to trigger a scheduled event, WP-Cron performs a similar function to th So to start, you set up an action hook callback to be scheduled by using the same `add_action` function you would use to hook into any existing action. ```php -add_action('wp_learn_trigger_event', 'wp_learn_trigger_event_callback'); +add_action( 'wp_learn_trigger_event', 'wp_learn_trigger_event' ); -function wp_learn_trigger_event_callback() { +function wp_learn_trigger_event() { // event logic here } ``` This action is not an existing WordPress action, but one that you will create in the next step for the purposes of scheduling a WP-Cron event. -Inside the callback function hooked into this action, you add your event logic. For now, just add a simple log message to the callback function: +Inside the callback function hooked into this action, you add your event logic. For now, just add a simple log message with a date/time to the callback function: ```php -function wp_learn_trigger_event_callback() { - error_log('WP Learn Scheduled Event Triggered'); +function wp_learn_trigger_event() { + error_log( 'WP Learn Scheduled Event Triggered at ' . gmdate( 'Y-m-d H:i:s' ) ); } ``` @@ -70,50 +70,101 @@ WordPress ships with a few predefined intervals you can use: To schedule the event, you use the [`wp_schedule_event`](https://developer.wordpress.org/reference/functions/wp_schedule_event/) function. -It's recommended to use this function during plugin activation, by using the register_activation_hook() function. +For the purposes of this example, trigger this function during plugin activation, by using the `register_activation_hook()` function with a callback function. ```php register_activation_hook( __FILE__, 'wp_learn_schedule_event' ); function wp_learn_schedule_event() { - wp_schedule_event( time(), 'hourly', 'wp_learn_trigger_event' ); + wp_schedule_event( time(), 'hourly', 'wp_learn_trigger_event' ); } ``` -That function takes three parameters: +That wp_schedule_event() function takes three parameters: - The Unix timestamp from when next to run the event, ie the start time. You can use the PHP `time()` [function](https://www.php.net/manual/en/function.time.php) to get the current time. -- The internal at which the event should run after the initial start time, as set by the first parameter. -- The action hook you created that should be executed. +- The interval at which the event should run after the initial start time, as set by the first parameter. +- The action hook to run at the start time and subsequent intervals. ## Testing the event There are a number of ways to check and test your WP Cron events, which you will learn about in a different lesson. -However, because you've created this event to run hourly, you can check that it's working by activating the plugin, and then loading the front end of your site after about an hour. +However, because you've created this event to start at the current time, you can check that it's working by activating the plugin, and then loading the front end of your site after about an hour. + +Once you've done that, you should see the log message in your error log file, indicating that first run of the event has been triggered. + +```log +[01-Jan-2021 00:00:00 UTC] WP Learn Scheduled Event Triggered at 2021-01-01 00:00:00 +``` This is an important thing to note about WP-Cron events, they are only triggered by requests to the front-end of your site, and not the administration dashboard. -## Preventing an event from scheduling twice +Another way you could quickly test this is to use a quick snippet of code, to trigger the action hook manually: + +```php +add_action( 'init', 'wp_learn_event_test' ); +function wp_learn_event_test() { + do_action( 'wp_learn_trigger_event' ); +} +``` -Even if the action we scheduled previously is executed, there will be an issue with it, WordPress doesn't check if an event is already scheduled before scheduling it. +## Preventing an event from scheduling twice -Due to that, the event will be scheduled again, and again each time WordPress is loading and that is why we need to use the function [`wp_next_scheduled`](https://developer.wordpress.org/reference/functions/wp_next_scheduled/) to prevent this from happening. +The code you created earlier used the `register_activation_hook` to schedule the event. -The [`wp_next_scheduled`](https://developer.wordpress.org/reference/functions/wp_next_scheduled/) provides the timestamp from when is the next occurrence from an event or `false` if it does not have. +This is fine if you are adding a scheduled event from the first version of the plugin. However, if you need to add a new scheduled event to an existing plugin, you can't hook into the activation hook, because that only runs code on plugin activation, and not if the plugin is updated. -We will use that function to bail out when we already have an event scheduled the following way: +In this case you'd generally hook into something like the `init` action hook to add new scheduled events. ```php -function my_plugin_schedule_my_event() { +add_action( 'init', 'wp_learn_schedule_event' ); + +function wp_learn_schedule_event() { + wp_schedule_event( time(), 'hourly', 'wp_learn_trigger_event' ); +} +``` + +When scheduling a new event using wp_schedule_event(), WordPress doesn't perform any checks to see if the event is already scheduled. - if( wp_next_scheduled('my_plugin_my_event') ) { - return; - } +This means that every time the `init` hook is triggered, §wp_learn_trigger_event` will be scheduled as a new event. - wp_schedule_event(time(), 'my_plugin_my_event', 'hourly'); +To prevent this, you can use the [`wp_next_scheduled`](https://developer.wordpress.org/reference/functions/wp_next_scheduled/) function to check if an already existing event with the same action as been scheduled. + +The [`wp_next_scheduled`](https://developer.wordpress.org/reference/functions/wp_next_scheduled/) returns the timestamp for the next occurrence of the given event or `false` if it's not scheduled. + +```php +add_action( 'init', 'wp_learn_schedule_event' ); + +function wp_learn_schedule_event() { + if ( wp_next_scheduled( 'wp_learn_trigger_event' ) ) { + return; + } + wp_schedule_event( time(), 'hourly', 'wp_learn_trigger_event' ); } +``` + +By checking and returning early if the event is already scheduled, you can be sure the event will only be scheduled once. + +## Unscheduling an event -add_action('init', 'my_plugin_schedule_my_event'); +To unschedule an event, you use the [`wp_unschedule_event`](https://developer.wordpress.org/reference/functions/wp_unschedule_event/) function. + +This function has two parameters: + +- The Unix timestamp from when the event was last scheduled to run. +- The action hook to unschedule. + +To unschedule the event, you can use the `register_deactivation_hook` function to trigger the unscheduling when the plugin is deactivated. + +```php +register_deactivation_hook( __FILE__, 'wp_learn_unschedule_event' ); + +function wp_learn_unschedule_event() { + $timestamp = wp_next_scheduled( 'wp_learn_trigger_event' ); + wp_unschedule_event( $timestamp, 'wp_learn_trigger_event' ); +} ``` -Now we are sure that the event will be scheduled only once. +## Further reading + +To read more about scheduling and unscheduling WP-Cron events, check out the [Scheduling WP Cron Events](https://developer.wordpress.org/plugins/cron/scheduling-wp-cron-events/) page in the Cron section of the WordPress Plugin Developer handbook. \ No newline at end of file