nexphant/lifecycle

Ownership, resource lifecycle, and cleanup management.

Install

composer require nexphant/lifecycle

Basic Usage

Lifecycle manages structured owner scopes that track child items and resources (e.g. database connections, stream sockets) for auto-cleanup.

use Nexphant\Lifecycle\Lifecycle;

// Create a request-scoped lifecycle owner
$owner = Lifecycle::request();

// Register a resource under this owner
$owner->own($dbConnection);

// Spawn a child scope (e.g., for a background fiber)
$childScope = $owner->child();
$childScope->own($socket);

// Propagate cancellation
$owner->cancel();

// Safely close and release resources
$owner->close();

Factory Methods

All factory methods accept an optional ?OwnerScope $parent to attach the new scope into an existing hierarchy.

use Nexphant\Lifecycle\Lifecycle;
use Nexphant\Lifecycle\OwnerScope;

// Worker-scoped owner — top-level, owns the process lifetime
$worker = Lifecycle::worker();

// Request-scoped owner — attach to a parent worker scope
$request = Lifecycle::request(parent: $worker);

// Job-scoped owner — carries the job payload
$job = Lifecycle::job($jobPayload, parent: $worker);

// Task-scoped owner — carries the task payload
$task = Lifecycle::task($taskPayload, parent: $worker);

// Message-scoped owner
$message = Lifecycle::message(parent: $worker);

// Child fiber — always attached to a parent scope
$child = Lifecycle::childFiber(parent: $request);

When a parent scope is cancelled or closed, all child scopes are closed recursively first.

Owner Interface

Every lifecycle owner implements Nexphant\Lifecycle\Owner:

Method	Description
own(mixed $resource)	Register a resource for automatic cleanup on scope close.
spawn(callable $fn)	Spawn a child fiber scope bound to this owner.
cancel()	Request cancellation of this scope and all child scopes.
isCancelled()	Check if this scope or any parent has been cancelled.
close()	Recursively close children then release owned resources.
isClosed()	Check if this owner scope has been closed.

Scope Types

Factory	Scope	Carries
Lifecycle::worker()	Worker process	—
Lifecycle::request()	HTTP request	—
Lifecycle::job($payload)	Queue job	Job payload
Lifecycle::task($payload)	Scheduled task	Task payload
Lifecycle::message()	Message handler	—
Lifecycle::childFiber()	Background fiber	—

Auto Cleanup

When close() is called on an owner:

• All child scopes are closed first (depth-first).
• Registered resources implementing OwnedResource have their release() called.
• Raw stream/socket handles are closed with fclose().
• The scope is marked as closed and cannot be re-used.

Spawn Child Fiber

$request = Lifecycle::request();

$child = $request->spawn(function () use ($request) {
    // runs inside child fiber, owned by $request
    // automatically closed when $request closes
});

Resource Registration

Any object implementing OwnedResource or a raw PHP stream can be registered:

$owner->own($pdo);           // PDO connection
$owner->own($socket);        // stream resource
$owner->own($myResource);    // implements OwnedResource

Related

• nexphant/core
• nexphant/runtime
• Runtime Ownership