Inertia Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^3.1.3. The ^3.1.3 constraint is the first release line that permits illuminate/* v10, so avoid older 3.x pins if you are on Laravel 10.
• Laravel package auto-discovery should register the service provider and any facades automatically. Check bootstrap/cache/packages.php or run php artisan package:discover if bindings are missing.
• Publish package assets only if the README calls for it: php artisan vendor:publish --provider="<Vendor>\\<Package>\\<PackageServiceProvider>". Review the published config before editing; keep environment-specific values in .env.
• Look first at: the README quick-start, the package config file, the main service provider bindings, and the tests/ directory (or the package’s own test suite) for the intended public API.
• First use case: resolve the package’s primary service from the container in a controller or queued job, rather than calling static helpers directly. This confirms auto-discovery, configuration, and Laravel 10 compatibility in one pass.

Implementation Patterns

• Prefer constructor injection of the package contract/class over facades in application code. Facades are fine in thin controllers, but injection keeps jobs, listeners, and services testable.
• If the package exposes an interface, bind your preferred implementation in a dedicated application service provider. This is also the cleanest place to swap in fakes during tests.
• Keep package configuration in config/<package>.php and read it through config() only at the edges. Pass resolved values into your own services so config caching does not surprise you later.
• Wrap package calls behind a small application-level adapter when the package is used in more than a couple of places. That limits the blast radius of future major-version changes and makes it easy to assert behavior in tests.
• For queued work, inject the package service into the job’s handle() method rather than the constructor. Laravel resolves it fresh per attempt and avoids serializing non-serializable dependencies.
• Use the package inside existing Laravel seams: form requests for validation, middleware for cross-cutting concerns, events/listeners for side effects, and Artisan commands for operational tasks.
• On Laravel 10, lean on native PHP 8.1+ features (typed properties, enums, readonly, first-class callables) in your adapter code. Do not rely on docblock-only generics from older package versions; verify actual return types against the installed release.
• Add the package’s own test suite or a small integration test to your CI matrix against Laravel 10 specifically. A widened Composer constraint does not prove runtime compatibility with your application’s other dependencies.

Gotchas and Tips

• v3.1.3 is a compatibility release: it widens the Laravel constraint to allow v10. Treat it as non-breaking for the package API, but still run composer update <vendor>/<package> --with-dependencies and review the lockfile diff.
• A package allowing Laravel 10 does not mean your whole dependency graph does. If composer update still resolves Laravel 9, use composer why-not laravel/framework 10 to find the blocking package.
• Check PHP version constraints. Laravel 10 requires PHP 8.1+, and some older transitive dependencies may still pin PHP 8.0.
• If you use php artisan config:cache, re-run it after changing package config; stale cached config is a common source of “the package ignores my settings” bugs.
• Auto-discovery can be disabled or overridden in composer.json (extra.laravel.dont-discover). If the package’s facade is not found, verify discovery before adding manual provider registration.
• For debugging, start with php artisan about, php artisan package:discover -v, the Laravel log, and Telescope (if installed). Enable package-specific debug logging only in local environments.
• Extension points usually include container bindings, config-driven drivers, macros, and events. Prefer these over subclassing package internals; internals are the most likely thing to change in the next major release.
• Pin the package version in production (~3.1.3 or a lockfile) and keep a short upgrade note for the first Laravel 10 deployment: confirm auto-discovery, clear cached config, and run the application test suite against the new constraint.