Getting Started

Install with Composer: composer require vendor/package. Laravel package auto-discovery should register the service provider automatically; if not, add it manually in config/app.php and run php artisan package:discover.
Publish any config or migrations: php artisan vendor:publish --tag=package-config and php artisan migrate. Check the package’s README or src/ServiceProvider.php for the exact publish tags.
First use case: resolve the package’s primary class from the container (constructor injection or app()), then call its main method from a simple route or artisan command. This confirms bindings, config, and dependencies are wired correctly.
Where to look first: src/ServiceProvider.php (bindings, singletons, publishes), config/package.php (defaults), and the package’s tests for real usage examples.
Since this is the initial 1.3.0 release, treat the API as usable but still stabilizing. Pin the version in composer.json (e.g., ^1.3) until you have validated an upgrade path.

Implementation Patterns

Constructor injection over facades: Inject the package’s interfaces/classes into controllers, jobs, and listeners. This keeps dependencies explicit and tests simple. Reserve facades for views or legacy code.
Config-driven behavior: Publish the config file and adjust defaults per environment. Cache config in production with php artisan config:cache; only read environment variables inside config files.
Events and listeners: Inspect src/Events for dispatched events. Hook into them for cross-cutting concerns instead of modifying vendor code. Register listeners in EventServiceProvider or use the package’s documented extension points.
Queue integration: Wrap long-running package calls in jobs and dispatch them. Ensure any package objects passed to queued jobs are serializable, or pass identifiers and re-resolve inside the job.
Testing: Use the package’s fakes if provided, or bind a mock implementation in the container during setUp(). For HTTP calls made by the package, use Laravel’s Http::fake().
Thin wrappers: Create a small service around the package’s API to isolate your domain. This makes future upgrades safer and allows swapping implementations without touching business logic.
Console workflows: If the package exposes commands, call them from your own commands using $this->call() and assert output in tests with $this->artisan().

Auto-discovery failures: If the provider isn’t registered, run php artisan package:discover and inspect bootstrap/cache/packages.php. Clear caches with php artisan optimize:clear.
Config caching: After publishing config, remember php artisan config:cache in production. Changes to .env won’t apply until you re-cache. Keep config uncached locally.
Version pinning: Pin to ^1.3 for now. As a first release, minor versions may include behavioral changes; review the changelog before upgrading.
Debugging: Use Laravel Telescope or targeted Log::debug() calls around package interactions. If the package swallows exceptions, check its config for a debug/throw option, or temporarily bind a decorator that logs and rethrows.
Extension points: Look for interfaces, macros, or extend methods in the service provider. Prefer these over subclassing vendor classes. If none exist, file an issue—initial releases often add them quickly.
Publishing assets: Publish tags are often registered only when running in console. If vendor:publish shows nothing, confirm the service provider calls publishes() and that you’re using the correct tag.
Dependency conflicts: Check composer why-not vendor/package 1.3.0 if installation fails. Initial releases may not yet support the newest Laravel or PHP versions.