README

A small class for easily adding WP-Cron tasks (jobs).

This class allows you to create WordPress cron tasks quickly and simply. To avoid confusion, all task settings are specified in the first argument when creating the class instance. The class handles all the routine work required to properly register cron tasks and their intervals. The task handler (callback function) must already exist in PHP or be written separately.

Requirements

• PHP: >=7.4
• WordPress: >=5.7

Examples

By default, tasks are registered automatically (very fast) when you visit the admin panel, during a WP-CLI request, or during any cron request. If automatic registration is not needed, set the parameter 'auto_activate' => false and activate tasks manually using the activate() method. See the example below.

INFO: You can call Kama_Cron at an early stage of WordPress loading, starting from the muplugins_loaded hook.

IMPORTANT: The Kama_Cron code must also run during cron requests, because it registers the required WP hooks that are executed in those requests. In other words, you cannot register a cron job with this code and then remove this code.

Repeatable job

Use the known WP interval (hourly):

new \Kama\WP\Kama_Cron( [
	'wpkama_core_data_check_update' => [
		'callback'      => 'wpkama_core_data_check_update',
		'interval_name' => 'hourly',
	]
] );

/**
 * Cron callback (handler) function.
 */
function wpkama_core_data_check_update(){
	// your code to do the cron job
}

wpkama_core_data_check_update is the internal name of the WP hook. You do not need to use it anywhere else in your code. Just specify a unique and understandable name (it is a good idea to use the same name as the callback function).

Use the unknown WP interval (10 minutes):

new \Kama\WP\Kama_Cron( [
	'wpkama_cron_hook' => [
		'callback'      => 'wpkama_cron_func',
		'interval_name' => '10 minutes',
	],
] );

function wpkama_cron_func(){
	// your code to do the cron job
}

In this case, the class will parse the string 10 minutes and fill in the interval_sec and interval_desc parameters automatically.

In interval_name, you can specify a value in the following format: N (min|minutes|hour|day|month)s (for example: 10 minutes, 2 hours, 5 days, 2 months). The numeric value will be used for the interval_sec parameter. You can also specify an existing WP interval: hourly, twicedaily, daily.

Single job

Single job (once):

new \Kama\WP\Kama_Cron( [
    'single_job' => [
        'callback' => 'single_job_func',
        'start_time' => 1679205600, //= strtotime('tomorrow 6am') - (int) get_option('gmt_offset'),
    ],
] );

Single job at a specific time:

new \Kama\WP\Kama_Cron( [
    'single_job' => [
        'callback' => 'single_job_func',
        // start event every day at 6am by site time
        'start_time' => strtotime('tomorrow 6am') - (int) get_option('gmt_offset'),
    ],
] );

IMPORTANT: For single jobs, start_time must be a future timestamp. If it is in the past, the event will not be scheduled.

Pass arguments to callback

new \Kama\WP\Kama_Cron( [
	'my_hook' => [
		'callback'      => 'my_cron_callback',
		'interval_name' => 'hourly',
		'args'          => [ 123, 'abc' ],
	],
] );

function my_cron_callback( $post_id, $mode ){
	// do something
}

Access an instance by ID

$cron = \Kama\WP\Kama_Cron::get( 'my_cron_jobs' );
$cron->activate();

NOTE: If the ID is not found, Kama_Cron::get() returns an empty stub instance.

Register more than one task at once

Let's create 4 tasks with different intervals. Tasks are registered automatically (very fast) when you visit the admin panel, via CLI, or during a cron request.

Add the following code anywhere, for example in functions.php or in a plugin.

new \Kama\WP\Kama_Cron( [
	'id'     => 'my_cron_jobs',
	'events' => [
		// first task
		'wpkama_cron_func' => [
			'callback'      => [ MyCronCallbacks::class, 'wpkama_cron_func' ],
			'interval_name' => '10 min',
		],
		// 
		'wpkama_cron_func_2' => [
			'callback'      => [ MyCronCallbacks::class, 'wpkama_cron_func_2' ],
			'interval_name' => '2 hours',
			'start_time'    => 1679205600, // start at specified UNIX time
		],
		// second task
		'wpkama_cron_func_3' => [
			'callback'      => [ MyCronCallbacks::class, 'wpkama_cron_func_3' ],
			'interval_name' => '2 hours',
			'start_time'    => strtotime('tomorrow 6am'), // run at 6 a.m. (site time will be added to this time)
		],
		// 
		'wpkama_cron_func_4' => [
			'callback'      => [ MyCronCallbacks::class, 'wpkama_cron_func_4' ],
			'interval_name' => 'hourly', // this is already a known WP interval
		],
	],
] );

class MyCronCallbacks {

	public static function wpkama_cron_func(){
		$file = dirname( ABSPATH ) .'/__cron_check.txt';
		$content = current_time('mysql') ."\n";
		file_put_contents( $file, $content, FILE_APPEND );
	}
	
	public static function wpkama_cron_func_2(){
		// do something
	}
	
	public static function wpkama_cron_func_3(){
		// do something
	}
	
	public static function wpkama_cron_func_4(){
		// do something
	}
}

Register tasks when activating the plugin

The code below shows how to activate and deactivate tasks manually during plugin activation/deactivation.

IMPORTANT: in this case, the auto_activate parameter must be set to false: 'auto_activate' => false.

// Example of activation and deactivation when `auto_activate = false`
register_activation_hook( __FILE__, function(){
	\Kama\WP\Kama_Cron::get( 'my_cron_jobs_2' )->activate();
} );

register_deactivation_hook( __FILE__, function(){
	\Kama\WP\Kama_Cron::get( 'my_cron_jobs_2' )->deactivate();
} );

new \Kama\WP\Kama_Cron( [
	'id' => 'my_cron_jobs_2',
	'auto_activate' => false, // !IMPORTANT
	'events' => [
		'wpkama_cron_func_4' => [
			'callback'      => 'wpkama_cron_func_4',
			'interval_name' => 'twicedaily',
		],
		'wpkama_cron_func_5' => [
			'callback'      => 'wpkama_cron_func_5',
			'interval_name' => '2 hours',
		],
	],
] );

function wpkama_cron_func_4(){
	// code here
}

function wpkama_cron_func_5(){
	// code here
}

INFO: The deactivate() method will deactivate all jobs from the current pack (in the example above, there are two jobs).

--

Plugin page: https://wp-kama.com/1353/kama_cron