breadcrumb-the-shire/lib/Service/Scheduler/Handler/ScheduledJobHandlerInterface.php

<?php

namespace MintyPHP\Service\Scheduler\Handler;

interface ScheduledJobHandlerInterface
{
    /**
     * Returns the job definition (metadata + schedule defaults).
     *
     * The job_key is NOT included here – it is provided as the key in the
     * registry handler map in ScheduledJobRegistry.
     *
     * Required keys:
     *   label                        (string)       Human-readable name shown in admin UI.
     *   description                  (string)       Short description of what the job does.
     *   default_enabled              (int)          1 = enabled on first creation, 0 = disabled.
     *   default_timezone             (string)       IANA timezone name (e.g. 'Europe/Berlin').
     *   default_schedule_type        (string)       'hourly'|'daily'|'weekly'
     *   default_schedule_interval    (int)          1..24 hourly / 1..365 daily / 1..52 weekly
     *   default_schedule_time        (string|null)  'HH:MM', required for daily and weekly.
     *   default_schedule_weekdays_csv(string|null)  CSV of ISO weekday numbers 1..7, weekly only.
     *   default_catchup_once         (int)          1 = catch up once after downtime (default).
     *   allowed_schedule_types       (array)        Subset of ['hourly','daily','weekly'].
     */
    public function definition(): array;

    /**
     * Executes the job and returns a normalized result envelope.
     *
     * Implementations are responsible for:
     * - Calling the underlying service
     * - Mapping service results to the envelope format below
     * - Handling and wrapping service-level errors (e.g. lock_not_acquired → skipped)
     *
     * The result array content is job-specific and is JSON-encoded into the run log.
     * Keep values JSON-serializable (no objects, no resources).
     *
     * @param int|null $actorUserId  Null for scheduler-triggered runs; user ID for manual runs.
     * @return array{status:string, error_code:?string, error_message:?string, result:array}
     *   status:        'success'|'failed'|'skipped'
     *   error_code:    short machine-readable code, null on success
     *   error_message: human-readable detail, null on success (max 255 chars)
     *   result:        job-specific payload, empty array if nothing to report
     */
    public function execute(?int $actorUserId): array;
}