Phpunit Mock Objects Laravel Package

Getting Started

In modern Laravel development, you do not install phpunit/phpunit-mock-objects directly—it was fully merged into PHPUnit’s core by PHPUnit 5.4 (2015) and the package is now archived/unmaintained. To start mocking today:

1. Install PHPUnit (e.g., composer require --dev phpunit/phpunit).
2. In your test class (extending PHPUnit\Framework\TestCase), use $this->createMock(Foo::class) or $this->getMockBuilder(Foo::class) immediately.
3. First real-world use case: Mock a service dependency in a controller test:

   $paymentGateway = $this->createMock(PaymentGateway::class);
   $paymentGateway->method('charge')->willReturn(['status' => 'succeeded']);
   $controller = new CheckoutController($paymentGateway);
   

Implementation Patterns

• createMock() is the idiomatic Laravel test pattern: concise, chainable, and type-hint safe:

  $mailer = $this->createMock(Mailer::class);
  $mailer->method('send')->willReturn(true);
  

• Partial mocks with onlyMethods() for legacy or fragile classes:

  $order = $this->getMockBuilder(Order::class)
      ->onlyMethods(['validateStock'])
      ->disableOriginalConstructor()
      ->getMock();
  $order->method('validateStock')->willReturn(false);
  

• Argument constraint chaining for precision:

  $logger->expects($this->once())
      ->method('error')
      ->with($this->stringContains('payment failed'));
  

• Prefer atLeast()/atMostOnce() over at() to avoid brittle test order dependencies (common in parallel test runs).
• For Laravel’s service container: Mock a concrete class, then bind it manually in tests:

  $repository = $this->createMock(UserRepository::class);
  app()->instance(UserRepository::class, $repository);
  

Gotchas and Tips

• ⚠️ This package is obsolete and dangerous to use directly. Never add phpunit/phpunit-mock-objects as a project dependency—its API is now in phpunit/phpunit and conflicts will arise (e.g., class redefinition, autoloader chaos).
• Argument cloning: In older versions (v1.2.0+), setCloneArguments(false) could preserve references—but modern PHPUnit uses shallow cloning by default and this setting is irrelevant unless maintaining ancient code.
• Prophecy vs PHPUnit mocks: Many Laravel teams prefer phpspec/prophecy (via phpspec/prophecy-phpunit) for its decoupled, intent-based mocking. If starting new, consider adopting Prophecy—it avoids mocking implementation details (e.g., constructor signatures).
• Laravel's test helpers: You may still see $this->mock() in TestCase (Laravel’s custom helper), but it’s just a Prophecy wrapper—not tied to this package.
• Legacy migration: If your codebase still references this package (e.g., phpunit/phpunit-mock-objects: ^1.2), update to phpunit/phpunit:^9.6 and ensure tests use createMock()—no code changes are needed since the API is identical.
• CI red flags: If mocks behave inconsistently (e.g., "cannot redeclare class" errors), check composer.lock for orphaned phpunit/phpunit-mock-objects—remove it and regenerate autoloader (composer dump-autoload).