Shutdown
A centralized, priority-aware lifecycle for completing work before an APPNETOS runtime terminates.
APPNETOS lets core services and application components register finalization methods. Use the #[Shutdown]
annotation for declarative registration, or register an object method explicitly through Core\Shutdown.
The shared shutdown controller executes the queue once, in descending priority order, and isolates
failures between tasks.
Register shutdown methods
Declarative registration with an annotation
APPNETOS supports the #[Shutdown] method annotation. Annotated methods are intended to
participate in the runtime shutdown process. Annotation discovery and its optional parameters are
implemented outside the three classes shown here; consult the annotation definition for its exact
signature.
use Core\Annotation\Shutdown;
class RuntimeStatistics
{
#[Shutdown]
public function persist(): void
{
// Persist collected runtime statistics.
}
}
The annotation example illustrates the registration convention; the discovery mechanism must register the method before shutdown.
Explicit registration
Register an existing object and a method name with add(object $object, string $method, int
$priority =
0). The method must exist; otherwise ShutdownException::methodNotFound() is
raised.
use Core\Registry;
use Core\Shutdown;
$shutdown = Registry::get(Shutdown::class);
$shutdown->add($statistics, 'persist', 100);
$shutdown->add($cache, 'flush', 50);
$shutdown->add($connection, 'close', 0);
Registering the same method on the same object instance again updates its priority rather than adding a duplicate. The same method on a different object instance is a distinct task.
Execution order and guarantees
| Behavior | Implementation |
|---|---|
| Order | Higher integer priorities run first; default priority is 0. |
| One-time execution | execute() sets the executed flag before running tasks. Later calls return
immediately.
|
| Native PHP integration | init() registers execute() once using register_shutdown_function().
|
| Task errors | Each task is wrapped in try/catch (Throwable); failures go to native PHP error_log(),
and the next task continues.
|
| Parameters | Registered task methods are called without arguments. |
| Duplicate tasks | Same object identity plus method name updates priority. |
Tasks with equal priorities have no documented business ordering guarantee. Use distinct priorities if ordering matters. Tasks registered after execution has started will not be processed by that already-started pass.
Controlled runtime termination
From the shutdown controller
Registry::get(Shutdown::class)->exit(0);
Core\Shutdown::exit(int $code = 0): never executes pending tasks and then terminates PHP
with
the supplied exit code. The native shutdown callback may subsequently run, but the executed flag
prevents
duplicate task execution.
From a controller extending Core\Base
class ExampleController extends \Core\Base
{
public function finish(): void
{
// Application work completed.
$this->exit();
}
}
The protected Core\Base::exit() shortcut resolves the shared shutdown service, invokes its
execute() method, and then calls PHP exit. It does not send a
pending response first. The supplied implementation passes true to execute()
although that method declares no parameters; the extra value is not used by its implementation.
From the response controller
use Core\Response;
$response = Registry::get(Response::class);
$response->json(['status' => 'completed']);
$response->exit();
Core\Response::exit(int $code = 0): never first calls send(), then delegates to
Core\Shutdown::exit(). This is the appropriate path when the current HTTP response must be
transmitted before termination. send() is idempotent and integrates response metadata and
debug
data before emitting the body.
Practical use cases
Persist state
Save runtime statistics, session-related changes, or buffered data at the end of processing.
Flush caches
Write deferred cache changes before external connections are released.
Close resources
Finalize application-managed external resources in a predictable order.
Finalize runtime
Run cleanup or final accounting for requests, commands, and worker executions.
Public API Reference
Core\Shutdown
Class & Registry
Class:
Core\Shutdown
Extends:
Core\Shutdown\Base
use Core\Shutdown;
use Core\Registry;
$shutdown = Registry::get(Shutdown::class);
| Method | Description |
|---|---|
init(): void |
Register the native PHP shutdown callback once. |
add(object $object, string $method, int $priority = 0): void |
Add or reprioritize a task. |
execute(): void |
Run the registered tasks once. |
exit(int $code = 0): never |
Execute tasks and terminate the runtime. |
getTasks(): array |
Inspect the registered task list. |
getExecuted(): bool |
Check whether execution has already started. |
Recommendations and limitations
- Keep shutdown tasks short and deterministic; slow tasks delay process termination.
- Use explicit priorities for dependencies such as “flush before close”.
- Avoid requiring response output inside shutdown tasks: the HTTP response may already have been sent.
- Log task failures with enough context for investigation. The shutdown controller itself uses PHP's native error log.
- Native PHP shutdown hooks are not a guarantee against every form of process termination, such as abrupt process kills.
- Use
Response::exit()when you need to send an HTTP response; useShutdown::exit()for direct termination.