Teamwork Laravel Package

Getting Started

• Verify your app meets the new floor: Laravel 8 or 9 and PHP 8.0+. The 9.0.0 release dropped Laravel 6 and 7, so composer require will fail on older skeletons.
• Check the package's composer.json constraints before upgrading: you want illuminate/* at ^8.0|^9.0 and no transitive dependency still pinned to Laravel 6/7.
• Look first at:
  1. The service provider (auto-discovered or manually registered).
  2. config/<package>.php and whether it is publishable.
  3. Any facade, helper, or artisan command exposed by the package.
• Minimal first use case:

  composer require vendor/package:^9.0
  php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
  php artisan migrate   # only if the package ships migrations
  

  Then exercise one read/write path in php artisan tinker (e.g. the package facade or a model/repository it exposes) before wiring it into application code.

Implementation Patterns

• Upgrade path from 8.x: bump the constraint, run composer update vendor/package, then run the full test suite. Pay special attention to any code that used Laravel 6/7-only APIs; the package is now built against Laravel 9 conventions.
• Service container first: resolve the package's main class via constructor injection rather than app() or static calls. This keeps it mockable and makes it easy to swap in a custom implementation.
• Facades where appropriate: if the package ships a facade, use it in controllers and Blade, but prefer injecting the underlying contract in jobs, listeners, and service classes.
• Configuration-driven setup: publish the config file and drive behaviour from .env. Keep package-specific env keys grouped and documented in .env.example.
• Queue and scheduler integration: if the package dispatches jobs or exposes scheduled work, register it in Kernel::schedule() and ensure workers are restarted on deploy (php artisan queue:restart).
• Testing pattern:

  use Vendor\Package\Facades\Package;
  
  public function test_feature(): void
  {
      Package::shouldReceive('doSomething')->once()->andReturn(true);
      // ...
  }
  

  Use RefreshDatabase when the package owns tables, and Facade::clearResolvedInstances() in tearDown if you swap bindings between tests.
• Upgrade checklist for teams: pin ^9.0, update CI matrix to Laravel 9 / PHP 8, run composer dump-autoload, php artisan package:discover, and php artisan config:clear before validating.

Gotchas and Tips

• PHP 8 requirement: Laravel 9 and this release assume PHP 8.0+. Check your Docker image, CI runner, and production PHP version before merging the upgrade.
• Auto-discovery cache: after upgrading, run php artisan package:discover (or composer dump-autoload). A stale bootstrap/cache/packages.php is a common cause of "class not found" after a version bump.
• Config cache: php artisan config:cache will freeze published package config. Use config:clear when changing env values, and never call env() outside config files.
• Migration ordering: published migrations may collide with existing tables. Review filenames and consider running them in isolation on a staging database first.
• Facade state in tests: facades cache resolved instances. If one test swaps the binding and the next does not, you can get order-dependent failures—clear resolved instances in tearDown.
• Dependency conflicts: dropping Laravel 6/7 often surfaces as a Composer conflict with another package still requiring illuminate/support ^6|^7. Use composer why-not vendor/package 9.0.0 to find the blocker.
• Queued jobs after deploy: restart workers after upgrading. Long-running workers can hold old package code in memory.
• Extension points: publishing config, views, and migrations is usually the supported customisation path. Prefer binding a custom implementation to the package's contract over editing vendor files.