Callmap Laravel Package

Getting Started

Install bovigo/callmap as a dev dependency with Composer:

composer require --dev bovigo/callmap ^9.0

Ensure PHP 8.3+ and an assertion provider (bovigo/assert or PHPUnit) are available. Begin by importing the main namespaces:

use bovigo\callmap\NewInstance;
use function bovigo\callmap\throws;
use function bovigo\callmap\onConsecutiveCalls;
use function bovigo\callmap\verify;

Start by creating a proxied instance (to exercise real methods unless stubbed) or a pure stub:

$instance = NewInstance::of(MyService::class, $constructorArgs);
// or
$stub = NewInstance::stub(MyService::class);

Then map method return values using returns():

$instance->returns([
    'fetchData' => ['id' => 42],
    'process'   => function($input) { return strtoupper($input); }
]);

Verify interactions:

verify($instance, 'process')->received('hello');
verify($instance, 'fetchData')->wasCalledOnce();

Implementation Patterns

• Use NewInstance::of() when you want real methods to run unless explicitly stubbed, e.g., for partial mocks where only certain dependencies are controlled.
• Use NewInstance::stub() for complete isolation—methods not in the callmap return default values (e.g., null, or self for self-returning methods).
• Leverage onConsecutiveCalls() for sequences (e.g., database retries, iterator-like behavior):

  $instance->returns(['next' => onConsecutiveCalls('a', 'b', throws(new \EOFError()))]);
  

• Pass-through via callables to inspect or transform arguments:

  'log' => fn(...$args) => error_log(json_encode($args));
  

• Chain verify calls in tests for clarity—group setup, act, and assert phases.
• Integrate with test frameworks: verify() returns objects compatible with PHPUnit assertions (extends ExpectationFailedException if PHPUnit available).
• For fluent interfaces, rely on auto-detection: if @return $this or return type is the class/interface itself (non-nullable), calling unmapped methods returns the instance.

Gotchas and Tips

• returns() overwrites the entire callmap on each call—merge mappings if needed or call it once with all stubs.
• Only non-static, non-final, public/protected methods can be mapped; final classes are unsupported.
• Missing methods in callmap trigger \InvalidArgumentException—great for catching typos (e.g., 'getuser' vs 'getUser').
• @return docblock support is deprecated and removed in v9.0; rely on native type hints.
• Optional parameters: defaults are not passed to callables unless explicitly provided in the call.
• throws() works with onConsecutiveCalls() for realistic failure sequences (e.g., initial success, then errors), but falls back to default return after exhausting values.
• Argument verification requires an assertion framework ( PHPUnit or bovigo/assert ); omitting it silently disables verification.
• Use wrap() only when you intentionally want to return the callable itself, not its result—rare, but useful for factory patterns.
• Debug tip: Run tests with -v to see full trace when CallAmountViolation or MissingInvocation is thrown.
• Performance note: Proxying via NewInstance::of() has minimal overhead, but stubbing (stub()) is faster for pure mocks.