Askr Laravel Laravel Package

Getting Started

Start by reading the package's main CHANGELOG at the linked repo and the README to confirm which drivers ship with the Laravel bridge (config/askr.php is the first place to look after install). The typical setup is:

1. composer require kwhorne/askr (pin to ^1.8).
2. Publish config: php artisan vendor:publish --tag=askr-config.
3. Register the service provider (auto-discovered on Laravel 9+, but verify in bootstrap/providers.php on 11+).
4. Add credentials to .env (driver-specific keys) and cache config with php artisan config:cache.

Your first use case should be the smallest integration surface: resolve the driver via the container (app(Askr::class) or the injected contract) and make a single call inside a route or artisan command. Don't wire it into a queue or HTTP controller until you've confirmed the driver resolves and the credentials work. Look first at the driver interface/contract, then at the concrete drivers shipped under src/Drivers/, then at the CHANGELOG for anything in 1.8.x that changed defaults or signature.

Implementation Patterns

Bind-and-inject over facades where possible: the drivers are best consumed through the published contract so you can swap fakes in tests. A common daily pattern is a thin AskrService wrapper that owns your default driver, retry policy, and logging, keeping driver details out of controllers.

For multi-driver setups, register named instances in a service provider:

$this->app->singleton('askr.default', fn ($app) => $app->make(AskrManager::class)->driver(config('askr.default')));

Typical workflows:

• Controllers/jobs: inject the contract, not the manager. Queue long-running driver calls and always set tries, backoff, and a timeout slightly above the driver's own timeout.
• Testing: use the package's fake/binding in setUp() so unit tests never hit the network; assert on the contract calls rather than driver internals.
• Feature toggles: gate driver selection behind config or a tenant column so you can switch providers without code changes.
• Observability: wrap calls in your own middleware or a decorator to capture latency and failure reasons, since driver-level errors are usually wrapped exceptions.

Integration tips: prefer config-driven driver selection (config('askr.drivers')) over hardcoding class names; keep prompt/payload builders in dedicated classes so driver swaps don't ripple through the app; and cache the resolved manager rather than re-resolving per call.

Gotchas and Tips

• Config caching: driver lists resolved at boot won't reflect .env changes until php artisan config:clear. Always clear after editing config/askr.php.
• Driver resolution vs. boot: resolving a driver in a service provider's register() can fail if credentials aren't loaded yet — resolve lazily in the consuming class or bind a closure.
• Timeout mismatches: Laravel's HTTP/job timeouts and the driver's own timeout are separate. A 30s queue timeout with a 60s driver timeout yields confusing partial failures.
• Testing pitfalls: fakes usually only intercept the contract layer; anything that bypasses it (direct Http:: calls in a custom driver) won't be faked. Bind your custom driver explicitly in tests.
• Version pinning: 1.8.4 is a patch release pointing at the main changelog — read that before bumping, because the bridge's driver set can change with the main package even when the bridge version only ticks the patch number. Lock to ~1.8.0 until you've reviewed the 1.8.x changelog for deprecations.
• Extension points: custom drivers should implement the shipped driver contract and be registered through the manager's extend()/config map rather than replaced by subclassing the manager. This keeps you upgrade-safe across 1.8.x.
• Debugging: log the resolved driver name and the config key it came from on failure; most "it used the wrong driver" bugs are stale config cache or a mis-scoped singleton rather than a package bug.