Phony Kahlan Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev eloquent/phony-kahlan
   

   Add to kahlan-config.php (if using dependency injection):

   Kahlan\Filter\Filters::apply($this, 'run', function (callable $chain) {
       Eloquent\Phony\Kahlan\install();
       return $chain();
   });
   

2. First Use Case: Mock a dependency in a test:

   use function Eloquent\Phony\Kahlan\on;
   
   describe('UserService', function (UserRepository $repo) {
       it('creates a user', function (UserRepository $repo) {
           on($repo)->save->with(new User())->returns(true);
           expect($this->service->create())->toBe(true);
       });
   });
   

Key Files to Reference

• eloquent/phony-kahlan (source)
• Phony Docs (mocking syntax)
• Kahlan Docs (test structure)

Implementation Patterns

Dependency Injection Workflow

1. Define Test Parameters:

   describe('OrderService', function (OrderRepository $repo, Logger $logger) {
       // $repo and $logger are auto-injected as mocks
   });
   

2. Stub Interactions:

   on($repo)->findById->with(1)->returns(new Order());
   

3. Verify Behavior:

   on($repo)->findById->calledWith(1);
   

Common Patterns

• Mocking External APIs:

  describe('PaymentProcessor', function (PaymentGateway $gateway) {
      on($gateway)->charge->throws(new Exception('Failed'));
  });
  

• Stubbing Callables:

  describe('EventDispatcher', function (callable $listener) {
      $listener->with('event')->returns(true);
  });
  

• Type-Specific Defaults:

  describe('DataTransformer', function (int $id, string $name) {
      // $id = 0, $name = ''
  });
  

Integration with Laravel

1. Mock Eloquent Models:

   describe('UserController', function (User $user) {
       on($user)->save()->returns(true);
   });
   

2. Stub Facades:

   describe('AuthController', function (callable $auth) {
       $auth->attempt()->returns(true);
   });
   

3. Test Service Providers:

   describe('AppServiceProvider', function (Container $container) {
       on($container)->make('UserRepository')->returns($mockRepo);
   });
   

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • Requires PHP 7.3+ (no longer supports 7.2/7.1).
   • Error: Class 'Kahlan\Filter\Filters' not found → Ensure Kahlan 5.x is installed.

2. Monkey-Patching Conflicts:

   • Disable Phony’s global monkey-patching in kahlan-config.php:

     $this->commandLine()->set('exclude', ['Eloquent\Phony']);
     

3. Final Classes in Mocks:

   • Cannot mock final classes (e.g., DateTimeImmutable).
   • Workaround: Use emptyValue() or stub a wrapper class.

4. Lazy Loading Issues:

   • If tests fail with Class not found, ensure Eloquent\Phony\Kahlan\install() runs after autoloading.

5. Type Hinting Quirks:

   • object type hints receive an empty stdClass by default.
   • Use on($obj) to access the mock handle.

Debugging Tips

• Verify Mocks:

  on($mock)->method->called(); // Check if called
  on($mock)->method->calledWith($args); // Check arguments
  

• Inspect Stubbed Callables:

  $stub = on($callable);
  $stub->calledWith($args)->firstCall()->returned($value);
  

• Reset Mocks Between Tests:

  beforeEach(function () {
      Eloquent\Phony\reset();
  });
  

Extension Points

1. Custom Default Values: Override Eloquent\Phony\Kahlan\emptyValue() in a service provider:

   Eloquent\Phony\Kahlan\emptyValue('App\Models\User', fn() => new User());
   

2. Global Stubbing: Pre-configure stubs in kahlan-config.php:

   Eloquent\Phony\stub('App\Services\Logger')->log()->returns(true);
   

3. Custom Matchers: Extend Phony’s matchers for complex assertions:

   Eloquent\Phony\matchers()->add('customMatcher', function ($actual, $expected) {
       return $actual === $expected;
   });