Invoker Laravel Package

Getting Started

php-di/invoker is a lightweight library for resolving and invoking callables with dependency injection support. To get started:

• Install via Composer: composer require php-di/invoker
• Use the Invoker\Invoker class directly, or integrate it with a container like PHP-DI, PHP-DI Bridge, or PSR-11 implementations
• The core pattern: $invoker->call($callable, $parameters) where $parameters can include named arguments, positional fallback, or container-resolved dependencies

Example first use:

$invoker = new Invoker\Invoker();
$callback = function (UserService $userService, $userId) {
    return $userService->getUser($userId);
};
$result = $invoker->call($callback, [
    'userId' => 123,
    // UserService will be resolved automatically if container-aware or passed explicitly
]);

Implementation Patterns

• Type-hinted dependencies: Let the invoker auto-resolve dependencies from the callable's type hints (requires a PSR-11 container, either injected or via ContainerInterface extension)
• Named parameters: Pass an associative array matching parameter names for clarity and resilience to refactoring
• Fallback resolution: Supports both named and positional resolution—positional works only if no name match exists and count matches exactly
• Middleware wrapping: Wrap the invoker with MiddlewareInterface implementations to add logging, timing, or exception handling before/after invocation
• Extension via Resolver\ResolverInterface: Provide custom resolvers for parameters (e.g., environment-specific values, config injection)

Typical workflow:

1. Instantiate Invoker with optional PSR-11 container or resolver chain
2. Wrap in middleware for cross-cutting concerns (e.g., profiling)
3. Call dynamic callbacks with partial/fully specified parameters
4. Return resolved/invoked result (including closures, invokables, strings, arrays, etc.)

Gotchas and Tips

• Container dependency: While optional, omitting a PSR-11 container means no automatic resolution of type-hinted parameters—you must pass all dependencies explicitly
• Parameter name vs. signature order: PHP 8.0+ named parameters may not match runtime parameter names if compiled with --with-external-pdo or obfuscation—always use named arrays with explicit keys
• Performance: Avoid creating many invokers per request; Invoker is stateful but safe to reuse (especially when combined with ContainerInterface)
• Middleware ordering matters: Resolvers run in order—first match wins; ensure custom resolvers are registered before default container-based ones if overriding behavior
• Fallback pitfalls: Mixing named and positional arguments in call() can cause ambiguity; prefer explicit named arrays for maintainability
• Debugging tip: Use var_dump($invoker->getParameters($callable)) to inspect what the invoker expects to resolve before calling
• Extension point: To support framework-specific injections (e.g., Laravel’s request, Symfony’s user), implement a custom Resolver\ResolverInterface and prepend it to the resolver chain