Saloon Logger Plug In Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The saloon-logger-plugin extends Laravel’s Saloon (a PHP HTTP client library) by adding structured logging capabilities. This aligns well with Laravel applications requiring debuggable, audit-friendly HTTP interactions (e.g., APIs, webhooks, or third-party services).
• Modularity: The plugin follows Saloon’s plugin architecture, making it a lightweight addition without forcing architectural changes. Ideal for teams already using Saloon or migrating to it.
• Observability Needs: Fits scenarios where:
  • HTTP request/response payloads need structured logging (e.g., JSON formatting for ELK/Logstash).
  • Debugging is critical (e.g., payment gateways, legacy integrations).
  • Compliance requires request/response auditing (e.g., GDPR, PCI).

Integration Feasibility

• Laravel/Saloon Compatibility: Designed for Saloon v4+ (PHP 8.1+). If the app uses Laravel 10+, integration is straightforward. For older versions, Saloon upgrades may be needed.
• Logging Backend Agnostic: Outputs structured logs (e.g., JSON), compatible with Monolog, Laravel Log Channels, or third-party loggers (e.g., Sentry, Datadog).
• Minimal Boilerplate: Plugin-based setup reduces manual logging code, but requires:
  • Saloon HTTP clients to be explicitly configured with the logger plugin.
  • Log formatting to match existing observability pipelines.

Technical Risk

Key Questions

1. Current Logging Stack:
   • Does the app use Monolog/Laravel Log Channels? If not, how will logs be routed?
2. Saloon Adoption:
   • Is Saloon already used, or will this require migrating from Guzzle/HTTP Client?
3. Performance Sensitivity:
   • Are HTTP clients in high-throughput paths (e.g., >1000 RPS)? Structured logging may add latency.
4. Compliance Requirements:
   • Are request/response logs needed for audits? If so, ensure retention policies align.
5. Error Handling:
   • How will failed requests (e.g., 5xx) be surfaced in logs vs. monitoring tools?

Integration Approach

Stack Fit

• Primary Use Case: Laravel apps using Saloon for HTTP clients (e.g., Saloon\Http\Client).
• Alternatives Considered:
  • Guzzle Middleware: If not using Saloon, Guzzle’s Middleware or LogMiddleware may suffice.
  • Laravel HTTP Client: For simple cases, Laravel’s built-in logging via tap() or throwIf().
• Tech Stack Synergy:
  • PHP 8.1+: Required for Saloon v4+ features (e.g., attributes, enums).
  • Laravel 10+: Recommended for dependency compatibility (e.g., Symfony components).
  • Logging Drivers: Works with single, daily, syslog, or custom channels.

Migration Path

1. Assess Current HTTP Layer:
   • Audit existing HTTP clients (Guzzle, Symfony HTTP Client, or raw file_get_contents).
   • Prioritize high-value endpoints (e.g., payment APIs) for Saloon migration.
2. Saloon Onboarding:
   • Replace GuzzleHttp\Client with Saloon\Http\Client.
   • Example:

     use Saloon\Http\Client;
     use BitMx\SaloonLoggerPlugin\LoggerPlugin;
     
     $client = new Client(base_url: 'https://api.example.com');
     $client->withPlugin(new LoggerPlugin()); // Enable logging
     

3. Logging Configuration:
   • Extend Monolog or Laravel’s logging config to handle JSON-formatted Saloon logs.
   • Example config/logging.php:

     'channels' => [
         'saloon' => [
             'driver' => 'single',
             'path' => storage_path('logs/saloon.log'),
             'level' => env('SALOON_LOG_LEVEL', 'debug'),
             'format' => Monolog\Formatter\JsonFormatter::class,
         ],
     ],
     

4. Incremental Rollout:
   • Start with non-critical endpoints to validate log structure.
   • Gradually replace clients, monitoring log volume and performance.

Compatibility

• Saloon Plugins: Confirmed compatibility with Saloon’s ecosystem (e.g., Saloon\Plugins\RetryPlugin).
• Middleware Conflicts: Avoid mixing with custom Saloon middleware that logs; prioritize one approach.
• PHP Extensions: No special extensions required (uses json_encode for payloads).

Sequencing

1. Phase 1: Set up Saloon in a feature branch for 1–2 endpoints.
2. Phase 2: Integrate LoggerPlugin and validate log output format.
3. Phase 3: Extend to all HTTP clients, adjusting log levels per environment.
4. Phase 4: Connect logs to observability tools (e.g., ELK, Datadog) and set up alerts for errors.

Operational Impact

Maintenance

• Plugin Updates: Monitor Saloon and saloon-logger-plugin for breaking changes (MIT license allows forks if needed).
• Log Rotation: Ensure Saloon logs are included in existing log rotation policies (e.g., Laravel’s log-rotate or custom cron jobs).
• Dependency Management:
  • Pin Saloon and plugin versions in composer.json to avoid unexpected updates.
  • Example:

    "require": {
        "saloon-php/saloon": "^4.0",
        "bit-mx/saloon-logger-plugin": "^1.0"
    }
    

Support

• Debugging Workflow:
  • Logs will include request/response metadata (headers, status codes, duration), reducing manual debugging.
  • Example log entry:

    {
      "timestamp": "2025-11-11T12:00:00+00:00",
      "level": "debug",
      "context": {
        "client": "PaymentGatewayClient",
        "method": "POST",
        "url": "https://api.example.com/charge",
        "headers": {"Authorization": "Bearer ***"},
        "payload": {"amount": 100, "currency": "USD"},
        "response": {"status": 200, "body": {"id": "ch_123"}},
        "duration_ms": 150
      }
    }
    

• Support Teams: Train devs/QA on interpreting Saloon logs for API issues.
• Vendor Lock-in: Low risk; plugin is lightweight and Saloon is open-source.

Scaling

• Performance Impact:
  • Minimal: Structured logging adds ~5–10ms per request (benchmark in staging).
  • Mitigation: Use log_level: 'info' in production for critical paths.
• Log Volume:
  • High-traffic apps may need log sampling or asynchronous logging (e.g., queue-based).
  • Consider Laravel Horizon for processing logs if using queues.
• Horizontal Scaling: Logs are local per instance; centralize with ELK/Fluentd if needed.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1–2 Hours: Add Saloon + plugin to a new endpoint.
  • Documentation: Create internal docs on:
    • How to enable logging per client.
    • Log format and fields.
    • Common log-based debugging patterns.
• **