Phiremock Codeception Extension Laravel Package

Technical Evaluation

Architecture fit

• This is not a mocking library — it is a ~lifecycle orchestrator. It starts phiremock-server before a Codeception suite and stops it after, and reads a YAML config block. The actual request matching, expectation schema, and HTTP semantics live in phiremock-server; the client-side expectation API lives in a third package, phiremock-codeception-module.
• That three-package shape matters for a TPM: adopting this extension is adopting Phiremock as a platform, not adding a utility. Budget review effort for the server and module, not just this repo.
• It operates out-of-process over a real socket. That is the defining choice versus Laravel's Http::fake() / Http::preventStrayRequests(), which intercept in-process. Out-of-process buys fidelity (real headers, form data, TLS, redirects, retry/timeout behavior, SDK-internal transports); in-process buys speed, zero ports, zero supervision.
• For a Laravel codebase that already uses Http::fake(), this package's incremental value is narrow and specific: acceptance-level tests of the served application (Codeception acceptance suite hitting artisan serve/nginx), testing non-Guzzle clients or SDKs that ignore Laravel's HTTP facade, and TLS/port-level scenarios.
• It is Codeception-only. Laravel's default test harness is PHPUnit/Pest. If Codeception is not already a committed part of the stack, adopting this extension is effectively a vote to keep Codeception — surface that explicitly.

Integration feasibility

• Requirements are concrete and checkable: Codeception 5, PHP 8+, symfony/process. v4.0.0 additionally requires phiremock-server v2, bumps the PHP floor, and adds Symfony 8 support. wait_until_ready requires phiremock-client via Composer.
• Config surface is genuinely useful for a Laravel/CI context: listen (bind address/port), bin_path, logs_path, debug, start_delay vs. wait_until_ready (with timeout/interval), expectations_path, suites filter, extra_instances (e.g., simultaneous HTTP + HTTPS), certificate*, and server_factory for bringing your own PSR-18 client (Guzzle 6 vs 7 is a real-world friction point this solves).
• suites: [] filtering and per-suite extension config (Codeception ≥2.2.7) let you scope the server to only the suites that need it — important for keeping the rest of the suite fast.
• Deployment flexibility (vendor binary, phar, global Composer dep, or Docker) is the right call for mixed CI/local environments and reduces lock-in.

Technical risk

