Plans Laravel Package

Getting Started

1. Confirm the runtime matrix. v1.0.0 explicitly supports Laravel 9 and 10. Check your app’s composer.json for compatible PHP and illuminate/* constraints before installing.
2. Install the package.

   composer require vendor/package
   

3. Verify discovery. Most Laravel packages auto-register via extra.laravel.providers. If the package does not, add its service provider manually in config/app.php.
4. Publish configuration and assets.

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   # or, if the package defines tags:
   php artisan vendor:publish --tag=package-config
   

5. Run migrations only if the package is database-backed.

   php artisan migrate
   

6. Look first at:
   • README.md for the public API and required env/config values
   • config/package.php after publishing
   • The package service provider for bindings, facades, and extension points
   • The package’s facade/contract classes for the intended entry point

First use case: resolve the package’s main contract from the container rather than reaching for globals:

use Vendor\Package\Contracts\PackageService;

public function __invoke(PackageService $service)
{
    return $service->handle($request->validated());
}

If the package ships a facade, use it for quick calls in controllers or Blade, but prefer constructor injection in application services and jobs.

Implementation Patterns

• Inject contracts, not concrete classes. Bind the package contract in a small application-level service provider if you need to swap implementations or decorate behavior.
• Wrap third-party calls in your own adapter. Even a thin App\Services\PackageGateway keeps package-specific types out of controllers, jobs, and tests.
• Use config for environment-specific behavior. Keep credentials and switches in config/package.php, and reference them with config('package.key') rather than calling env() at runtime.
• Queue and event integration. When dispatching jobs that use the package, ensure serializable payloads and re-resolve services inside handle() instead of storing container-bound objects on the job.
• Database-backed packages. Publish migrations once, review them, and commit them if your deployment process expects application-owned migrations. Use RefreshDatabase in tests and seed only what the package requires.
• Testing pattern. Swap the package binding for a fake or mock in the container:

  $this->mock(PackageService::class, function ($mock) {
      $mock->shouldReceive('handle')->once()->andReturn('ok');
  });
  

• Blade and UI integrations. If the package publishes views or components, prefer overriding published views in your app rather than editing vendor files.
• Octane and long-running workers. Avoid static state, memoized request data, or service singletons that retain request-specific context. Resolve per request/job where appropriate.
• Upgrade-safe integration. Keep package usage behind your adapter so future major versions only require changes in one place.

Gotchas and Tips

• Laravel 9/10 support is not the same as Laravel 8 support. Confirm PHP requirements, illuminate/support constraints, and any transitive dependencies with:

  composer why-not vendor/package
  composer show vendor/package
  

• Discovery and config caching. After install or upgrade, run:

  php artisan package:discover
  php artisan config:clear
  php artisan cache:clear
  

  In production, rebuild caches with php artisan config:cache and php artisan route:cache as appropriate.
• Do not call env() from package config at runtime. Laravel config caching will return null. Put env lookups in config/package.php only.
• Publishing can overwrite local changes. Use --force intentionally. Prefer publishing only the tags you need.
• Facade aliases can collide. If the package registers a generic alias, use the fully qualified class name or disable the alias.
• Provider order matters. If the package depends on another provider’s bindings, register it after that provider or move customization into a later boot() phase.
• Laravel 10 deprecations. Watch for removed or deprecated framework APIs if the package’s internals are older than the release notes imply. Run your test suite on both Laravel 9 and 10 if you support both.
• Debugging checklist:
  • php artisan about for environment and cache status
  • composer show vendor/package for the installed version
  • Provider register() vs boot() timing
  • Published config values vs package defaults
  • Application logs for binding resolution or migration errors
• Extension points to prefer: container bindings, published config, published views/lang files, package events/listeners, and facade replacements. Avoid modifying vendor code.
• Release-note scope. The v1.0.0 note only confirms Laravel 9/10 compatibility. Treat the package README and service provider as the source of truth for feature surface, required config, and any breaking changes not captured in the note.