Phiremock Server Laravel Package

Technical Evaluation

Architecture Fit

• Mocking/Stubbing Use Case: Phiremock is a perfect fit for Laravel applications requiring HTTP service mocking (e.g., API testing, CI/CD, or local development). It replaces external dependencies (e.g., Stripe, payment gateways, third-party APIs) with configurable responses, reducing flakiness and speeding up tests.
• REST/HTTP Focus: Aligns with Laravel’s ecosystem (e.g., HTTP clients like Guzzle, HTTP tests in Laravel Dusk/Pest). Complements tools like Laravel’s Http::fake() but offers advanced features (scenarios, priorities, latency simulation).
• Stateful Testing: Supports complex workflows (e.g., multi-step API interactions) via scenarios, which is critical for Laravel apps with stateful business logic (e.g., OAuth flows, multi-request transactions).
• Proxy Mode: Useful for intercepting real API calls during development without modifying code (e.g., redirecting http://api.example.com to Phiremock).

Integration Feasibility

• Laravel Compatibility:
  • HTTP Clients: Works seamlessly with Laravel’s built-in HTTP client (Http::get(), Http::post()) or Guzzle (v6/v7). The PSR-18 factory pattern allows customization (e.g., swapping Guzzle for Symfony’s HTTP client).
  • Service Providers: Can be bootstrapped as a Laravel service (e.g., register Phiremock’s REST API endpoints via routes/api.php or a service provider).
  • Configuration: Leverages Laravel’s environment-based config (e.g., .env overrides for EXTERNAL_SERVICE_URL to point to Phiremock in local/testing environments).
• Testing Frameworks:
  • Pest/Laravel Tests: Integrates via REST API (e.g., Http::post('/__phiremock/expectations', [...])).
  • Codeception: Native support via phiremock-codeception-extension (reduces boilerplate for acceptance tests).
  • PHPUnit: Can be used alongside Laravel’s Http::fake() for hybrid mocking strategies.

Technical Risk

• Dependency Isolation:
  • Risk: Phiremock is a dev-only dependency (installed via require-dev). Must ensure it doesn’t leak into production (e.g., via composer install --no-dev).
  • Mitigation: Use composer.json require-dev + CI/CD checks (e.g., composer validate).
• Performance Overhead:
  • Risk: Running Phiremock as a separate process adds latency (~10–50ms per request due to inter-process communication).
  • Mitigation: Use --port on localhost (avoid network hops) and disable debug mode (--debug=false) in production-like environments.
• State Management:
  • Risk: Stateful scenarios require careful cleanup (e.g., POST /__phiremock/reset after tests). Forgetting to reset can cause flaky tests.
  • Mitigation: Wrap tests in setUp()/tearDown() hooks (e.g., Pest’s beforeEach/afterEach) to reset Phiremock.
• Binary Data Handling:
  • Risk: Base64-encoded binary responses (e.g., images) may bloat expectation files and slow down tests.
  • Mitigation: Use external files for large binaries (e.g., store images in storage/app/phiremock/ and reference them via phiremock.file:path/to/image.jpg).

Key Questions

1. Environment Strategy:
   • How will Phiremock be toggled between local/testing vs. production? (e.g., .env variables, feature flags).
   • Example:

     # .env.local
     EXTERNAL_SERVICE_URL=http://localhost:8086/mocked_api
     

2. Expectation Management:
   • Will expectations be dynamically generated (via code) or statically defined (JSON files)? Hybrid approaches (e.g., code-generated JSON) may be needed.
3. CI/CD Impact:
   • How will Phiremock be spun up in CI? (e.g., Docker container, local process, or a shared service like ngrok).
   • Example Docker setup:

     # docker-compose.yml
     services:
       phiremock:
         image: composer:latest
         command: vendor/bin/phiremock --port 8086
         volumes:
           - .:/app
     

4. Monitoring:
   • Will request verification (/executions) be used for test assertions or runtime monitoring? If the latter, consider adding a Laravel listener to log Phiremock stats.
5. Security:
   • If using HTTPS, how will certificates be managed? (e.g., self-signed certs for local dev, Let’s Encrypt in CI).
   • Example:

     openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
     ./vendor/bin/phiremock --certificate cert.pem --certificate-key key.pem
     

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • HTTP Layer: Replaces Http::get() calls to external services with Phiremock endpoints. Works alongside Laravel’s Http::fake() but offers advanced matching (e.g., regex URLs, body content).
  • Testing: Integrates with Pest/PHPUnit via REST API calls or Codeception modules. Reduces need for complex test doubles (e.g., Mockery) for HTTP services.
  • Queue Workers: Can mock external queue services (e.g., SQS, RabbitMQ) by stubbing their HTTP APIs.
• Tooling:
  • Docker: Package Phiremock in a container for consistent CI/CD environments.
  • Postman/Insomnia: Useful for manually defining expectations via GUI before automating them in tests.
  • GitHub Actions: Spin up Phiremock as a service in workflows:

    services:
      phiremock:
        image: ghcr.io/mcustiel/phiremock-server:latest
    

Migration Path

1. Phase 1: Local Development
   • Replace direct API calls with Phiremock in config/services.php:

     'stripe' => [
         'url' => env('STRIPE_URL', 'http://localhost:8086/stripe_mock'),
     ],
     

   • Use --expectations-dir to load pre-defined JSON files (e.g., config/phiremock/expectations/).
2. Phase 2: Testing
   • Add Phiremock to phpunit.xml/pest.php:

     <env name="STRIPE_URL" value="http://localhost:8086/stripe_mock"/>
     

   • Use phiremock-client to dynamically set expectations in tests:

     use Mcustiel\Phiremock\Client\Client;
     
     $client = new Client('http://localhost:8086');
     $client->createExpectation([
         'on' => ['method' => ['isSameString' => 'POST'], 'url' => ['isEqualTo' => '/payments']],
         'then' => ['response' => ['statusCode' => 200, 'body' => '{"success": true}']],
     ]);
     

3. Phase 3: CI/CD
   • Run Phiremock as a service in GitHub Actions/CircleCI:

     - name: Start Phiremock
       run: composer require-dev mcustiel/phiremock-server --dev && ./vendor/bin/phiremock --port 8086 &
     

   • Use phiremock-codeception-extension for acceptance tests.

Compatibility

• Laravel Versions: Compatible with Laravel 8+ (PHP 7.4+) due to Guzzle v6/v7 support.
• HTTP Clients: Works with:
  • Laravel’s built-in HTTP client (PSR-18 compliant).
  • Guzzle v6/v7 (default).
  • Symfony’s HTTP client (via custom factory).
• Authentication: Supports mocking OAuth/JWT flows via scenario state transitions (e.g., first request returns a token, subsequent requests require it).
• WebSockets: Not supported (Phiremock is HTTP-only). Use Laravel Echo’s Pusher mocking for WebSocket services.

Sequencing

1. Setup:
   • Install via Composer (require-dev).
   • Configure .env and config/services.php to route traffic to Phiremock in non-production environments.
2. Define Expectations:
   • Create JSON files in --expectations-dir or set dynamically via REST API.
   • Example workflow:

     # Start Phiremock
     ./vendor/bin/phiremock --expectations-dir ./config/phiremock/expectations --port 8086
     
     # In tests:
     $this->post('/__phiremock/expectations', $expectationJson);