MMOframework
Why AI Playground Libraries Documentation Search Agency
FR EN
Index

JobController

MMO\core\jobs · 1 symbol · generated 27 Oct 2026

class

JobController

JobController.php:44

The HTTP side of long jobs (JobStore): start one, follow it live, stop it.

class MMO\core\jobs\JobController extends MMO\core\classes\aController
Namespace
MMO\core\jobs
Extends
aController
Only the jobs the application declares can be started or seen ([`$jobs`](https://mmoframework.fr/en/documentation/mmo.core/php/jobs/JobController.md#jobcontroller-jobs)), each by name, with the rights it needs: the class is never taken from the request. A job declared `start: false` is started by the application's own code only (a route checking who may, as mmo.admin's board sync does): the api only follows it and stops it. ```php \MMO\config([ \MMO\core\Application::class => ['routes' => [\MMO\core\jobs\JobController::class => []]], \MMO\core\jobs\JobController::class => [ 'scope' => 'sudo', 'jobs' => [ 'demo' => \MMO\core\jobs\DemoJob::class, 'atonline' => ['class' => \Oviepro\atonline\ImportJob::class, 'scope' => 'god'], ], ], ]); ``` - `GET api/jobs.json?job=demo&limit=20`: the declared jobs, newest first; - `POST api/jobs.json {job, params}`: start one, answers its record (`state: queued`); - `GET api/jobs/{id}.json`: its record ([`JobStore::get`](https://mmoframework.fr/en/documentation/mmo.core/php/jobs/JobStore.md#jobstore-get)); - `GET api/jobs/{id}/events.json?offset=0`: its events since an offset, `{events, offset, job}` (polling); - `GET api/jobs/{id}/events.sse`: its events live, as Server-Sent Events ([`JobEventStream`](https://mmoframework.fr/en/documentation/mmo.core/php/jobs/JobEventStream.md#jobeventstream)): `?offset=` or the `Last-Event-ID` header to resume; - `POST api/jobs/{id}/stop.json`: ask it to stop; `POST api/jobs/{id}/kill.json`: kill its process. > WARNING: without mmo.oauth, a [`$scope`](https://mmoframework.fr/en/documentation/mmo.core/php/jobs/JobController.md#jobcontroller-scope) refuses everyone; with no scope, every route answers whoever calls: > only on a development machine.
curl -X POST -H 'Content-Type: application/json' -d '{"job": "demo", "params": {"steps": 5}}' http://localhost/app/api/jobs.json curl -N http://localhost/app/api/jobs/20261019-142501-a1b2c3d4/events.sse

Properties2

jobs

array $jobs = []
Type
array

Methods16

answer($record, $name)

JobController.php:235
protected function answer(array $record, string $name): array
$recordarray
$namestring
returnsarraya record as the routes answer it: with its declared name, without the process's details

find($route)

JobController.php:180

The job of the route's {id}, when it is a declared one the user may see.

protected function find(MMO\core\server\Route $route): array
$routeRoute
returnsarrayarray, 1: string} its record and its name
throws404 otherwise (a job the user may not see does not exist for them)

guardJob($route, $name)

JobController.php:197
protected function guardJob(MMO\core\server\Route $route, string $name): array
$routeRoute
$namestring
returnsarrayclass-string<aJob>, scope: ?string} the declared job $name, when the user may start it
throws404 when it is not declared, 403 when the user may not, 500 when it is not a job

isAllowed($scope)

JobController.php:216
protected function isAllowed(?string $scope): bool
$scopenull | stringa|b: any of them; null: anyone
returnsboolwhether the user holds $scope (mmo.oauth); without mmo.oauth, only a null scope is

routeEvents($route)

JobController.php:119
#[MMO\core\attributes\APIRoute('GET|api/jobs/{id}/events.json', 'A long job\'s events since ?offset=', mediaTypes: ['json'])] function routeEvents(MMO\core\server\Route $route): array
$routeRoute
returnsarrayarray<array>, offset: int, job: array}

routeGet($route)

JobController.php:109
#[MMO\core\attributes\APIRoute('GET|api/jobs/{id}.json', 'A long job: its state, progress, result or error', mediaTypes: ['json'])] function routeGet(MMO\core\server\Route $route): array
$routeRoute
returnsarraythe job's record

routeKill($route)

JobController.php:154
#[MMO\core\attributes\APIRoute('POST|api/jobs/{id}/kill.json', 'Kill a long job\'s process', mediaTypes: ['json'])] function routeKill(MMO\core\server\Route $route): array
$routeRoute
returnsarraythe job's record

routeList($route)

JobController.php:66
#[MMO\core\attributes\APIRoute('GET|api/jobs.json', 'The long jobs, newest first: ?job={name}&limit=20', mediaTypes: ['json'])] function routeList(MMO\core\server\Route $route): array
$routeRoute
returnsarraythe records of the declared jobs the user may see, newest first

routeStart($route)

JobController.php:93
#[MMO\core\attributes\APIRoute('POST|api/jobs.json', 'Start a long job: {job, params}', body: ['job' => 'string', 'params' => '?object'], mediaTypes: ['json'])] function routeStart(MMO\core\server\Route $route): array
$routeRoute
returnsarraythe new job's record

routeStop($route)

JobController.php:144
#[MMO\core\attributes\APIRoute('POST|api/jobs/{id}/stop.json', 'Ask a long job to stop', mediaTypes: ['json'])] function routeStop(MMO\core\server\Route $route): array
$routeRoute
returnsarraythe job's record

routeStream($route)

