Translation Set Laravel Package

Getting Started

• Require ^1.2.0 on Laravel 11 projects. This is the first line with explicit Laravel 11 support and the initialization fix from #328; earlier versions may boot inconsistently under Laravel 11’s streamlined provider/bootstrap flow.
• Install with Composer and let package discovery register the service provider:

  composer require vendor/package:^1.2.0
  php artisan package:discover --ansi
  

• Publish and review configuration before first use:

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

  Check the published file in config/; keep environment-specific values in .env where the package supports it.
• Run migrations only if the package ships them:

  php artisan migrate
  

• First use case: resolve the package’s primary service from the container in a route, command, or Tinker session rather than instantiating it directly. This verifies the 1.2.0 initialization fix in the same way application code will use it:

  php artisan tinker
  >>> app(Vendor\Package\Client::class);
  

• Where to look first: vendor/vendor/package/src/ServiceProvider.php, the package config file, and the upgrade notes for 1.2.0. Run php artisan about to confirm Laravel version, cache state, and environment before debugging behavior.
• On Laravel 11, there is no app/Http/Kernel.php. If the package documents middleware or console-kernel snippets from older Laravel versions, translate them into bootstrap/app.php or the package’s own auto-registration.

Implementation Patterns

• Resolve package services through the Laravel container or the provided facade/helper. This ensures config, singleton state, and any initialization performed by the provider are applied consistently.
• Keep package configuration publishable but environment-overridable. Use config/package.php for defaults and .env for deployment-specific values; avoid editing vendor files.
• If the package integrates with HTTP middleware, register it in Laravel 11’s bootstrap/app.php:

  ->withMiddleware(function (Middleware $middleware) {
      $middleware->append(\Vendor\Package\Middleware\PackageMiddleware::class);
  })
  

  Prefer package-provided registration when available; only add manual wiring when the package documents it.
• In jobs and queued listeners, inject the package service through the constructor rather than resolving it globally at class-load time. This avoids serializing container state and keeps workers predictable after config changes.
• For testing, use the package’s fake or swap bindings in the container:

  $this->swap(Contract::class, $fake);
  

  If migrations are involved, combine with RefreshDatabase. Confirm tests run with cached config disabled, or rebuild caches in CI.
• Extension point: bind your own implementation after the package provider has registered. Use a small application service provider:

  $this->app->bind(
      \Vendor\Package\Contracts\Client::class,
      \App\Services\CustomClient::class
  );
  

  This is safer than modifying package internals and works with Laravel 11’s provider discovery.
• Deployment workflow: composer install --no-dev, then php artisan optimize or explicit config:cache / route:cache steps. Verify the package behaves correctly with cached config before promoting to production.

Gotchas and Tips

• The 1.2.0 initialization fix is the main reason to upgrade on Laravel 11. Pin >=1.2.0 and clear stale bootstrap caches after upgrading:

  php artisan optimize:clear
  composer dump-autoload
  

• If the provider is not loading, check package discovery rather than adding it manually first:

  php artisan package:discover
  

  Confirm extra.laravel.providers exists in the package’s composer.json and that bootstrap/cache/packages.php was regenerated.
• Initialization order matters. Do not resolve the package service inside another provider’s register() method before the package provider has run. Defer to boot() or use $this->app->booted(...) when integrating with application code.
• Published config wins over package defaults. If behavior seems ignored, check whether a stale config/package.php is overriding a newer default from the package.
• Laravel 11 moved console scheduling and some kernel responsibilities. If package documentation references app/Console/Kernel.php, adapt scheduling to routes/console.php and middleware to bootstrap/app.php.
• Cached configuration can freeze values that look environment-driven. After changing .env in a deployed environment, run php artisan config:clear or rebuild caches as part of release.
• Debug with Laravel’s built-ins before reaching for package internals:

  php artisan about
  php artisan config:show package
  php artisan tinker
  

  Then inspect storage/logs/laravel.log for provider or binding failures.
• Check framework and PHP constraints before upgrading. Laravel 11 support does not automatically mean older Laravel versions remain supported; verify the package’s composer.json before using the same version across mixed-version applications.