Distributed Laravel Laravel Package

Getting Started

1. Install the package on Laravel 12 using Composer, pinning to the new major line:

   composer require <vendor>/<package>:^1.0
   

   Confirm your app meets Laravel 12’s platform requirements, typically PHP 8.2+ and laravel/framework:^12.0.

2. Let Laravel package discovery register the service provider. Verify with:

   php artisan package:discover
   php artisan about
   

3. Publish any config, migrations, or assets the package exposes. Check the package README for the exact tag or provider:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   # or
   php artisan vendor:publish --tag=package-config
   

4. Look first at the published config file, the package service provider, and the README’s quick-start example. Those three places usually reveal the intended entry point and extension points.

5. Start with a single, low-risk use case: resolve the package’s main service from the container in one controller action, command, or queued job, then validate the result in php artisan tinker before rolling it out more broadly.

Implementation Patterns

• Prefer container resolution over static calls in application code. Inject the package service or contract into constructors. Use facades only where they improve readability, such as controllers, Blade templates, or quick scripts.

• Bind contracts when the package exposes them. If the package publishes an interface, bind your own implementation or a configured implementation in AppServiceProvider rather than reaching into package internals.

• Keep configuration in config files and environment variables. Publish the package config, set values through .env, and avoid editing files under vendor/. This keeps upgrades to 1.x predictable.

• Register middleware in Laravel 12’s bootstrap/app.php. Laravel 12 no longer uses app/Http/Kernel.php by default. If the package ships middleware, append it through the withMiddleware() callback.

• Move package operations into queued jobs when they perform I/O. If the package calls external APIs, writes large files, or sends notifications, wrap the call in a job implementing ShouldQueue so failures and retries are handled by Laravel’s queue system.

• Use events and listeners for side effects. If the package dispatches events, listen for them instead of modifying package code. This is usually the cleanest extension point for logging, notifications, and cache invalidation.

• Test with fakes or container swaps. If the package provides a fake or test helper, use it. Otherwise, mock its facade with Facade::shouldReceive(...) or bind a test double into the container.

• Include package migrations and config in deployment. Run php artisan migrate --force and php artisan config:cache as part of your normal deploy pipeline. If the package ships migrations, confirm they are published or loaded correctly.

Gotchas and Tips

• Treat 1.0.0 as a stability and compatibility release. The only stated change is Laravel 12 support, so do not assume new features. Review the package changelog and upgrade guide before moving from any 0.x version.

• Laravel 12 skeleton differences matter. Providers are registered in bootstrap/providers.php, and HTTP middleware is configured in bootstrap/app.php. Package installation instructions written for older Laravel versions may reference files that no longer exist.

• Auto-discovery can fail in monorepos or custom bootstraps. If the package does not appear after installation, manually add its service provider to bootstrap/providers.php and run composer dump-autoload.

• Do not call env() from package config after caching. Once php artisan config:cache runs, env() calls outside config files can return null. Use config() and published config values instead.

• Facade aliases are not registered by default in Laravel 12. Use the fully qualified facade class, or explicitly add an alias if your codebase relies on short names.

• Debug with the standard Laravel tools first. Use composer show <vendor>/<package>, php artisan package:discover -v, php artisan tinker, and storage/logs/laravel.log to confirm the package is installed, discovered, and configured correctly.

• Extension points usually include config, contracts, events, and macros. Prefer those over subclassing package internals. If the package documents macros, use them; otherwise keep custom behavior in your own service layer.

• Pin the major version and test Laravel 12 in CI. Use ^1.0 in composer.json, and run your test suite against Laravel 12 before merging the upgrade. Because the release notes are sparse, your CI smoke tests are the best confirmation that the package behaves correctly in your application.