• Bus factor 1 / adoption signal is weak. 31 stars, 0 dependents. This is a single-maintainer package with a thin maintenance footprint. Mitigation is cheap because the code is glue, but it must be an explicit, owned risk.
• GPL-3.0. Dev-only dependency is normally safe, but two things need a legal check before rollout: (a) confirm it never lands in production artifacts/images; (b) confirm your use of shared test base images or internal mirrors doesn't trigger redistribution questions. This alone can stall adoption in regulated orgs.
• Version-coupling churn. The v3 → v4 jump (Phiremock Server v1→v2, PHP floor bump, Symfony 8) is a breaking migration, not a patch. Teams pinning old Codeception/PHP will be stranded on v3.x; teams upgrading Laravel/PHP will be forced forward.
• Process supervision is the real failure surface. Port collisions, orphaned server processes after aborted runs, CI container networking (the app-under-test must be able to reach the mock's listen address), and readiness timing. wait_until_ready mitigates the readiness case but adds a dependency on phiremock-client.
• Expectation-format coupling. Fixtures are Phiremock JSON, not Laravel-native. Getting them wrong tends to fail as confusing 404s rather than clear errors.
• Laravel-specific gap: there is no Laravel-native ergonomics here. No config publishing, no facade, no RefreshDatabase-style lifecycle. Any "Laravel integration" is really "Codeception + Laravel module + env-var wiring," which you build.

Key questions to resolve before committing

1. Is Codeception a strategic part of our test stack, or legacy we are migrating off? (If the latter, stop here.)
2. Which specific tests fail today because of vendor sandbox unavailability, rate limits, or credentials — and can Http::fake() cover them instead?
3. Does CI permit per-suite process spawning and port binding? How do we allocate ports under parallel test execution?
4. Does the app-under-test run in a different container/host than the tests? If so, what is the reachable address for the mock, and who owns that network contract?
5. Has legal signed off on GPL-3.0 in a dev dependency, including shared test images?
6. Are we prepared to own the v3→v4 upgrade (PHP floor, Phiremock Server v2, Symfony 8) on someone's roadmap?

Integration Approach

Stack fit

• Target usage: Codeception acceptance suites (and optionally functional suites) where the Laravel app is served over HTTP and makes outbound calls to third parties. The pattern is: extension starts Phiremock on 127.0.0.1:18080; the app's config/services.php base URL is pointed at that address via an env var set for the test environment; Phiremock returns canned responses; assertions run against the app's response and, if needed, Phiremock's request log.
• Keep the boundary explicit: in-process fakes (Http::fake(), Queue::fake(), Event::fake()) for unit/feature tests; Phiremock for acceptance/e2e tests that must traverse the real HTTP stack. Do not migrate existing fast tests to a socket-based mock — that is a net regression in speed and stability.
• Expectation fixtures become first-class repo artifacts under tests/_expectations (or a configured path). That is a contract artifact; treat it as an API surface with review, ownership, and versioning, not as test detritus.

Migration path

1. Pilot, don't rollout. Pick one suite and one flaky/unavailable third-party dependency. Measure before/after: external calls per run, wall-clock time, flake rate, re-run count.
2. Run Phiremock manually first (vendor/bin/phiremock or phar) and validate expectation JSON and app wiring by hand. This isolates "is the mock correct?" from "is the extension orchestrating correctly?" — a distinction that saves days of debugging later.
3. Then enable the extension with wait_until_ready: true and suites: scoped to the pilot suite. Avoid start_delay as a permanent solution; it is a race condition with a sleep timer.
4. Write down the exit ramp. Because the extension is thin, the fallback is a Codeception _bootstrap.php/global extension that shells out to Phiremock directly, or a Docker Compose service. Document it — it is ~50 lines and it defuses the single-maintainer risk almost entirely.
5. Then expand to extra_instances (HTTP + HTTPS) only if you actually need TLS fidelity; otherwise stay single-instance.

Compatibility

• Verify the matrix explicitly: PHP version × Codeception 5 × Phiremock Server v2 × Symfony 8 × Guzzle 6/7 (via server_factory). Laravel 11 is referenced in v3.1.0; confirm your Laravel version and the Codeception Laravel module compatibility independently — the extension itself is Laravel-agnostic.
• If you need Guzzle 7 or a custom PSR-18 client, plan the server_factory subclass up front; it is a small class but requires phiremock-server as a local Composer dependency (not phar/Docker), which constrains your deployment choice.
• Docker-based execution is supported, but confirm how bin_path is used to invoke it and whether your CI runner needs a Docker socket — that is an infrastructure ticket, not a config line.

Sequencing (order of work)

1. Decision memo: Codeception strategic or not → go/no-go on the whole package.
2. Legal/licensing confirmation on GPL-3.0 (dev-only, images, mirrors).
3. Manual Phiremock spike + expectation fixture draft for one dependency.
4. CI plumbing: port allocation, container networking, teardown guarantees, log artifact collection.
5. Extension enablement scoped to one suite; measure.
6. Fixture ownership/process definition (who reviews expectation JSON when a vendor API changes).
7. Expansion decision + documented exit ramp.

Operational Impact

Maintenance

• Ongoing cost is low in lines-of-code terms but non-zero in coordination: this repo's releases track upstream Codeception/PHP/Symfony/Phiremock versions, and you inherit that upgrade treadmill. The v4 line is a fresh compatibility baseline, so expect to move again when the next Codeception or Symfony major lands.
• Two upgrade levers you do not control: Phiremock Server's expectation schema (v1 vs v2 formats differ) and Codeception's extension API. Both have broken before.
• Assign a named internal owner ("we own the test-infra layer"), even though you don't own the code. The realistic plan is: pin versions, watch releases, and be ready to fork or replace the ~50-line lifecycle shim.

Support

• No vendor, no SLA. GitHub issues + one maintainer. Response latency for a CI-breaking bug could be days.
• Because the extension is thin and the failure modes are mostly environmental (ports, processes, paths), most incidents are diagnosable in-house — provided logging is configured. Set debug: true and logs_path to a CI artifact directory from day one; Phiremock's log of received requests is the single most valuable debugging artifact you get.
• The separate Codeception module (phiremock-codeception-module) handles client-side expectation management. Teams routinely conflate the two in troubleshooting; document the split in your internal runbook.

Scaling

• Per-suite server startup means parallel test execution multiplies processes and ports. Codeception's parallelism story is weaker than PHPUnit/Pest's; if you scale test workers, plan a deterministic port-allocation scheme (e.g., worker index → base port) or your CI will produce intermittent bind failures.
• Containerized CI: the mock must bind to an address reachable from the app-under-test container, and the port must be exposed on the runner network. This is often the single largest unplanned integration task.
• State hygiene: expectations loaded per suite can bleed between tests if not reset. Reset belongs to the module/config discipline, not to this extension — verify per-test reset behavior explicitly, and add a "zero expectations" guard test.

Failure modes (and the mitigations a TPM should fund)

• Port already in use / stale process → dynamic ports or pre-flight cleanup step; trap-based teardown in CI.
• Server not ready when tests start → wait_until_ready: true with explicit timeout/interval; not start_delay.
• Orphaned mock process after aborted run → CI job-level cleanup; containers are better than bare processes here.
• Wrong expectations_path → silent no-stub behavior manifesting as opaque 404s/connection errors; add a startup assertion that the expectation directory exists and is non-empty.
• Certificate/TLS misconfiguration → tests hang or fail with SSL errors; only enable certificate* when a test genuinely needs HTTPS.
• Log path permissions / PCNTL-disabled environments → historically fragile; validate on your runner image early (there is prior history of PCNTL-related log issues in this project's changelog).
• Silent version drift between extension and Phiremock Server v1/v2 → pin both and assert versions in CI.

Ramp-up

• Developer ramp is modest but multi-source: they must learn (a) Codeception extension YAML config, (b) Phiremock's expectation JSON schema, (c) the module's expectation-loading API, and (d) the env-var wiring from app config to mock address. Realistically half a day for a developer already fluent in Codeception, one to two days including CI plumbing and one end-to-end contract.
• QA ramp is where the leverage is: once fixtures exist, QA can run acceptance against stubbed vendors with no credentials, no sandbox accounts, and no rate limits. That is the operational payoff worth funding — and the metric to report upward is reduction in vendor-induced CI failures and re-runs, not test count.
• Document one thing above all: when to use Http::fake() versus when to use Phiremock. Ambiguity here will cause teams to over-apply the heavier tool and quietly make the suite slower and flakier.