<?php
/**
 * Background jobs.
 *
 * Thin wrapper around Action Scheduler (bundled via Composer) with a WP-Cron
 * fallback, so features can queue work without caring which runner is present.
 *
 * @package KarmaDocs
 */

namespace KarmaDocs;

defined( 'ABSPATH' ) || exit;

/**
 * Queue, schedule and cancel jobs.
 *
 * Jobs are plain WordPress actions: register the handler with add_action( $hook, ... )
 * and queue it here. Arguments must be JSON-serializable.
 */
class Jobs {

	/**
	 * Action Scheduler group for every Karma Docs job.
	 */
	const GROUP = 'karma-docs';

	/**
	 * Hooks.
	 */
	public function register() {
		add_filter( 'cron_schedules', array( $this, 'cron_schedules' ) ); // phpcs:ignore WordPress.WP.CronInterval -- Weekly is a standard interval.
	}

	/**
	 * Whether Action Scheduler is loaded and ready.
	 *
	 * @return bool
	 */
	public static function has_action_scheduler() {
		return function_exists( 'as_enqueue_async_action' ) && did_action( 'action_scheduler_init' );
	}

	/**
	 * Runs a job as soon as possible, in the background.
	 *
	 * @param string $hook   Action name.
	 * @param array  $args   Arguments.
	 * @param bool   $unique Skip if a job with this hook is already queued. Action Scheduler
	 *                       compares the hook only, not the arguments: pass false for
	 *                       per-item jobs (one per article, chained batches).
	 * @return void
	 */
	public static function async( $hook, array $args = array(), $unique = true ) {
		if ( self::has_action_scheduler() ) {
			as_enqueue_async_action( $hook, $args, self::GROUP, $unique );
			return;
		}
		if ( ! $unique || ! wp_next_scheduled( $hook, $args ) ) {
			wp_schedule_single_event( time(), $hook, $args );
		}
	}

	/**
	 * Runs a job once at a given time.
	 *
	 * @param int    $timestamp Unix time.
	 * @param string $hook      Action name.
	 * @param array  $args      Arguments.
	 * @return void
	 */
	public static function at( $timestamp, $hook, array $args = array() ) {
		if ( self::has_action_scheduler() ) {
			as_schedule_single_action( (int) $timestamp, $hook, $args, self::GROUP, true );
			return;
		}
		if ( ! wp_next_scheduled( $hook, $args ) ) {
			wp_schedule_single_event( (int) $timestamp, $hook, $args );
		}
	}

	/**
	 * Ensures a recurring job exists (idempotent: call it on every request).
	 *
	 * @param int    $interval Seconds between runs (DAY_IN_SECONDS, WEEK_IN_SECONDS…).
	 * @param string $hook     Action name.
	 * @param array  $args     Arguments.
	 * @param int    $first    First run (Unix time); defaults to now + interval.
	 * @return void
	 */
	public static function recurring( $interval, $hook, array $args = array(), $first = 0 ) {
		$first = $first ? (int) $first : time() + (int) $interval;
		if ( self::has_action_scheduler() ) {
			if ( false === as_next_scheduled_action( $hook, $args, self::GROUP ) ) {
				as_schedule_recurring_action( $first, (int) $interval, $hook, $args, self::GROUP, true );
			}
			return;
		}
		if ( ! wp_next_scheduled( $hook, $args ) ) {
			wp_schedule_event( $first, self::cron_recurrence( (int) $interval ), $hook, $args );
		}
	}

	/**
	 * Whether a job is queued.
	 *
	 * @param string $hook Action name.
	 * @param array  $args Arguments (null = any).
	 * @return bool
	 */
	public static function is_scheduled( $hook, $args = null ) {
		if ( self::has_action_scheduler() ) {
			return false !== as_next_scheduled_action( $hook, $args, self::GROUP );
		}
		return (bool) wp_next_scheduled( $hook, null === $args ? array() : $args );
	}

	/**
	 * Cancels every pending run of a job, in both runners.
	 *
	 * @param string $hook Action name.
	 * @return void
	 */
	public static function cancel( $hook ) {
		if ( function_exists( 'as_unschedule_all_actions' ) ) {
			as_unschedule_all_actions( $hook, array(), self::GROUP );
		}
		wp_clear_scheduled_hook( $hook );
	}

	/**
	 * Maps an interval to a WP-Cron recurrence name.
	 *
	 * @param int $interval Seconds.
	 * @return string
	 */
	private static function cron_recurrence( $interval ) {
		if ( $interval <= HOUR_IN_SECONDS ) {
			return 'hourly';
		}
		if ( $interval <= DAY_IN_SECONDS ) {
			return 'daily';
		}
		return 'kdocs_weekly';
	}

	/**
	 * Adds the weekly WP-Cron interval used by the fallback.
	 *
	 * @param array $schedules Schedules.
	 * @return array
	 */
	public function cron_schedules( $schedules ) {
		if ( ! isset( $schedules['kdocs_weekly'] ) ) {
			$schedules['kdocs_weekly'] = array(
				'interval' => WEEK_IN_SECONDS,
				'display'  => __( 'Once weekly', 'karma-docs' ),
			);
		}
		return $schedules;
	}
}