Budbee Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. There is no composer require + auto-discovery path. The realistic onboarding is:

1. Read the config first. Open vendor/setono/budbee-bundle/src/DependencyInjection/Configuration.php. This file is the authoritative list of every value you'd need to supply (API key, endpoint, environment, etc.). Translate each node to a key under config/services.php (services.budbee.*) or a dedicated config/budbee.php.
2. Read the service definitions next. src/Resources/config/services.xml (or .yaml) tells you which concrete classes exist and their constructor signatures. That's what you'll bind in a Laravel ServiceProvider.
3. Check SetonoBudbeeBundle.php. It's almost always empty — all wiring lives in the extension. Skipping the bundle registration costs you nothing.
4. Look for the underlying client. Most Setono bundles are thin wrappers over a separate PHP client (setono/budbee-php-client or similar). If one exists, install that and ignore the bundle entirely — it's the same code without the Symfony DI wrapper.

First use case: create a shipment or fetch delivery options for a cart. In Laravel you'll do this by constructing the client/service class directly from your provider, not by resolving it from Symfony's container.

// app/Providers/BudbeeServiceProvider.php
public function register(): void
{
    $this->app->singleton(BudbeeClient::class, fn () => new BudbeeClient(
        apiKey: config('services.budbee.api_key'),
        endpoint: config('services.budbee.endpoint'),
    ));
}

Implementation Patterns

Pattern 1 — Extract and bind (recommended). Pull the concrete classes out of the bundle (Client, shipment creators, DTOs), bind them in a service provider, and translate any %setono_budbee.*% parameter references into config('services.budbee.*'). You get the working code without the Symfony baggage.

Pattern 2 — Config mapping. Convert the Symfony TreeBuilder config into a Laravel config file and a validation rule set. Symfony validates at boot; Laravel doesn't, so replicate the required/default behavior with config() defaults and a small validator at provider boot time.

Pattern 3 — Webhooks over event listeners. Where the bundle expects Symfony event subscribers for tracking updates, use a Laravel route + controller (or a queued job) for Budbee's callbacks. Don't try to wire the bundle's event tags — Laravel's dispatcher is a different contract.

Pattern 4 — Scheduling polling. Shipment status sync becomes a Schedule::command('budbee:sync')->hourly() calling a queued job, rather than a Symfony console command.

Pattern 5 — E-commerce integration. If you're building on Lunar or a custom checkout, wrap Budbee delivery-option lookup behind your own interface (e.g. DeliveryOptionProviderContract). This makes Budbee swappable when the API changes and keeps the checkout code framework-agnostic.

Pattern 6 — Fork as a package. MIT license makes this legitimate and often the right call: fork, strip DependencyInjection/, keep the DTOs and client, and publish as yourvendor/laravel-budbee with a proper ServiceProvider. This is more work up front but gives you a maintainable artifact instead of a copy-paste.

Gotchas and Tips

• No service provider. php artisan package:discover will not pick this up. You must wire everything manually.
• Symfony-specific wiring won't translate. Anything tagged (kernel.event_subscriber, monolog.logger, http_client.client) has no Laravel equivalent — those services will silently not be injected.
• HTTP client mismatch. The bundle almost certainly depends on symfony/http-client. Laravel apps usually use Guzzle via Http:: facade. Swapping to Guzzle is often less work than dragging a second HTTP abstraction into the stack.
• Config tree validation is lost. Symfony throws on unknown keys at container boot; Laravel doesn't. Add explicit validation if config mistakes are likely (API key present, endpoint well-formed, environment is one of test|live).
• Zero adoption is a signal. Stars: 0, dependents: 0, last release 2024-03-06. That means almost no one is exercising this against a real Budbee account. Run composer audit and pin versions. Verify endpoints against Budbee's current API docs — an unmaintained client will not warn you when Budbee bumps a version.
• Debugging path. Before wiring the bundle's services, prove credentials work by instantiating the client in php artisan tinker. Log raw request/response bodies behind a thin wrapper service — you'll spend less time debugging auth than debugging "which layer swallowed the error."
• Testing. Symfony's MockHttpClient fixtures (if present in the bundle's tests) translate cleanly to Guzzle MockHandler or Http::fake(). Reuse the recorded JSON fixtures rather than inventing your own — they reflect what the real API actually returns.
• Don't fight the framework. For a single Laravel app, the effort to un-bundle a Symfony bundle usually exceeds writing a ~200-line client against Budbee's REST API directly. Use the bundle as reference documentation: the DTOs show you the response shape, the service definitions show you the call sequence, the config tree shows you what to collect from operators. That's the most realistic day-to-day leverage you'll get from it.