CRON Events Service

The CRON Events Service is again a multi-handler service that exhibits a run action method. A CRON event is an event that should happen at a particular point in time -- like literally when the real clocks of the world reach a certain point. This service is designed to work with such events and it provides the following public methods:

• schedule_single_event

• unschedule_single_event

• schedule_recurring_event

• unschedule_recurring_event

The method names should be pretty self-explanatory. A single event is one that should happen exactly once at a given point in time while a recurring event is one that should happen with some regularity, like every hour or every day. If you're unfamiliar with the concept, we recommend reading the WordPress Developer documentation on this topic.

Setting up a CRON event requires you to make a few conscious decisions, but we've tried to simplify the process by providing some helpful defaults. For example, for both types of events you need to provide a UNIX timestamp as to when the first (and maybe only) event should take place. If you simply omit this value, the service will default to next midnight based on the website's timezone.

Similarly, for recurring events you need to provide a recurrence value. WordPress provides some default values like daily, twicedaily, or weekly, but that might not cover your specific use-case. To help with this, you can simply make use of our CronIntervalsEnum enum. This will provide you with more recurrence values which, when used together with our service, will automagically handle everything in the background for WordPress to understand what you mean.

Obviously, being a handler service, the service expects to have at least one handler registered. It accepts handlers implementing the CronEventsHandlerInterface interface. There are two handlers that the module comes pre-packaged with, and one of them gets registered by default (so if you omit to provide any handler whatsoever, there will be a default one set up automagically).

As you might expect, the default handler used the WordPress API. You can check out how it works here and you can read more about scheduling events with WordPress CRON API here.

How to use the service

Just like with all the services so far, the recommended method is using the setup action trait, SetupCronEventsTrait. You don't have to though and you're free to use any of the other traits and interfaces provided in the CRON Events namespace here.