Download the PHP package muhammadhuzaifa/telescope-guzzle-watcher without Composer

We Stand With Palestine, Pakistan Stand With Palestine

Telescope Guzzle Watcher

Telescope Guzzle Watcher provide a custom watcher for intercepting http requests made via guzzlehttp/guzzle php library. The package uses the on_stats request option for extracting the request/response data. The watcher intercept and log the request into the Laravel Telescope HTTP Client Watcher.

Once the installation and configurations are completed, you will be able to see the request logs under telescope/client-requests

Table of Contents

• We Stand With Palestine, Pakistan Stand With Palestine
  • Telescope Guzzle Watcher
  • Table of Contents
  • Requirements
  • Installation
  • How It Works
  • Configuration Reference
  • Registering the Watcher
  • Resolving Guzzle Clients
  • Using Multiple Clients
  • Integration Example: HubSpot PHP SDK
  • Testing \& Verification
  • Troubleshooting
  • Changelog
  • Credits
  • Other Projects
  • License

Requirements

• PHP ^8.4
• Laravel 12.x
• Laravel Telescope ^5.11
• Guzzle ^7.9

Installation

Install the package via Composer:

Laravel's package auto-discovery will register the service provider for you. No manual provider entry is required unless auto-discovery is disabled.

After the package is installed, publish the configuration file so that you can tweak the watcher defaults:

The published file lives at config/telescope-guzzle-watcher.php.

How It Works

1. Client Hijacking via the Container – The package binds GuzzleHttp\Client in the service container to a custom Guzzle Client Factory. Every time a client is resolved from the container, the factory injects an on_stats callback that forwards request and response information to Telescope.
2. Transfer Stats Hook – Guzzle fires the on_stats callback when a request completes (successfully or not). The watcher converts the raw PSR-7 request/response objects into Laravel's Illuminate\Http\Client\Request and Response wrappers so that Telescope can index the payload.
3. Telescope Recording – When Telescope is actively recording, the watcher forwards each HTTP transfer to the client-requests panel, applying configuration such as tag extraction, payload truncation, and header redaction.

Because the watcher is a first-class Telescope watcher, it benefits from all Telescope filters, tags, and search capabilities right out of the box.

Configuration Reference

The configuration file ships with the following options:

Tweak these settings in config/telescope-guzzle-watcher.php and cache your configuration if your deployment workflow requires it (php artisan config:cache).

Registering the Watcher

Tell Telescope to use this watcher by updating your config/telescope.php file:

Set the value to true to enable it or to a configuration array if you want to supply watcher-specific options in-line (for example, to disable it per-environment using a closure).

Resolving Guzzle Clients

For the watcher to intercept traffic you must resolve Guzzle clients through Laravel's service container:

If you already provide an on_stats callback, the factory will wrap it so both Telescope and your callback execute.

Using Multiple Clients

The watcher supports any number of clients or middleware stacks as long as they are resolved through the container. A few patterns you may find useful:

• Per-service bindings:

• Custom middleware: resolve the client as normal, then push additional middleware. Telescope will continue to receive the transfer statistics.

Integration Example: HubSpot PHP SDK

The HubSpot PHP SDK ships with a Pluggable HTTP client stack. To hook it into Telescope you only need to hand it a Guzzle client from the container.

1. Install the SDK

2. Bind a HubSpot client that reuses the Telescope-aware Guzzle client

   Adjust the configuration array to include proxies, retry middleware, or any other Guzzle options your integration needs.

3. Use the client

   Each call will now appear in Telescope under Client Requests, tagged with api.hubapi.com and the path segments (unless you disable URI tagging).

Tip: HubSpot APIs enforce rate limits. Telescope will record both successful responses and 429 errors so you can diagnose throttling in development.

Testing & Verification

1. Run a request through your application that uses the container-resolved Guzzle client.
2. Visit https://your-app.test/telescope/client-requests (or the path configured for Telescope) to verify the entry.
3. Adjust configuration options and clear caches as needed.

Automated testing tips:

• The package itself is tested with Orchestra Testbench. If you write integration tests, boot Telescope or fake it appropriately to avoid polluting production storage.
• You can disable Telescope during certain tests with Telescope::withoutRecording(fn () => /* perform requests */); if you only want to test the client behavior.

Troubleshooting

• No entries appear: Confirm that Telescope is enabled (TELESCOPE_ENABLED=true) and that you are resolving Guzzle via the container. Telescope only records when Telescope::isRecording() returns true.
• Entries missing payloads: Increase size_limit in the package config or ensure the response body is seekable. Streams that cannot be rewound will be labeled as Stream Response by Telescope.
• Headers still visible: Remember that header names are case-insensitive; ensure you use the exact header key (for example, Authorization) in the except_* arrays.
• Existing on_stats logic not firing: The factory preserves your callback. If you replace the client configuration elsewhere, make sure you merge with the container-provided config instead of instantiating a fresh client.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Huzaifa Saif-ur-Rehman

Other Projects

• Laravel Pulse Guzzle Recorder
  • Laravel Pulse Guzzle Recorder provide a custom recorder for intercepting http requests made via guzzlehttp/guzzle php library and log them into the Laravel Pulse Slow Outgoing Requests section.

License

The MIT License (MIT). Please see License File for more information.