Phiremock Codeception Extension Laravel Package

Product Decisions This Supports

• Build vs. buy for test-environment infrastructure. This package is a thin orchestration layer (start/stop lifecycle) around Phiremock Server. It answers a question PMs actually face: do we hand-roll Docker Compose + mock-server scripts in CI, or adopt a maintained extension? At 31 stars and 0 dependents, it is effectively "build" with extra steps — the decision is whether the ~50 lines of lifecycle glue it saves is worth a single-maintainer dependency.
• Third-party integration risk posture. It makes "we cannot test against the real vendor" an explicitly solvable problem: acceptance suites can run hermetically against stubbed payment, shipping, KYC, tax, or OAuth endpoints instead of vendor sandboxes that are rate-limited, credentialed, or intermittently down. That is a decision to decouple release cadence from vendor availability, which is a roadmap-level commitment, not a code detail.
• CI cost and flake budget. Starting one or more mock servers per suite instead of hitting live sandboxes cuts external network calls, credential provisioning, and vendor-side outages from the test path. If your CI dashboard shows third-party timeouts as a recurring cause of red builds, this is a candidate remediation with a measurable before/after (build time, flake rate, re-run count).
• Feature scoping for "testable by default." It enables a definition-of-done clause: any new outbound integration ships with a recorded/stubbed contract so QA can run acceptance tests without vendor access. That changes estimation and acceptance criteria across the roadmap, not just one ticket.
• Framework consolidation decisions. Because this is Codeception-only, adopting it is implicitly a vote to keep Codeception. That is a genuine architectural fork in the road and should be surfaced in any PHP stack modernization plan (Codeception → PHPUnit/Pest, or Laravel's Http::fake()), rather than discovered later as migration friction.
• Where it does not help: Laravel teams already served by Http::fake() / Http::preventStrayRequests() get the same isolation in-process with no extra server, no extra port, no extra process supervision. That is the honest baseline this package must beat.

When to Consider This Package

Adopt when several of these are true:

• You already run Codeception (acceptance, functional, or API suites) and the suites live in codeception.yml / suite YAML. The extension is configured entirely through the extensions: block — no bootstrap PHP, no CI shell scripts. If you are not on Codeception, this package has no surface area for you.
• The stub must be a real network endpoint. This is the decisive criterion vs. in-process fakes. Laravel's Http::fake() intercepts the client before the transport layer, which means it will not exercise Guzzle handler stacks, retry/backoff middleware, connection-refused and timeout paths, DNS failures, TLS behavior, or any outbound call made from a separate process (queue worker, scheduler, Octane worker, a Node/Cypress end-to-end run, a Python data job). A listening mock server on 127.0.0.1:18080 covers all of those; a fake does not.
• You need TLS. The certificate / certificate_key / cert_passphrase options let you test HTTPS-only code paths (strict certificate verification, SNI, misconfigured-CA error handling) that are genuinely painful to simulate in-process. Few fakes can do this at all.
• You want the same stub to serve multiple suites or multiple consumers. extra_instances with per-instance listen, expectations_path, and suites lets one config stand up, say, an HTTP instance for api and an HTTPS instance for acceptance, sharing one YAML file. That is a real ergonomic win over hand-rolled process management.
• Deterministic startup matters more than speed. wait_until_ready with wait_until_ready_timeout/interval health-gates the suite instead of a start_delay sleep. For flaky CI this is the single most valuable option in the package; if you adopt it, turn this on.
• The vendor sandbox is the bottleneck. Credentialed, rate-limited, or regularly-down sandboxes are the classic case. Decoupling acceptance tests from vendor uptime is a legitimate roadmap-level win.
• Version compatibility lines up. v3.0.0 requires PHP 8 + Codeception 5; v3.1.1 adds PHP 8.4; v4.0.0 moves to phiremock-server v2 and Symfony 8. You need a recent, maintained PHP toolchain — this is not a package for legacy stacks.
• You can tolerate GPL-3.0 as a dev dependency. It is require-dev only and never ships to production, so most legal reviews clear it, but get that in writing before adoption rather than after.

Look elsewhere when:

• You are a Laravel/PHPUnit or Pest shop. This is the primary disqualifier. Http::fake() + Http::preventStrayRequests() inside a Pest/PHPUnit test gives you isolation with zero new processes, zero ports, zero cleanup, and no dependency. Reach for a live mock server only if you can articulate a specific gap (process boundary, TLS, cross-language consumer) that fakes cannot close.
• You want a mainstream mock-server ecosystem. WireMock, Mountebank, and Mockoon offer record/replay proxying, a web UI, far richer matchers, and much larger communities. Phiremock's JSON-expectation model is capable but niche; hiring and knowledge transfer are easier on the bigger names.
• You need non-HTTP protocols. WebSockets, gRPC, message brokers, and GraphQL-over-persisted-queries are out of scope. Phiremock is HTTP request/response with JSON expectations.
• You need per-test (not per-suite) lifecycle control. The extension's granularity is suite-level start/stop. If your tests demand a fresh expectation set per test method with hard isolation, you will be writing reset logic in a helper anyway — at which point a module or an explicit Docker Compose service is more honest.
• Containerized CI is already your norm. If everything runs in containers, a docker-compose service or Testcontainers gives you the same endpoint with better portability, no PHP-specific glue, and no single-maintainer risk.
• Supply-chain risk tolerance is low. 31 stars, one maintainer, zero dependents, and a release cadence driven by individual issues. If your organization gates dev dependencies on maintenance depth, this fails that gate — and its value proposition (saving orchestration boilerplate) is small enough that failing the gate should end the conversation rather than trigger an exception process.
• You are planning to leave Codeception. Do not adopt it as part of a migration away from Codeception; you would be buying glue for the framework you are exiting.

How to Pitch It (Stakeholders)

To executives — one paragraph: This is a small, free, open-source test-infrastructure helper. It automatically stands up a simulated third-party API before our automated test suite runs and tears it down after. Practically, it lets us test payment, identity, shipping, and other vendor integrations without calling the vendor — no sandbox credentials, no rate limits, no waiting on their outages. The upside is faster, more reliable releases and fewer "the vendor was down so we skipped QA" incidents. The cost is near zero in licensing and engineering time, but it carries single-maintainer risk and a GPL-3.0 license that legal should clear as a development-only dependency. Recommendation: a time-boxed spike (1–2 sprints of one engineer at part-time capacity), gated on a clear before/after on build flake rate — not a wholesale adoption.

To engineering leadership — the honest framing:

• What it is: ~50 lines of process-supervision glue. It starts phiremock-server on suite begin, health-checks it, and kills it on suite end. All the actual stubbing intelligence lives in Phiremock Server, which is a separate dependency you may or may not add.
• The real decision is not "this package yes/no" — it is "do we test outbound HTTP as a real network endpoint, or as an in-process fake?" If in-process fakes (Http::fake(), Mockery, Guzzle mock handlers) cover our cases, this package is redundant and we should say no quickly. It earns its place only where the transport layer itself is under test — retries, timeouts, TLS, or calls originating outside the PHP request lifecycle.
• Adoption is coupled to Codeception. Saying yes is a soft commitment to Codeception for the lifetime of these suites. Flag it in any PHPUnit/Pest consolidation discussion now, not during the migration.
• Operational footprint: an extra listening port per suite (plus extra_instances if you want HTTP and HTTPS), a supervised child process, and log files under the tests output dir. Small, but real — it is one more thing that can fail on a CI box with constrained ports or zombie process reaping. The wait_until_ready health gate is what keeps that from becoming flake; default it to true in our config rather than accepting the package's false.
• Support and upgrade risk: PHP 8.4 and Symfony 8 are supported as of the latest releases, so we are not buying into a dead branch today. But one maintainer, 31 stars, and zero dependents means we should assume we may have to fork or replace it within a couple of years, and keep the config thin enough that swapping in a docker-compose service is a half-day job.
• Success criteria for the spike: (1) a vendor integration tested end-to-end with the vendor's sandbox disabled, (2) measurable reduction in CI flake attributable to third-party calls, (3) written legal sign-off on GPL-3.0 as a dev-only dependency, (4) a documented fallback path if the package goes unmaintained.
• If the spike fails any of those, the answer is in-process fakes plus a Compose-managed WireMock for the small set of cases that genuinely need a socket — not this package.