Getting Started

Treat 1.0.0 as the first stable baseline. Pin it with ^1.0 and confirm the package’s Laravel/PHP version constraints before upgrading existing apps.
Install with composer require <vendor>/<package>, then check whether the service provider is auto-discovered. If not, register it manually in config/app.php.
Publish anything the package exposes: config, migrations, views, assets, or language files. Run php artisan config:clear after publishing.
Look first at the repository README, CHANGELOG.md, the package service provider, and the published config file. The 1.0.0 release note (“It’s finally launched”) is intentionally sparse, so the source and README are the real documentation.
First use case: wire the package into one small feature behind a config flag, resolve it from the container rather than instantiating it directly, and add one feature test that proves the integration works end-to-end.

Implementation Patterns

Resolve the package through Laravel’s container or its facade. Prefer constructor injection in controllers, jobs, commands, and listeners so tests can swap implementations.
Drive behavior through the published config file. Keep secrets in .env, not in committed config, and read package options via config() only at the edges of your application.
Wrap the package behind a small application-level adapter or service if it exposes a broad API. This keeps day-to-day calls readable and limits the blast radius if the package’s API changes later.
Integrate through Laravel-native seams where possible: events and listeners for side effects, queued jobs for slow work, middleware for request concerns, and validation rules for input concerns.
In tests, use the package’s fakes or mock its container binding. Assert observable outcomes—records written, jobs dispatched, events fired—rather than internal method calls.
For queued usage, make handlers idempotent and pass only serializable identifiers through jobs. Resolve the package inside the job rather than serializing the service itself.
If the package ships views or UI assets, publish them and override only what you need. Keep overrides in your app so package upgrades remain straightforward.

1.0.0 is a new major baseline: expect undocumented edge cases. Check open issues and recent commits before relying on it for critical paths.
Pin the major version and read the changelog before every minor upgrade. Semver should protect you from breaking changes, but new packages often refine behavior in early releases.
After publishing config or changing environment values, run php artisan config:clear. Config caching is a common source of “my setting is ignored” bugs.
If the provider is not auto-discovered, confirm registration order—especially if the package depends on another service provider or facade alias.
Publish migrations before running php artisan migrate. In production, review the migration and take a backup first; never assume a new package’s migration is safe to run blindly.
Debug resolution problems with app()->bound(...), dd(app(Service::class)), and Laravel’s exception page. For facade issues, verify the alias and underlying binding.
Use the package’s extension points first: published config, container bindings, events, and overridable views. Avoid editing vendor files.
Keep package calls out of your domain layer where practical. A thin adapter makes it easier to test, replace, or isolate the package later.