APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

APPNETOS shutdown registration and execution flow
Registration and execution are centralized in the shared shutdown controller.

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; use Shutdown::exit() for direct termination.

Next Steps

Previous

Log

Explore Log

Next

Exception

Explore Exception