Php Invoker Laravel Package

Getting Started

Install as a dev dependency: composer require --dev phpunit/php-invoker. Its sole purpose is to safely execute callables (e.g., closures, invokables, or arrays like [$class, 'method']) with a strict timeout—commonly used in test suites to prevent hung processes from blocking CI runs. The most common first use case is wrapping potentially long-running test assertions:

use PHPUnit\Invoker\TimeoutInvocationException;
use PHPUnit\Invoker\Invoker;

$invoker = new Invoker;

try {
    $invoker->invoke(fn() => $this->doSomethingSlow(), timeout: 1.5);
} catch (TimeoutInvocationException $e) {
    $this->fail('Operation timed out');
}

Check src/Invoker.php for the core API—only two methods exist: invoke() and call()—so documentation fits in minutes.

Implementation Patterns

• Test isolation: Wrap risky test operations (e.g., external API mocks, process spawns) with timeouts to fail fast instead of hanging.
• CI safety nets: Add try/catch around assertions in @after or @afterEach hooks to abort if cleanup logic hangs.
• Async-like control: Combine with pcntl_async_signals(true) and signal handlers to gracefully terminate timed-out operations (e.g., kill file watchers or sockets).
• Integration with Pest/PHPUnit: In PHPUnit, use it in setUp() or tearDown(); in Pest, wrap expectations in ensure() callbacks:

  ensure(fn() => $this->doAsyncThing())->passesBefore(2.0);
  

  (Note: Must manually handle timeouts—no automatic Pest integration exists.)

Gotchas and Tips

• Requires ext-pcntl: The package depends on PCNTL for non-blocking timeouts. This fails silently on Windows (where pcntl_* functions are absent)—tests will timeout indefinitely unless you guard usage with function_exists('pcntl_async_signals').
• Signal handling is critical: Without enabling async signals (pcntl_async_signals(true)), timeouts may not interrupt cleanly. Always call this before invoking timed code.
• PHP 8.4+ only: v7.0.0 dropped support for older PHP versions—check your runtime to avoid surprises in CI.
• Timeout is soft: The invocation may complete after the timeout if it doesn’t check for signals (e.g., tight loops without tick callbacks). Use declare(ticks=1) inside the callable for reliable interruption.
• Extensibility: For advanced control, extend Invoker and override handleTimeout()—but note the class is final in v7+, so modify via composition instead.
• Debugging timeouts: Log the timeout duration and callable details—use $invoker->invoke($callable, 0.5, 'my-test-timeout'); (third param is a descriptive label logged on timeout).