LibRuntimeGuard

LibRuntimeGuard

LibRuntimeGuard provides explicit execution boundaries and bounded failure reports for callbacks controlled by a plugin.

Repository:

https://github.com/ImperaZim/LibRuntimeGuard

Install

/easylibrary packages install libruntimeguard development confirm
restart
/elprobe run libruntimeguard

The standalone PHAR and EasyLibrary package are both published in the v1.0.0-dev pre-release.

Basic Use

use imperazim\runtimeguard\RuntimeGuard;

$guard = (new RuntimeGuard(100))->register('example-plugin');

$result = $guard->tasks()->execute(
    'refresh-cache',
    fn(): bool => $cache->refresh(),
    owner: 'ExamplePlugin'
);

if ($result->isFailure()) {
    $logger->error('Cache refresh failed.');
}

Available boundaries:

• arbitrary callbacks through ErrorBoundary;
• commands through CommandGuard;
• scheduled callbacks through TaskGuard;
• form responses through FormGuard;
• packet callbacks through PacketGuard.

PMMP Callback Adapters

RuntimeGuard::pmmp() wraps callbacks that your plugin already owns. It does not register commands, listeners, scheduler tasks or packet hooks by itself.

use imperazim\runtimeguard\GuardExecutionResult;
use imperazim\runtimeguard\RuntimeGuard;

$guard = (new RuntimeGuard())->register('example-plugin');
$pmmp = $guard->pmmp($this);

$handler = $pmmp->command(
    'profile',
    fn($sender, $command, string $label, array $args): bool => $this->profile($sender),
    static fn(GuardExecutionResult $result, array $arguments): bool => false
);

Without a failure handler, the original Throwable is rethrown after being recorded. With a handler, the fallback return value is an explicit plugin decision. The adapter records only scalar context such as sender/player names, UUIDs, command labels, packet class and response type.

Diagnostics

Registered guards appear in /easylibrary doctor and in:

runtime/runtime-guard.json

inside a support bundle. LibRuntimeInspector is optional; when installed, it translates guard failures into regular inspection findings.

Limits

LibRuntimeGuard does not recover fatal PHP process errors, PMMP engine faults or lifecycle failures outside a guarded callback. It preserves the original throwable, redacts common secrets and keeps only a configured number of recent failures.