Vwo Engage Laravel Package

Getting Started

• Verify the runtime floor before installing: Laravel 8 requires PHP >= 7.3; Guzzle 7 requires PHP >= 7.2.5. Confirm with php -v and composer show guzzlehttp/guzzle.
• Install with a v1.2 constraint: composer require vendor/package:^1.2. If Composer refuses, run composer why-not guzzlehttp/guzzle 7 to find the package pinning Guzzle 6.
• Look first at the package README for service-provider registration and configuration publishing. Publish config with php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider", then inspect base URI, timeout, auth, and middleware options.
• First use case: inject the package's documented client/manager into a controller or Artisan command and make one GET against a sandbox endpoint. Assert the status code and decoded JSON. This validates Laravel 8 package discovery, container binding, and the Guzzle 7 handler stack before you wire it into jobs or domain services.

Implementation Patterns

• Resolve the client from the container; do not new Guzzle clients in application code. Configure base URI, headers, timeout, and retry behavior in config/package.php so each environment can differ.
• Constructor-inject the package client into services, actions, and jobs. Avoid resolving it repeatedly inside loops; reuse the bound instance for connection and handler-stack reuse.
• Build a middleware stack for cross-cutting concerns: auth token injection, correlation/request IDs, structured logging, and retries. Keep middleware order deliberate: auth before logging if you need to redact credentials.
• Map transport failures to domain exceptions. Catch GuzzleHttp\Exception\ConnectException for DNS/connection failures, RequestException for 4xx/5xx responses, and let Laravel's exception handler render application-specific exceptions.
• In queued jobs, set connect_timeout and timeout below the queue worker --timeout. Use job middleware such as WithoutOverlapping for rate-limited third-party APIs.
• Test with Guzzle's MockHandler and HistoryMiddleware, bound into the container. Do not assume Laravel's Http::fake() intercepts this package; Laravel's HTTP client is separate from a package that wraps Guzzle directly.
• For retried writes, use idempotency keys or restrict retries to idempotent methods. Retry middleware is easy to enable globally and dangerous for non-idempotent POSTs.

Gotchas and Tips

• v1.2.0 is primarily a compatibility release: Laravel 8 and Guzzle 7 support. The upgrade risk is dependency resolution and Guzzle 6-to-7 behavior, not new package features.
• Guzzle 7 keeps the familiar ClientInterface and request options, but custom handlers, middleware, and streaming/redirect behavior should be re-tested. Run integration tests for multipart uploads, redirects, and streamed responses.
• Laravel 8 supports PHP 7.3, so avoid assuming PHP 7.4-only syntax in package extensions or custom middleware if you still support the lower bound.
• Guzzle's default timeout is infinite. Always set explicit timeout and connect_timeout; otherwise queue workers and web requests can hang indefinitely.
• Config caching breaks closures in config files. If the package config contains callables, move them into a service provider before running php artisan config:cache.
• Guzzle debug output and MessageFormatter can leak Authorization, Cookie, and API-key headers. Redact sensitive headers in logs.
• Never disable SSL verification in production. If a corporate CA is required, point verify at the CA bundle path instead of setting it to false.
• When mocking, the MockHandler queue must match the number of requests exactly. Use HistoryMiddleware to inspect unmatched requests and debug why a mock was not consumed.
• Extension point: bind a custom handler stack or client singleton in a service provider rather than editing vendor code. Check whether the package exposes middleware push/config hooks first.
• Debugging checklist: composer show vendor/package, composer why guzzlehttp/guzzle, inspect RequestException::getResponse()->getBody() for error payloads (with size guards), and enable the package's debug logging only in local/staging environments.