Smartbots Bundle Laravel Package

Getting Started

Read this first: kynno/smartbots-bundle is a Symfony bundle, not a Laravel package. There is no SmartBotsServiceProvider, no config/smartbots.php to publish, and no auto-discovery. Installing it into a Laravel app gives you a package that only activates inside a Symfony kernel. In practice you have three options, in order of preference:

1. Depend on the underlying SmartBots API client directly (the bundle is a thin DI/config wrapper around it) and bind it yourself in a service provider.
2. Install the bundle and instantiate its client class manually from the container — skipping the bundle's Extension and Configuration entirely.
3. Fork it. With 2 stars, 0 dependents, and a small user base, this is the realistic long-term path.

Minimal steps (Laravel path):

composer require kynno/smartbots-bundle

Then read, in this order:

• DependencyInjection/Configuration.php — the real config schema (API key, bot name, base URI, timeouts). This is your source of truth for what .env keys you need.
• DependencyInjection/*Extension.php and Resources/config/services.* — shows which classes are services and what their constructor args are. Copy those constructor args into a SmartBotsServiceProvider.
• The client/API class itself — the actual HTTP calls and the action parameters it sends.

First use case: a queued job that sends an in-world IM or checks bot status/balance. As of v0.3, status and avatar_info are first-class calls on the client, so bot health-check and UUID-to-display-name resolution are now one-liners instead of raw HTTP. Something like:

// config/services.php
'smartbots' => [
    'api_key'  => env('SMARTBOTS_API_KEY'),
    'bot_name' => env('SMARTBOTS_BOT_NAME'),
    'base_uri' => env('SMARTBOTS_BASE_URI', 'https://api.smartbots.com/'),
],

// app/Providers/SmartBotsServiceProvider.php
$this->app->singleton(SmartBotsClient::class, fn ($app) => new SmartBotsClient(
    config('services.smartbots.api_key'),
    config('services.smartbots.bot_name'),
    config('services.smartbots.base_uri'),
));

Wrap it in a SmartBots facade so call sites read cleanly and you can swap the implementation later.

Implementation Patterns

Treat the client as infrastructure, not domain logic. Put a thin SmartBotsGateway interface in front of it (sendIm(), inviteToGroup(), getBotStatus(), getAvatarInfo()), implement it with the bundle's client, and bind it in the provider. When the package dies — and it will — you replace one class.

Queue everything. SmartBots calls are network-bound, occasionally slow, and rate-limited. Every call belongs in a job:

final class SendInWorldIm implements ShouldQueue
{
    use InteractsWithQueue, Queueable;

    public int $tries = 3;
    public array $backoff = [10, 60, 300];

    public function __construct(
        public string $avatarUuid,
        public string $message,
    ) {}

    public function handle(SmartBotsGateway $bots): void
    {
        $bots->sendIm($this->avatarUuid, $this->message);
    }
}

Retries with backoff matter more than usual here: a bot that is offline, mid-teleport, or rate-limited will return a transient failure, and hammering the API gets you throttled.

Use status as your health probe. v0.3 exposes the SmartBots status endpoint directly on the client. Wire that into a scheduled command (php artisan smartbots:health) alongside your queue workers so a silent bot fails loudly before user-facing jobs start throwing.

Use avatar_info to resolve UUIDs. The new avatar_info call turns a UUID into a display name and related metadata. Cache the result (avatars rarely rename) rather than hitting the API per inbox message — but keep a fallback to the raw UUID so unresolvable keys never break a listing.

Named connections for multi-bot setups. If you run more than one avatar, mirror Laravel's Manager pattern rather than passing a bot name into every call. The bundle's config is single-bot oriented; a BotManager keyed by connection name gives you Bot::connection('greeter')->sendIm(...) and keeps config in config/services.php where Laravel developers expect it.

Keep Second Life identifiers as first-class data. SL avatars are UUIDs, not integers, and group keys are UUIDs too. Store them as char(36) (or uuid where supported), index them, and keep a local avatars table mapping UUID → your user record. avatar_info now gives you a cheap way to backfill that table, but treat it as an enrichment step, not the primary key source.

Inbound side: a controller, not a bundle listener. If you receive callbacks or bot-forwarded IMs, handle them in a normal Laravel controller with a signature/shared-secret check, then dispatch a Laravel event. Do not try to wire the bundle's Symfony event dispatcher into Laravel's — bridge at the controller boundary instead:

Route::post('/webhooks/smartbots', SmartBotsWebhookController::class)
    ->middleware('throttle:120,1');

Test with Http::fake()— but only if you can route the client through Laravel's HTTP client. The bundle almost certainly uses Guzzle directly, so you'll be testing with GuzzleHttp\Handler\MockHandler or injecting a ClientInterface. Budget for this: write one test double for the gateway and use it everywhere else, so only a single test file knows the bundle exists.

Log request and response bodies. The SmartBots API returns cryptic, sometimes near-plaintext errors ("bot not found", "no money", "not in group"). Without the raw body in your logs, debugging is guesswork. Attach a Guzzle Middleware::history() in local/staging and dump it on failure.

Gotchas and Tips

The Symfony/Laravel dependency surface is the sharp edge. v0.3 adds Symfony 5 support, which means it can now coexist with Laravel 7 and 8 — a real improvement over the 2020-era pin that targeted Symfony 3/4. It does not cover Symfony 6, so Laravel 9, 10, and 11 remain out of scope. Run composer why-not before you commit. If Composer resolves, it may only be by downgrading something you wanted.

PHP 8 and Guzzle 7 compatibility is still unverified. v0.3 doesn't advertise a PHP or Guzzle bump. Treat the client as PHP 7-era: expect deprecation noise at minimum, and possible hard failures from non-nullable-parameter or ArrayAccess signature changes. Test on your actual PHP version before wiring anything real.

Do not register the bundle. There is no bundle.php / providers array entry to add in a Laravel app, and adding Symfony's FrameworkBundle machinery to get it loaded is a losing fight. Use the classes; ignore the bundle packaging. The status and avatar_info additions are client methods, not Laravel-runnable console commands you can just wire into app/Console/Kernel.php.

Secrets and bot credentials. The API key grants control over an avatar that can send messages and invite people to groups — treat it like a password. .env only, never in config/, and rotate it if a job payload dumps the config on an exception (Laravel's default Ignition/Whoops output can leak constructor-injected secrets — mark the key #[SensitiveParameter]).

Bot state is the number one source of "the API is broken." A bot that is offline, in the wrong region, out of L$, or has hit its group-invite limit will fail in ways that look like code errors. Before debugging your own code, verify: bot online, bot funded, bot in the target group, and no rate-limit lockout. The new status call makes this a one-liner to rule out — expose it via php artisan smartbots:status and check it first.

No JSON guarantee. SmartBots endpoints are inconsistent — some return JSON, some return text/plain, some return HTTP 200 with an error string. Do not assume json_decode() succeeds or that status code alone tells you success. Parse defensively and treat unrecognized payloads as failures. The new status/avatar_info responses are not exempt from this.

Extension points are Guzzle middleware and the gateway interface — that's it. There are no meaningful Symfony extension hooks worth bridging, and the package still has no ecosystem around it, so there's no community pattern to copy. v0.3 does not change that. Your own interfaces and middleware are the extension surface. Keep them thin and version-pinned.

Pin the version, and vendor the source if you're serious. The v0.3 release is a small patch (Symfony 5, two new endpoints) and shows the maintainer is still alive — but the surface area is tiny and there's still no dependent ecosystem to absorb future breakage. Either commit to a tagged version or copy the client class into app/Support/SmartBots/ with a header comment noting the origin and MIT license. A few-hundred-line HTTP client is cheaper to own than a dependency nobody maintains.

Consider replacing it outright. If your usage is a handful of endpoints, the SmartBots HTTP API is simple enough that a Http::withToken(...)->post(...) wrapper is genuinely competitive with adopting an abandoned bundle. The two new v0.3 endpoints are trivial to hand-roll. Do this if the bundle's dependency tree fights your Laravel version — which, on Laravel 9+, it still will.