Oxylabs Api Laravel Package

Getting Started

1. Install the package and publish its config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Add Oxylabs credentials to .env (names depend on the published config, typically OXYLABS_USERNAME / OXYLABS_PASSWORD), then clear cached config:

   php artisan config:clear
   

3. Look first at:
   • config/<package>.php for credentials, base URL, timeout, and retry settings.
   • OxylabsApiClient for the supported request methods.
   • The result/content DTOs, especially WalmartProductResult and WalmartProductResultContentSeller, to understand the shape you will receive.
4. First use case: fetch a walmart_product payload and work with typed results instead of raw arrays:

   use Oxylabs\...\OxylabsApiClient;
   
   $client = app(OxylabsApiClient::class);
   
   $result = $client->walmartProduct('https://www.walmart.com/ip/...');
   
   foreach ($result->content->sellers ?? [] as $seller) {
       // official_name is nullable as of v0.10.1
       $name = $seller->official_name ?? 'Unknown seller';
   }
   

The v0.10.1 release is a patch-level compatibility fix: seller official_name is now nullable, and the client uses Laravel’s status() / headers() methods. There are no intentional breaking changes, but code that assumed official_name was always a string should be adjusted.

Implementation Patterns

• Resolve the client from the container. Bind or inject OxylabsApiClient rather than constructing it manually, so config, HTTP client, and future package changes stay centralized.

  public function __construct(private OxylabsApiClient $oxylabs) {}
  

• Treat DTOs as the boundary between transport and domain. Convert package results into your own application DTOs or arrays early. This isolates your code from nullable fields, added keys, and Oxylabs response changes.

• Handle optional fields defensively. Oxylabs omits keys when data is unavailable, and v0.10.1 specifically made WalmartProductResultContentSeller::$official_name nullable with a null default. Use null-safe access and fallbacks:

  $sellerName = $seller->official_name ?? $seller->name ?? 'Unknown';
  

• Use Laravel’s HTTP fakes in tests. Since the client reads response status and headers through Laravel’s status() / headers(), Http::fake() works naturally:

  Http::fake([
      '*/walmart_product*' => Http::response($fixture, 200, ['Content-Type' => 'application/json']),
  ]);
  

• Wrap requests in jobs for day-to-day scraping workflows. Product lookups are externally bound and slow; dispatch a queued job, persist the mapped result, and keep web requests fast.

• Add retry and timeout policy at the application boundary. If the package exposes timeout/retry config, set it in config. Otherwise wrap calls with Laravel’s HTTP retry behavior or your own job-level $tries / backoff.

• Log raw payloads before hydration when debugging. A TypeError during DTO construction usually means the response shape differs from expectations. Capture the decoded array first, then hydrate, so malformed payloads are diagnosable.

• Pin and upgrade deliberately. The official_name fix resolves a real failure mode for walmart_product seller payloads. If you previously worked around missing official_name by pre-normalizing arrays, remove that workaround after upgrading.

Gotchas and Tips

• Nullable does not mean always present. official_name is now ?string with a default of null, but callers must still use ?? or null checks. Do not pass it directly into strictly typed methods expecting string.

• Raw array/type mismatches surface as constructor TypeErrors. The v0.10.1 issue produced: WalmartProductResult::__construct(): Argument #1 ($content) must be of type ... array given When you see this class of error, inspect the raw Oxylabs payload and compare it with the DTO constructor before assuming the package is broken.

• Use Laravel HTTP methods, not PSR methods, in custom integrations. The client now reads status() and headers() directly, which keeps PHPStan happy across supported Laravel versions. If you extend or mock the client, follow the same pattern.

• Http::fake() must include the expected status and headers. A fake response without the expected content type or status can produce confusing parsing behavior. Assert both the raw response and the hydrated DTO.

• Config caching can hide credential changes. After editing Oxylabs credentials or endpoint settings, run php artisan config:clear in local development and ensure production deploys rebuild config cache.

• Do not rely on every seller key being present. Oxylabs may omit official_name; other optional keys may appear or disappear. Prefer defensive access over assuming a fixed schema.

• Debug at the transport layer first. Log the HTTP status, headers, and decoded JSON before DTO hydration. If hydration fails, the raw payload usually explains why faster than the stack trace.

• Extension point: wrap, don’t fork. For custom endpoints or response normalization, wrap OxylabsApiClient in your own service or decorator, or map package DTOs into application DTOs. Avoid editing vendor code so future patch releases such as v0.10.1 remain safe to apply.