Web Service Common Laravel Package

Getting Started

This package is not meant for direct use — it’s a shared internal dependency that powers MaxMind’s official PHP client libraries (e.g., maxmind/minfraud-api-php, maxmind/geoip2). As a Laravel developer, your first step is to install the actual client you need:

composer require maxmind/minfraud-api-php

This automatically pulls in maxmind/web-service-common as a transitive dependency. Confirm the relationship:

composer why maxmind/web-service-common
# Output: maxmind/minfraud-api-php 2.x requires maxmind/web-service-common ^0.11

Your first real use case: instantiating the public-facing client and making a request — e.g., IP geolocation or fraud scoring — where web-service-common silently handles auth, retries, error parsing, and cURL reuse behind the scenes.

Implementation Patterns

• Zero direct interaction: Never import or extend classes from this package. All functionality is exposed only through MaxMind’s official clients.

• Framework integration pattern: In Laravel, bind MaxMind clients in a service provider or use a custom facade. For example:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(\Minfraud\WebService\Client::class, function ($app) {
          return new \Minfraud\WebService\Client(
              config('maxmind.account_id'),
              config('maxmind.license_key'),
              ['lang' => 'en']
          );
      });
  }
  

  Under the hood, the client uses web-service-common’s HttpClient and Request abstractions for robust HTTP handling.

• Configuration via client options: Pass HTTP customizations (e.g., proxy, timeout) through the client constructor:

  new Client($accountId, $licenseKey, [
      'curl' => [
          CURLOPT_PROXY => env('HTTP_PROXY'),
          CURLOPT_TIMEOUT => 5,
      ],
  ]);
  

• Error handling: Catch exceptions like \MaxMind\Exception\AuthenticationException — these are defined in web-service-common, but their messages and types are stable and documented in the client’s API.

Gotchas and Tips

• ⚠️ Don’t pin this package: Version upgrades (e.g., 0.11.0 → 0.11.1) often involve silent internal changes (e.g., removal of no-op curl_close()). Always upgrade alongside the main client — never update web-service-common standalone.
• 🔥 PHP 8.1+ requirement: Since v0.10.0, this package requires PHP ≥8.1. If stuck on older PHP, use legacy clients (e.g., geoip2/geoip2:~2.13 still works on PHP 7.4).
• 🐛 Empty response edge case: Versions <0.8.1 crash on responses without a Content-Type header (e.g., minFraud report endpoint). Ensure your client version pulls in ≥web-service-common:0.8.1.
• 🧪 Testing strategy: Mock the public client (e.g., Minfraud’s Client), not web-service-common. Use Guzzle’s MockHandler or register a PSR-18 mock client if the target client supports it — avoid mocking low-level cURL.
• 📦 "Zero dependents" ≠ unmaintained: Despite no direct dependents, it’s actively used by MaxMind’s critical production clients. Check release notes for subtle fixes (e.g., v0.8.1’s bug fix for malformed responses). Always track updates via composer outdated on the main client, not this package.