JobController.php:130
#[MMO\core\attributes\APIRoute('GET|api/jobs/{id}/events.sse', 'A long job\'s events, live (Server-Sent Events): ?offset= or Last-Event-ID', mediaTypes: ['sse'])] function routeStream(MMO\core\server\Route $route): MMO\core\server\StreamResponse
$routeRoute
returnsStreamResponsethe job's events, live (JobEventStream)
Inherited members (55)
ConstantsDeclared byDescription
ALERTiLogLevelAlert: Action must be taken immediately.
ALLiLogLevelMask for all
ALL_PLUSiLogLeveldebug everything
BACKTRACEiLogLevel
CRITICALiLogLevelCritical: Critical conditions.
DEBUGiLogLevelDebug: Detailed debug information.
DEEPiLogLeveldebug everything with arguments
EMERGENCYiLogLevelEmergency: System is unusable.
ERRORiLogLevelError: Runtime errors that do not require immediate action but should typically be logged and monitored.
ERROR_PLUSiLogLevelMask for all error
FATALiLogLevelMask for all fatal error
INFOiLogLevelInfo: Interesting events.
INFO_PLUSiLogLevelMask for all errors/warning/notices/info
MEMORYiLogLevelinclude backtrace object
NOTICEiLogLevelNotice: Normal but significant events.
NOTICE_PLUSiLogLevelMask for all errors/warning/notices/info
TRACEiLogLevelinclude backtrace as origins
WARNINGiLogLevelWarning: Exceptional occurrences that are not errors.
WARNING_PLUSiLogLevelMask for all errors and warnings
PropertiesDeclared byDescription
verbosityaModule
MethodsDeclared byDescription
alert($message, $context)aModuleAction must be taken immediately.
backtraces($message, $context)aModuleForce-log a message at INFO level together with a full stack trace/memory snapshot (iLogLevel::BACKTRACE), bypassing the verbosity mask entirely (any non-zero verbosity is enough to trigger it).
Configure($config)aModuleMerge $config into this module's configuration in the shared Configuration.
critical($message, $context)aModuleCritical conditions. No-op if CRITICAL is currently filtered out by the verbosity mask.
debug($message, $context)aModuleDetailed debug information.
debugName()aModuleHuman-readable identifier used as the default {origin} in this instance's log messages.
DefaultConfig()aModuleThe config a module starts from before anything loaded via Configuration is merged in.
emergency($message, $context)aModuleSystem is unusable. No-op if EMERGENCY is currently filtered out by the verbosity mask.
error($message, $context)aModuleRuntime errors that do not require immediate action but should typically be logged and monitored.
ExtractRoutes($config)aControllerExtract all the APIRoute from this class, regardless of the fact they are registered in the application
getVerbosity()aModule
HasRoutes()aControllerTells if any APIRoute are registered in the application
info($message, $context)aModuleInteresting events. No-op if INFO is currently filtered out by the verbosity mask.
Instantiate($config)aModule(Re)create the shared instance immediately, configured with $config merged into the class's existing config.
IsShared()aModule
Link($method, $data)aControllerBuild a Link (URL + label/icon/description/title, taken from the route's APIRoute metadata) for a registered route.
log($level, $message, $context)aModuleLogs with an arbitrary level.
notice($message, $context)aModuleNormal but significant events.
offsetExists($key)aModule\ArrayAccess::offsetExists -- tells whether $key is a declared property at all, regardless of whether it is currently readable/writable through array access.
offsetGet($key)aModule\ArrayAccess::offsetGet -- reads a property directly, unless it has a #[Serialize(serialize: 'methodName')] attribute, in which case that zero-argument method is called instead (e.g.
offsetSet($key, $value)aModule\ArrayAccess::offsetSet -- sets a property directly, unless it has a #[Serialize(unserialize: 'methodName')] attribute, in which case that method is called with $value instead (e.g.
offsetUnset($key)aModule\ArrayAccess::offsetUnset -- equivalent to $module[$key] = null.
Route($method)aControllerGet a registered APIRoute WARNING: if this class was not registered in the application, it will return null.
Routes()aControllerGet a list of registered APIRoutes (from this class) in the application WARNING: if this class was not registered in the application, it will return an empty array.
serialize($path, $serializer)aModule\MMO\core\interfaces\iSerializable::serialize -- exports every property (via
setVerbosity($verb)aModuleSet the current verbosity mask, replacing whatever it was before.
Shared()aModuleGet the shared instance, creating (and configuring) it on first call.
testVerbosity($level)aModuleTest whether a given level (or set of levels) is currently enabled by this instance's verbosity mask.
traitUnshare($serialize)aModuleRemove the shared instance, so the next Shared() call creates a fresh one.
unserialize($data, $path, $instances)aModule\MMO\core\interfaces\iSerializable::unserialize -- merges $data onto DefaultConfig, runs it through the (possibly overridden) constructor, then applies each resulting value to its property (via
Unshare($serialize)aModuleLike tSingleton::Unshare, but also disconnects this module's instance from every event it was listening to (via Event::DisconnectListeners) before dropping it.
Url($method, $data)aControllerBuild the URL for a registered route, filling in any {placeholder} from $data.
warning($message, $context)aModuleExceptional occurrences that are not errors.
__construct($config)aModuleprotected constructor, so it is not possible to do new Module(...) called by the serialization process just before being injected with data.
__wakeup()aControllerCalled automatically right after the controller's shared instance is built (aModule::unserialize): registers onRoute as a Route listener with a low priority (-10), so it…