Mockery Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no service provider, no config/mockery-bundle.php, and no Laravel container integration. If you are a Laravel developer reaching for this because of the "Mockery" in the name, stop here and use Laravel's built-in $this->mock() instead (see below). The bundle exists to let Behat scenarios swap a compiled Symfony DI service for a Mockery mock.

Minimal steps if you are genuinely on Symfony + Behat:

1. composer require --dev polishsymfonycommunity/mockery-bundle (expect Symfony 2.x/3.x era constraints; check composer.json before assuming it installs at all on a modern app).
2. Register the bundle: new PSS\Bundle\MockeryBundle\PSSMockeryBundle() in app/AppKernel.php (legacy) or config/bundles.php (Symfony 4+, if compatible).
3. Look first at the README and src/ — specifically the Behat context class and the console command that performs the service swap. Those two files define the entire public surface area.
4. First use case: in a *.feature file, mock an external collaborator (mailer, HTTP client, payment gateway) so a scenario can assert interactions without hitting the real thing, then run bin/behat as usual.

If you are on Laravel, the equivalent first step is: use Mockery; is already available via laravel/framework, and a first use case is $this->mock(StripeClient::class, fn ($m) => $m->shouldReceive('charge')->once()) inside a feature or unit test.

Implementation Patterns

Behat + Symfony (the intended path):

• Reset state between scenarios. Mocks leaked across scenarios cause order-dependent failures. Wire a @BeforeScenario/@AfterScenario hook that calls Mockery's close() or Mockery::close() and re-registers the container override.
• Swap only what you need. The bundle's value is replacing a real compiled service in the container with a mock, so keep the override narrow — mock the border service (a gateway, a clock, a repository), not an internal domain service.
• Assert interactions in the scenario. The point of the swap is shouldReceive(...)->once() style expectations; if you only need a stub, a plain test double is lighter weight.
• Keep feature files readable by hiding the swap behind a custom Behat context that wraps the bundle's context, so step definitions read like Given the payment gateway will decline.

Laravel equivalent (since this package will not work there):

• Use $this->mock(Service::class) in feature tests — it resolves from the container and integrates with the app's lifecycle.
• Use $this->swap(Interface::class, $fake) when you need to replace an already-bound singleton before the code under test resolves it.
• Use $this->instance() for value objects or config objects that are not mockable.
• Bind interfaces in a service provider under test ($this->app->bind(...)) for narrow integration tests rather than mocking everything.
• For Behat on Laravel, the closest analogue is binding mocks into the application in a BeforeScenario hook via $this->app->instance(...) — you will be writing that yourself; this bundle does not help.

Integration tips:

• Prefer constructor injection in the classes you want to swap; setter-injected or Container::get() calls to private services are much harder to override.
• In Symfony 4+, services are private by default. The swap mechanism relies on the container giving you access; if a service is private and not accessible from the test container, you will need public: true or a test-only service definition.

Gotchas and Tips

• Do not install this in a Laravel project. There is no ServiceProvider, no facade, and no config publishing. Composer may resolve it, but nothing will wire it up. Use $this->mock() / $this->swap() from Illuminate\Foundation\Testing.
• Symfony version constraints are the first blocker. Check composer.json for symfony/symfony or symfony/framework-bundle version ranges before planning anything; 15 stars and 0 dependents strongly suggests it has not tracked modern Symfony.
• Compiled container. You cannot just $container->set() a service in a booted Symfony app and expect it everywhere — the container may have already inlined the original into consuming services. The bundle's command-based swap exists precisely to work around this; do not bypass it with raw set() calls and expect consistency.
• Mockery lifecycle is your responsibility. Mockery::close() must run after every scenario, or expectation failures silently pile up and the next scenario fails with a confusing message. This is the single most common source of "works alone, fails in suite" bugs.
• Private services. If the service you want to mock is private, the swap will not be visible to consumers. Either widen visibility in the config or mock at the boundary where the service is still constructed via DI.
• Interaction assertions are brittle. Over-specifying shouldReceive('x')->with(exact args) couples scenarios to implementation. Prefer asserting on outcomes (return values, state) unless the interaction is the requirement.
• Debugging: dump the service you actually received (get_class($service)) inside the scenario to confirm the swap took effect; verify Mockery expectations with Mockery::getContainer()->mockery_getExpectationCount().
• Extension points are the Behat context and the console command. Subclass the context to add your own steps or hook into scenario setup/teardown rather than reimplementing the swap.
• Maintenance risk. Zero dependents means no ecosystem pressure to keep it green. Budget time to fork and patch, especially around Symfony and PHP version bumps.
• If your real goal is "mock services in Behat" and you are on a modern Symfony app, evaluate friends-of-behat/service-container-extension or Symfony's KernelTestCase-style override instead — this bundle is the ancestor of those approaches for legacy Symfony 2/3.