Symfony Jira Issue Notifier Laravel Package

Getting Started

1. Installation: Add the package via Composer:

   composer require vendor/package-name
   

2. Basic Usage: Import the package facade (if applicable) or use the helper class:

   use Vendor\PackageName\Facades\PackageName; // or use Vendor\PackageName\PackageName;
   

3. First Use Case: Initialize with default or custom options:

   $result = PackageName::execute(['custom_option' => 'value']);
   

   • Check the README.md for the supported custom options section to understand available configurations.

Implementation Patterns

1. Configuration:

   • Use the config('package-name') helper to set global defaults in config/package-name.php.
   • Override defaults per execution via method parameters (e.g., PackageName::execute(['option' => 'value'])).

2. Service Provider Integration:

   • Bind the package to the Laravel container in AppServiceProvider:

     $this->app->singleton('package-name', function ($app) {
         return new \Vendor\PackageName\PackageName($app['config']['package-name']);
     });
     

3. Artisan Commands:

   • Extend the package’s CLI functionality by creating custom commands that leverage its core methods.

4. Event Listeners:

   • Listen to package-specific events (if documented) to react to lifecycle hooks (e.g., PackageName\Events\JobCompleted).

5. Testing:

   • Mock the package’s core class in PHPUnit tests:

     $this->partialMock(\Vendor\PackageName\PackageName::class, ['execute']);
     

Gotchas and Tips

1. Custom Options:

   • Pitfall: Undocumented options may cause silent failures. Always validate against the supported custom options list in the release notes.
   • Tip: Use PackageName::getSupportedOptions() (if available) to dynamically fetch valid keys:

     $validOptions = PackageName::getSupportedOptions();
     

2. Configuration Overrides:

   • Pitfall: Config values in config/package-name.php are merged with method parameters. Unexpected behavior may occur if defaults are not explicitly set.
   • Tip: Use array_merge() to debug overrides:

     $finalConfig = array_merge(config('package-name'), ['custom_option' => 'value']);
     

3. Dependency Injection:

   • Tip: Prefer constructor injection for testability:

     public function __construct(private PackageName $package) {}
     

4. Performance:

   • Tip: Cache repeated executions with the same options:

     $cacheKey = md5(serialize($options));
     return Cache::remember($cacheKey, now()->addHours(1), function () use ($options) {
         return PackageName::execute($options);
     });
     

5. Debugging:

   • Enable verbose logging by setting 'debug' => true in the config or passing ['debug' => true] to methods.
   • Check for PackageName\Exceptions\* classes for error handling.