Plugin Mockery Laravel Package

Getting Started

Install the plugin and enable it in one command sequence:

composer require --dev "psalm/plugin-mockery"
./vendor/bin/psalm-plugin enable psalm/plugin-mockery

That’s it — no config changes needed. Run ./vendor/bin/psalm and observe improved type inference: Mockery::mock(UserRepository::class) now returns UserRepository&Mockery\MockInterface instead of mixed. Your first win? No more @var docblocks like /** @var Mockery\MockInterface&UserRepository $mock */ — Psalm infers them automatically in tests.

Implementation Patterns

• Typed mocks: Prefer typed mock creation:
  $mock = Mockery::mock(UserService::class);
  Psalm now knows $mock is both UserService and Mockery\MockInterface, enabling safe method calls and accurate type checks.
• Strict expectation chaining: Use explicit variables for expectation chains to preserve type fidelity:

  $mock = Mockery::mock(UserService::class);
  $mock->shouldReceive('handle')->once()->andReturn(true);
  // Psalm keeps $mock typed as UserService&Mockery\MockInterface
  

• Spy support: Leverage Mockery::spy() — Psalm correctly infers Mockery\MockInterface&YourClass and validates shouldHaveReceived() usage against the real interface.
• No-break integration: Works instantly in PHPUnit, Pest, or Codeception — just run Psalm as usual. No test file modifications required.

Gotchas and Tips

• Mockery version alignment: Ensure mockery/mockery ≥1.0. Older versions (e.g., 0.9.x) won’t benefit from new-style typing — and may cause incorrect inference.
• Constructor args break inference: When mocking classes with complex constructors (Mockery::mock(Service::class, [$arg1, $arg2])), Psalm may widen types if args lack precise types. Provide narrow constructor hints or use @phpstan-param in docblocks.
• Spies vs mocks: Spies (spy()) lack full expectation-type inference — avoid deep chaining like $spy->shouldHaveReceived()->once()->with(...) without splitting into steps.
• Custom matchers: Mockery::on(fn() => ...) often loses return type context. Suppress cautiously with @psalm-suppress if no better alternative exists.
• Psalm v6/v7 quirks: On Psalm v7, watch for stricter noDocblockTypes rules — the plugin still infers types even without docblocks, but if you omit @var entirely, ensure your Psalm config doesn’t reject native intersection types.