- How do I install mcustiel/phiremock-codeception-extension in a Laravel project?
- Install it as a dev dependency with composer require --dev mcustiel/phiremock-codeception-extension, then enable \Codeception\Extension\Phiremock under the extensions section of your Codeception configuration. This is a Codeception-only package, so it will not do anything inside a plain PHPUnit or Pest suite. Version 4 requires Codeception 5, PHP 8 or newer, and symfony/process.
- Do I need to install phiremock-server separately, or can I run it from a phar or Docker?
- Phiremock Server is an optional Composer dependency of this extension. You can require mcustiel/phiremock-server in require-dev and let bin_path default to vendor/bin, or point bin_path at a phar, a globally installed Composer binary, or a wrapper that runs the server inside Docker. This flexibility is deliberate so the same config works locally and in CI. Note that wait_until_ready additionally requires phiremock-client to be installed via Composer.
- Which PHP and Codeception versions does this extension support?
- The 4.x line requires Codeception 5, PHP 8 or newer, and symfony/process, and it adds Symfony 8 support alongside Phiremock Server v2. Older stacks that still run Codeception 4 or older PHP versions need to stay on the 3.x releases. Check your composer constraints before upgrading, because the PHP floor moves with the major version.
- How is this different from Laravel's Http::fake() for mocking external APIs?
- Http::fake() intercepts requests in-process, so it never opens a socket and costs almost nothing per test. This extension instead starts a real Phiremock Server out of process, which buys fidelity for real headers, form data, TLS, redirects, retry and timeout behavior, and SDKs that bypass Laravel's HTTP facade. If your code only talks to external services through Guzzle via the facade, Http::fake() is simpler. Use Phiremock when your acceptance suite runs the served application and needs realistic network behavior.
- How do I configure the listen address, binary path, and logs for the Phiremock extension?
- Add the extension under the extensions config key in codeception.yml and set listen (defaults to 0.0.0.0:8086), bin_path (defaults to codeception_dir/../vendor/bin), logs_path, debug, and expectations_path (defaults to tests/_expectations). You can also choose between start_delay and wait_until_ready, define extra_instances for cases like simultaneous HTTP and HTTPS, supply certificate options, and set server_factory to bring your own PSR-18 client.
- How do I make Codeception wait until the Phiremock server is ready before running tests?
- Set wait_until_ready to true and tune wait_until_ready_timeout, which is in seconds and defaults to 30, and wait_until_ready_interval, which is in microseconds and defaults to 50000. Readiness polling requires phiremock-client to be installed through Composer. Without it, use start_delay as a cruder alternative, though a fixed delay is more fragile on slow CI machines.
- Can I run more than one Phiremock instance, for example HTTP and HTTPS at the same time?
- Yes, the extra_instances option lets you start additional servers alongside the primary one, which is the usual way to expose both an HTTP and an HTTPS endpoint. Each instance needs its own listen address, and HTTPS instances need the certificate configuration set. Remember the application under test must be able to reach every listen address, which is a common gotcha with container networking in CI.
- How do I limit the Phiremock extension to only certain Codeception suites?
- Use the suites option to list the suites that should trigger the server, and configure the extension per suite where needed. Per-suite extension configuration has been supported since Codeception 2.2.7. Scoping the server to acceptance suites that actually make external calls keeps the rest of your test suite fast and avoids unnecessary port usage.
- Is the GPL-3.0 license a problem for using this package in a Laravel application?
- As a dev-only dependency it normally never reaches production code, but two things deserve a legal check before rollout. First, confirm the package and its transitive dependencies are excluded from production artifacts and runtime images. Second, confirm that shared test base images or internal package mirrors do not count as redistribution in your organization, since that interpretation can stall adoption in regulated environments.
- What breaking changes does version 4 introduce when upgrading from v3?
- Version 4 moves the extension to Phiremock Server v2, raises the PHP version floor, requires Codeception 5, and adds Symfony 8 support. That is a breaking migration rather than a patch release, so teams pinned to older Codeception or PHP versions should stay on 3.x until they upgrade the rest of the stack. Also check that phiremock-client is present if you rely on wait_until_ready, and re-verify your expectation fixtures against the new server version.