Kanuu Laravel Laravel Package

Getting Started

• Check your runtime first. v1.0.0 requires PHP 8.1+ and Laravel 9+. If you're still on PHP 7.4 or Laravel 7, upgrade your application before adding this package. Use composer why-not php 8.1 and php artisan --version to confirm.
• Install the stable release. Run composer require vendor/package:^1.0. Laravel 9 auto-discovers the service provider; manual registration in config/app.php is only needed if package discovery is disabled.
• Publish assets and config. Use php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (check the README for the exact tag). This typically publishes config/package.php and any migrations. Run php artisan migrate if migrations are included.
• Configure credentials. Add required environment variables to .env (API keys, queue connection, etc.). Clear cached config with php artisan config:clear after changes.
• First use case: validate in tinker. Resolve the package's main class from the container or call its facade inside php artisan tinker to perform a basic operation (e.g., fetch a resource, dispatch a job). This confirms credentials and configuration before wiring the package into controllers or commands.
• Why v1.0.0 matters. This is the first stable release, so the public API is now covered by semantic versioning. You can pin ^1.0 with confidence that minor updates won't break your integration.

Implementation Patterns

• Dependency injection over facades. Type-hint the package's manager or client interface in controllers, jobs, and artisan commands. This keeps your code testable and lets you swap implementations via the service container. Use the facade only for quick scripts, Blade templates, or tinker sessions.
• Configuration-driven behavior. Keep package-specific settings in config/package.php and read them with config('package.key'). Cache config in production (php artisan config:cache) but clear it after any .env or config changes.
• Queue long-running work. If the package exposes jobs or synchronous operations, dispatch them to a queue. Use Bus::batch() for bulk operations and implement failed() methods on jobs to handle package exceptions gracefully.
• Event-driven side effects. Listen for package events (e.g., PackageOperationCompleted) to decouple notifications, logging, or cache invalidation. Register listeners in EventServiceProvider or use Laravel 9's event discovery.
• Testing with fakes and mocks. If the package ships a fake or mock utility, use it in feature tests. Otherwise, bind a mock implementation of the package interface in your test's service container. Use Http::fake() if the package makes outbound HTTP calls.
• Upgrade path from 0.x. If you're coming from a pre-1.0 version, expect breaking changes beyond the PHP/Laravel support drops. Review the full changelog for renamed methods, changed config keys, and removed deprecated features. Run your test suite immediately after upgrading.

Gotchas and Tips

• Breaking changes are not limited to runtime versions. Dropping PHP 7.4 and Laravel 7 is explicit, but v1.0.0 often includes API stabilisation. Check the package's upgrade guide for method signature changes, config restructuring, and removed helpers.
• Laravel 9 auto-discovery can fail silently. If the package doesn't appear to work, run php artisan package:discover and inspect bootstrap/cache/packages.php. Manually add the provider to config/app.php only if discovery is disabled.
• Never overwrite published config in production. vendor:publish will overwrite existing files if you use --force. Merge new config keys manually after upgrading. Keep your customisations in version control.
• PHP 8.1 deprecations may surface from dependencies. The package claims PHP 8.1 support, but transitive dependencies might emit deprecation warnings. After your first request, check storage/logs/laravel.log and run composer why-not php 8.1 to identify blockers.
• Debugging package calls. Enable the package's debug mode via env var if available. Wrap calls with Log::debug() and use Laravel Telescope to inspect jobs, events, and HTTP requests triggered by the package.
• Use extension points instead of forking. Many packages allow custom implementations via interfaces. Bind your own class in a service provider: $this->app->bind(PackageInterface::class, CustomImplementation::class). This keeps you on the upgrade path.
• Pin to ^1.0 for production. Since this is the first stable release, avoid dev-main or unconstrained versions. Monitor the package's releases for security patches and minor updates.