Getting Started

Install with Composer: composer require vendor/package. Version 1.0.0 is the first stable release and targets Laravel 12.
Laravel 12 package discovery should register the service provider automatically. If it does not, add the provider to bootstrap/providers.php.
Publish any package config/assets immediately:
```
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
```
Check the package README for publish tags if the provider path differs.
Review config/package.php and any required .env keys before first use.
First use case: resolve the package’s main class from the container or facade in a simple controller or artisan command, then run a smoke test. This confirms discovery, config, and credentials before integrating deeper.

Implementation Patterns

Prefer constructor injection of the package contract/manager in services, jobs, and commands. Use the facade only where brevity is more valuable than explicitness, such as small controllers.
Keep package configuration environment-driven. Publish the config file, commit it, and use .env for secrets and per-environment values.
For long-running or external operations, push work onto queues and use the package’s events/jobs where available. This keeps request latency predictable.
Bind package interfaces to test doubles in tests. Laravel 12’s container and testing helpers make this straightforward; use RefreshDatabase if the package ships migrations.
Integrate through Laravel’s standard extension points: service provider bindings, facades, macros, custom drivers, and events. Avoid reaching into package internals.
Add a small feature test that exercises the package end-to-end. This is especially useful after upgrading Laravel or changing config.

Laravel 12 requires PHP 8.2+. Confirm the runtime and CI matrix match before adopting 1.0.0.
Since 1.0.0 is the first stable release, there are no documented breaking changes or deprecations from a prior version. Future upgrades should still be reviewed against the changelog.
After publishing config or changing .env, run php artisan config:clear. In production, rebuild caches deliberately with php artisan config:cache.
If the package does not appear, run php artisan package:discover and verify the provider is listed. Use php artisan about to inspect the resolved environment.
Do not edit files in vendor/. Publish configuration and extend via bindings, macros, or custom implementations.
Watch for singleton state under Octane or long-running workers. If the package holds request-specific state, reset or rebind it in a middleware or worker listener.
Debug by resolving the package class directly from the container and dumping the instance, then checking provider registration and config values. Most day-to-day issues at this stage are discovery, config cache, or missing environment variables.