Bagisto Chatbot Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and confirm the version constraint. v1.0.0 is the first stable tag, so pin it explicitly ("^1.0") rather than using dev-main — there is no established SemVer track record yet.
• Check whether the package registers itself via Laravel's package auto-discovery by inspecting the extra.laravel block in its composer.json. If it is absent, add the service provider and any aliases manually to config/app.php (or bootstrap/providers.php on Laravel 11+).
• Run php artisan vendor:publish --provider="<Vendor>\\<Package>\\<Package>ServiceProvider" to see which config, migration, and view tags exist. If the package ships migrations, run php artisan migrate before touching the API.
• Read the service provider first. In a 1.0.0 package the provider is the most reliable map of what is bound into the container, which singletons exist, and which config keys are actually read. Then skim the package's tests, if any — they encode the intended usage better than an early README.
• First use case: wire the package into a single, low-risk read path (a controller or an artisan command) behind a feature flag. Exercise the happy path plus one failure mode (bad credentials, missing config, unreachable upstream) before rolling it into anything queued or scheduled.

Implementation Patterns

• Adapter boundary. Bind the package's client/manager behind your own interface in a dedicated service provider and resolve it from the container. This is the single highest-value pattern for a 1.0.0 dependency: it lets you swap or wrap the package without rewriting call sites when the API shifts in 1.1.
• Config, not constructor args. Drive behaviour through config/<package>.php and environment variables so staging and production differ without code changes. Keep the published config in version control and reference env keys in .env.example.
• Fakes in tests. If the package ships a fake or an interface you can bind, use it in tests/ rather than hitting the network. Where no fake exists, write a thin test double around your adapter — this also documents what you actually depend on.
• Queue and schedule integration. For anything slow (HTTP calls, file processing), wrap the call in a job with an explicit $timeout and $tries, and use retryUntil/backoff rather than the package's defaults. Package-level retry logic and Laravel's queue retries compound — pick one layer to own it.
• Events over polling. If the package dispatches events, listen and react rather than polling the package's state inside a request cycle. Register listeners in EventServiceProvider/AppServiceProvider so the coupling stays visible in one place.
• Upgrade rehearsal. Because there is no prior release to compare against, treat the next tag as potentially breaking. Before adopting, add a smoke test (one feature test that exercises the main entry point) so a future composer update fails loudly instead of silently.

Gotchas and Tips

• Config caching. php artisan config:cache in deployment will freeze the package config. Any env() call made from package code outside a config file returns null in production — always read config values through config(), never env(), in your own integration code.
• Auto-discovery staleness. After adding or removing the package, run php artisan package:discover (or composer dump-autoload) — cached manifests are a common cause of "class not found" on a package that is clearly installed.
• No deprecation policy yet. A first release has no documented deprecation window or BC promise. Read the changelog for each subsequent tag and check the diff of the service provider and public classes rather than trusting the version bump.
• Publishing overwrites. Re-running vendor:publish without --force leaves stale files in place, and with --force it clobbers your edits. Diff published config against the package's copy on each upgrade; --force in local only.
• Extension points to prefer: container bindings, config keys, and dispatched events. Avoid subclassing the package's concrete classes or editing vendor files — those are the first things to break in a patch release.
• Debugging. When behaviour seems inexplicable, check bind order in the container (your provider must register after the package's if you are overriding bindings), then whether a cached config or cached manifest is in play. php artisan about and php artisan tinker (app()->bound(...), config('package.key')) resolve most integration questions faster than reading the README.
• Vendor support posture. With a single Initial release entry and no issue history, budget for reading source on edge cases and keep the adapter boundary thin enough to fork or replace if maintenance stalls.