Buzz Bundle Laravel Package

Getting Started

Reality check first: juliendidier/buzz-bundle is a Symfony bundle, not a Laravel package. It has no ServiceProvider, no publishable config, and depends on symfony/framework-bundle and symfony/dependency-injection. Running composer require juliendidier/buzz-bundle in a Laravel app drags Symfony's container into your dependency graph for no runtime benefit. The bundle will not be booted by Laravel, and none of its services will be registered.

What you can actually leverage day-to-day is the underlying library — kriswallsmith/buzz — with the bundle's conventions as a wiring blueprint.

Where to look first (in the bundle source, if you want to mirror its behavior):

• DependencyInjection/BuzzExtension.php — the config tree: client class, timeout, default headers, listener registration.
• Resources/config/*.xml — the service definitions it would have registered under Symfony.
• Buzz\Browser and Buzz\Client\ClientInterface in the Buzz library — nearly all behavior lives here, not in the bundle.

Minimum viable Laravel binding to reproduce what the bundle does:

// app/Providers/BuzzServiceProvider.php
public function register(): void
{
    $this->app->singleton(\Buzz\Browser::class, function ($app) {
        $client = new \Buzz\Client\Curl();
        $client->setTimeout(10);
        $client->setVerifyPeer(true);

        $browser = new \Buzz\Browser($client);
        $browser->addListener(new \Buzz\Listener\LoggerListener(
            new \Psr\Log\LoggerInterfaceAdapter($app['log']->getLogger())
        ));

        return $browser;
    });
}

First use case: inject Buzz\Browser into a job or service and issue a request:

$response = app(\Buzz\Browser::class)->get(
    'https://api.example.com/things',
    ['Accept' => 'application/json']
);

if ($response->isOk()) {
    $data = json_decode($response->getContent(), true);
}

If you are not porting a Buzz-based Symfony app, stop here and use Illuminate\Support\Facades\Http. It is Guzzle-backed, has Http::fake(), retries, pools, and macros — a strict superset of what Buzz offers, with no framework-mixing cost.

Implementation Patterns

Wrap it behind an app-owned interface. This is the single most important pattern. Buzz is abandoned and pre-PSR-18; you do not want call sites coupled to Buzz\Browser. Define a small interface and bind one implementation to it:

namespace App\Contracts;

interface HttpClient
{
    public function get(string $url, array $headers = []): HttpResponse;
    public function post(string $url, array $headers = [], string $body = ''): HttpResponse;
}

Bind BuzzHttpClient in a service provider, resolve the interface everywhere. When you swap to Laravel's Http facade (or Guzzle) later, call sites don't change.

Configure the client once, in one provider. Mirror the bundle's extension: pick a ClientInterface (Curl or FileGetContents), set timeout, verifyPeer, and default headers in a single place. Do not scatter new Curl() across the codebase — that is exactly what the bundle existed to prevent on the Symfony side.

Listener chain for cross-cutting concerns. Buzz's listener API is the bundle's extension point and maps cleanly to Laravel's middleware concept. Use LoggerListener for request/response logging, and write a small custom listener for correlation IDs or timing:

class CorrelationIdListener implements \Buzz\Listener\ListenerInterface
{
    public function __construct(private string $id) {}

    public function preSend(\Buzz\Message\RequestInterface $request, \Buzz\Message\MessageInterface $response): void
    {
        $request->addHeader("X-Request-Id: {$this->id}");
    }

    public function postSend(\Buzz\Message\RequestInterface $request, \Buzz\Message\MessageInterface $response): void {}
}

Attach per-request rather than globally if the ID varies, since Browser listeners are shared state on a singleton.

Use it inside queued jobs, not controllers. HTTP calls are I/O and failure-prone. The bundle's design (a configured singleton Browser) suits long-lived workers; combine with retry() on the job, and keep timeouts tight on the client.

Testing. There is no Http::fake() equivalent for Buzz. Wrap the interface with a fake implementation for unit tests, and reserve real Buzz usage for integration tests against a local stub server (e.g., Http::fake() is unavailable here, so use a test double at your interface boundary).

Migration hygiene. If you are adopting this to port a Symfony app, do so behind your interface and log an exit ticket to Guzzle or Illuminate\Http\Client in the same sprint. Every feature built directly on Buzz\Browser raises the cost of that migration.

Gotchas and Tips

Don't composer require juliendidier/buzz-bundle in Laravel. It will resolve Symfony framework components into your tree with no benefit. If you need Buzz, require kriswallsmith/buzz directly and wire it yourself.

Buzz is end-of-life. Upstream was superseded by symfony/http-client and Guzzle. There is no security response path. Pin the version, document the exception in your SCA policy, and set a review date. The bundle itself is a 7-star, zero-dependent, bus-factor-one project — treat it as unmaintained even if it "still works."

Pre-PSR-7 message classes. Older Buzz releases use proprietary Buzz\Message\Request/Response. You cannot pass these to PSR-7 or PSR-18 consumers. Convert at the boundary of your HttpClient interface — do not leak Buzz message types into domain code.

TLS and timeout defaults can be unsafe. Old Buzz releases ship permissive defaults. Explicitly call setVerifyPeer(true) and setTimeout() on the client; do not rely on the bundle's config defaults being modern. Set verifyHost(true) too if your version exposes it.

No structured error taxonomy. Buzz throws generic exceptions on connection failures and returns non-2xx as a normal Response — you must check isOk() / getStatusCode() yourself. Wrap this in your interface so call sites do not parse exception messages, which break silently across environments.

Listeners on a singleton are shared state. If you addListener() on the singleton Browser in a long-running worker, the listener accumulates per request and may leak correlation IDs between jobs. Either bind Browser as bind() (per-resolution) or create a fresh browser per request via a factory.

Timeout discipline in workers. A hanging request blocks the worker. Set a client timeout and a job timeout; Buzz's curl backend will happily wait beyond a typical queue worker's --timeout if you forget.

Extension points to use when porting from Symfony: mirror BuzzExtension's config shape (client class, timeout, default headers, listeners) as a single Laravel config file (config/buzz.php) read by the provider. That keeps the Symfony config and the Laravel binding in one mental model during migration.

When you migrate off: map Buzz usage to Http::get()/post() with ->timeout() and ->retry(), replace multicurl usage with Http::pool(), and replace listeners with Guzzle middleware or Laravel's Http::beforeSending() hooks. If a Buzz\Client\ClientInterface adapter is depended on elsewhere, quarantine it — do not import the bundle to preserve it.