47 lines
2.3 KiB
PHP
47 lines
2.3 KiB
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;
|
||
}
|