Phiremock Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Ecosystem Synergy: Phiremock’s PHP-native design aligns perfectly with Laravel’s HTTP stack (e.g., HttpClient, Route::fallback(), and Http::fake()). It can be deployed as a Dockerized service, a Laravel Artisan command, or integrated via service providers, making it a first-class citizen in Laravel’s architecture.
• Testing Paradigm Support:
  • Unit/Integration Testing: Replaces flaky external API calls in Laravel’s phpunit or Pest tests with deterministic mocks.
  • Contract Testing: Validates API contracts (e.g., OpenAPI specs) by enforcing request/response schemas via regex or JSON matching.
  • E2E Testing: Works alongside Laravel Dusk or Codeception to mock APIs in browser-based tests.
• Microservices Alignment: Useful for service-to-service testing in Laravel microservices, where teams need to mock downstream services (e.g., a UserService mocking a PaymentService).
• Hybrid Testing: Supports proxy mode to forward requests to real APIs during development while still allowing mock overrides for specific tests.

Integration Feasibility

• Composer Dependency: Simple require-dev installation with guzzlehttp/guzzle (already used in Laravel for HTTP clients).
• REST API for Dynamic Control: Phiremock’s REST interface enables runtime configuration, useful for:
  • Laravel Tinker/Artisan: Dynamically set up mocks during debugging.
  • CI/CD Pipelines: Load test-specific mocks via API calls in GitHub Actions/GitLab CI.
• Codeception Plugins: Leverages existing Laravel-Codeception integrations (e.g., _generated/config/codeception.php) for zero-config testing.
• JSON Schema Validation: Supports JSON-based expectations, which can be validated using Laravel’s spatie/fork or nunomaduro/collision for schema compliance.

Technical Risk

• Deprecation Risk:
  • Version 2.0 Bundle: The split into phiremock-server and phiremock-client may cause confusion. The bundle’s role is now unclear—does it add value, or should teams use the standalone repos directly?
  • Dependency Stagnation: react/http (v0.7) and symfony/cache (v4) are outdated. Laravel 10+ may introduce breaking changes (e.g., PSR-15 middleware, Symfony 6+).
• Performance:
  • Latency Overhead: Running Phiremock as a separate process (even in Docker) adds ~50–200ms latency vs. in-memory mocks (e.g., Laravel’s Http::fake()).
  • Memory Usage: Stateful mocks with complex expectations (e.g., regex, dynamic responses) may consume significant memory over time.
• State Management:
  • Race Conditions: In CI/CD, concurrent test runs might corrupt shared state if not reset properly (e.g., reset() method in Codeception).
  • No Built-in Persistence: Mock configurations are ephemeral unless saved to JSON/files, which could complicate distributed testing.
• Security:
  • GPL-3.0 License: May conflict with proprietary Laravel apps (consult legal team).
  • No Auth for REST API: Phiremock’s REST interface is unauthenticated, risking accidental configuration changes in shared environments.

Key Questions

1. Upgrade Path:
   • What are the breaking changes when migrating from v1.x to v2.x (or standalone repos)? Can the bundle be deprecated in favor of direct repo usage?
   • Are there community forks actively maintaining compatibility with PHP 8.2+?
2. Laravel-Specific Gaps:
   • How does Phiremock handle Laravel’s signed routes, CSRF tokens, or middleware (e.g., VerifyCsrfToken) in mocked requests?
   • Can it intercept Laravel’s HttpClient without manual proxy configuration?
3. Testing Workflow:
   • How to reset state between test suites in Laravel’s phpunit.xml or Pest configurations?
   • Does it support parallel test execution (e.g., Pest’s --parallel) without state collisions?
4. Alternatives:
   • Should we evaluate Laravel’s built-in Http::fake() for simple cases, or Pest’s HTTP testing for a more modern approach?
   • For advanced use cases (e.g., request recording), would WireMock (via Docker) or Mountebank be worth the Java dependency?
5. Long-Term Strategy:
   • If Phiremock is abandoned, what’s the exit plan? Rewrite mocks using Laravel’s Http::fake() + custom logic?
   • Can we contribute back to the project (e.g., PHP 8.2+ support, Laravel integration PRs)?

Integration Approach

Stack Fit

• Laravel Core Integration:
  • Service Provider: Register Phiremock as a Laravel service (e.g., PhiremockServiceProvider) to manage lifecycle (start/stop server, load JSON configs).
  • Artisan Command: Add phiremock:serve to spin up the server locally (php artisan phiremock:serve --port=8080).
  • Environment Config: Use .env variables to toggle Phiremock (e.g., PHIREMOCK_ENABLED=true).
• Testing Frameworks:
  • Pest: Create a custom Http::fake() extension to delegate to Phiremock.
  • Codeception: Use the existing phiremock-codeception-extension with Laravel’s Codeception adapter.
• CI/CD Pipeline:
  • GitHub Actions: Spin up Phiremock in a matrix step before running tests.
  • Docker: Use the official mcustiel/phiremock image or a custom Dockerfile with Laravel.
• Monitoring:
  • Laravel Horizon: Log Phiremock’s REST API usage for debugging (e.g., track unexpected request patterns).

Migration Path

1. Pilot Phase:
   • Start with one Laravel module (e.g., AuthService) to mock external APIs (e.g., OAuth providers).
   • Use JSON-based expectations for version-controlled mocks.
2. Gradual Rollout:
   • Replace hardcoded HTTP clients (e.g., Http::get('https://api.example.com')) with Phiremock-configured clients.
   • Example:

     // Before
     $response = Http::get('https://api.example.com/users');
     
     // After (using Phiremock)
     $response = Http::withOptions(['base_uri' => 'http://phiremock:8080'])
                     ->get('/users');
     

3. CI/CD Integration:
   • Add Phiremock to test containers in Docker Compose:

     services:
       phiremock:
         image: mcustiel/phiremock-server
         ports:
           - "8080:8080"
         volumes:
           - ./tests/mocks:/etc/phiremock
     

   • Load mocks from tests/mocks/*.json via phiremock-client in phpunit.xml:

     <php>
         <env name="PHIREMOCK_CONFIG" value="/etc/phiremock"/>
     </php>
     

4. Fallback Strategy:
   • Use Laravel’s Http::fake() for simple cases (e.g., unit tests).
   • Reserve Phiremock for integration/E2E tests where realism is critical.

Compatibility

Sequencing

1. Phase 1: Local Development
   • Install Phiremock via Composer and add it to composer.json under require-dev.
   • Use phiremock:serve to mock APIs locally (e.g., Stripe, Twilio).
2. Phase 2: Test Automation
   • Integrate with Pest/Codeception via extensions.
   • Load mocks from JSON files in tests/mocks/.
3. Phase 3: CI/CD
   • Add