Uuid Extra Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package:^4.2

Verify PHP version compatibility (now requires PHP 8.1+) and Symfony components (e.g., symfony/console:^6.0). Check the upgrade guide for migration steps if coming from <4.2.0.

First use case: Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" to publish config files, then update your config/package.php to match the new schema (if applicable).

Implementation Patterns

Core Workflows

1. Dependency Injection: Leverage the package’s service container bindings (e.g., Vendor\Package\Contracts\ServiceInterface) via constructor injection:

   public function __construct(private ServiceInterface $service) {}
   

2. Artisan Commands: Extend existing commands by creating custom commands in app/Console/Commands and using the package’s traits (e.g., UsesPackageTraits):

   use Vendor\Package\Console\Traits\UsesPackageTraits;
   
   class CustomCommand extends Command {
       use UsesPackageTraits;
       // ...
   }
   

3. Event Listeners: Subscribe to package events (e.g., Vendor\Package\Events\JobProcessed) in EventServiceProvider:

   protected $listen = [
       'Vendor\Package\Events\JobProcessed' => [
           'App\Listeners\HandleJobEvent',
       ],
   ];
   

Integration Tips

• Configuration: Use the config('package.key') helper for runtime values. Override defaults via .env:

  PACKAGE_DRIVER=database
  

• Middleware: Attach package middleware (e.g., Vendor\Package\Http\Middleware\Authenticate) to routes:

  Route::middleware(['auth.package'])->group(function () {
      // ...
  });
  

Gotchas and Tips

Breaking Changes (4.2.0)

• PHP/Symfony Minimum: Drops support for PHP <8.1 and Symfony <6.0. Action required:
  • Update php.ini or Docker/PHP-FPM config to use PHP 8.1+.
  • Run composer update vendor/package --with-dependencies to pull compatible Symfony versions.
  • Test for UndefinedClass or RuntimeException errors related to removed Symfony components (e.g., Symfony\Component\Debug\Exception\FatalThrowableError).

Debugging

• Deprecated Features: Enable strict error reporting in php.ini (error_reporting = E_ALL) to catch deprecated method calls (e.g., @deprecated in 4.2.0).
• Logging: Use the package’s logger (\Log::channel('package')) for debug output. Configure in config/logging.php:

  'channels' => [
      'package' => [
          'driver' => 'single',
          'path' => storage_path('logs/package.log'),
          'level' => env('LOG_LEVEL', 'debug'),
      ],
  ],
  

Extension Points

• Custom Services: Implement Vendor\Package\Contracts\ServiceInterface to replace core services:

  class CustomService implements ServiceInterface {
      public function process(): void {
          // Custom logic
      }
  }
  

  Bind it in AppServiceProvider:

  $this->app->bind(
      ServiceInterface::class,
      CustomService::class
  );
  

• Blade Directives: Extend Blade templates by registering directives in AppServiceProvider:

  Blade::directive('packageDirective', function () {
      return "<?php echo Vendor\Package\Facades\Package::directive(); ?>";
  });
  

Performance

• Caching: Utilize the package’s cache layer (e.g., Vendor\Package\Facades\Cache) for frequent operations:

  $data = Cache::remember('package_key', 60, function () {
      return $this->service->expensiveOperation();
  });
  

• Queue Workers: Offload long-running tasks to queues (e.g., Vendor\Package\Jobs\ProcessData). Configure in .env:

  QUEUE_CONNECTION=database
  

Configuration Quirks

• Environment Variables: Prefix package-specific .env keys with PACKAGE_ (e.g., PACKAGE_API_TOKEN) to avoid conflicts.
• Service Providers: Ensure the package’s PackageServiceProvider is registered in config/app.php after your custom providers if you’re overriding bindings.