Callback Validator Laravel Package

Getting Started

Install via composer require daverandom/callback-validator. Begin by validating a simple callback signature—e.g., for an event listener like function (UserRegistered $event): void. Create a prototype closure ($prototype = fn(UserRegistered $e): void {}), derive a CallbackType ($type = CallbackType::createFromCallable($prototype)), and validate candidates ($type->isSatisfiedBy($candidate)). First use case: enforce strict listener signatures in your own event system before registration.

Implementation Patterns

• Plugin Hook Contracts: Define a canonical callback type (e.g., function (array $payload): array) and validate user-provided plugins/middleware before registration in a service provider.
• Macro Validation: Before calling Collection::macro(), validate the callback against a known signature to prevent runtime TypeError on misuse.
• Config-Driven Callbacks: In config/app.php or package config, register callbacks (e.g., for custom resolvers), then validate them at boot time using CallbackType—fail fast if mismatched.
• Test Assertions: In feature tests, assert that dynamically generated stubs (e.g., for queue jobs or event listeners) conform to expected signatures before invoking them.
• Conditional Relaxation: Use manual CallbackType construction to relax validation—e.g., omit required parameters for optional hooks or allow mixed returns with ReturnType::COVARIANT.

Gotchas and Tips

• Variance ≠ Compatibility: Contravariant parameters allow more specific types in candidates (e.g., ChildClass where ParentClass is expected), but less specific types fail. Returns are covariant: string is acceptable where ?string is expected, but string is not acceptable where string is expected but candidate returns ?string.
• Missing vs. Extra Params: Callbacks with fewer parameters than the prototype fail validation; those with extra parameters also fail unless you explicitly configure ParameterType to allow optional/variadic args (which this package does not support natively for ...$args).
• Debugging Is Manual: Use CallbackType::createFromCallable($candidate) and compare __toString() outputs. Build a helper to diff expected vs. actual signatures (e.g., echo "Expected: {$expected}\nGot: {$actual}\nMismatch: " . $expected->isSatisfiedBy($candidate) ? '✅' : '❌';).
• Performance: Reflection is cheap but not free—cache validated CallbackType instances in a registry during boot or use Laravel’s caching to store the validated types (e.g., in config() or custom cache key).
• Laravel Gotcha: Laravel’s Event::listen() already enforces return type hints at runtime—but only for closures with type hints. Use this package to enforce signature structure for untyped or loosely typed callbacks (e.g., from config or dynamic input), especially where void returns or strict argument counts matter.