Laravel Decomposer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lubusin/laravel-decomposer
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Lubusin\LaravelDecomposer\LaravelDecomposerServiceProvider"
   

2. First Command: Generate a basic report immediately:

   php artisan decomposer:report
   

   Outputs a markdown report to storage/app/public/decomposer-report.md.

3. First Use Case: Debug dependency conflicts or environment inconsistencies during onboarding or deployments. Example:

   use Lubusin\LaravelDecomposer\Facades\Decomposer;
   
   $report = Decomposer::getReport();
   dd($report['packages']['installed']); // Inspect installed packages
   

Implementation Patterns

Core Workflows

1. Dependency Inspection:

   // Check for a specific package version
   $report = Decomposer::getReport();
   $laravelVersion = $report['laravel']['version'];
   $composerPackages = $report['packages']['installed'];
   
   if (version_compare($laravelVersion, '10.0.0', '<')) {
       throw new \RuntimeException("Unsupported Laravel version");
   }
   

2. Environment Validation:

   // Validate PHP extensions
   $extensions = $report['php']['extensions'];
   if (!in_array('pdo_mysql', $extensions)) {
       throw new \RuntimeException("PDO MySQL extension required");
   }
   

3. Automated Reporting:

   • Artisan Command:

     php artisan decomposer:report --format=json --output=custom-report.json
     

   • Event Listeners:

     use Lubusin\LaravelDecomposer\Events\DecomposerGenerated;
     
     public function handle(DecomposerGenerated $event) {
         $report = $event->report;
         // Log or process report (e.g., send to monitoring)
     }
     

4. CI/CD Integration:

   # Example GitHub Actions step
   - name: Generate Decomposer Report
     run: php artisan decomposer:report --format=json > report.json
   - name: Upload Report
     uses: actions/upload-artifact@v3
     with:
       name: decomposer-report
       path: report.json
   

Integration Tips

• Custom Fields: Extend the report via config (config/decomposer.php):

  'custom_fields' => [
      'app' => [
          'name' => env('APP_NAME'),
          'env' => env('APP_ENV'),
      ],
  ],
  

• API Endpoint: Create a route to serve the report dynamically:

  Route::get('/report', function () {
      return response()->json(Decomposer::getReport());
  });
  

• Service Provider Boot: Preload reports for critical paths:

  public function boot() {
      $this->app->singleton('decomposer.report', function () {
          return Decomposer::getReport();
      });
  }
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Avoid generating reports in high-traffic routes. Cache the report if used frequently:

     $report = Cache::remember('decomposer.report', now()->addHours(1), function () {
         return Decomposer::getReport();
     });
     

   • Exclude sensitive data from reports (e.g., config('app.key')).

2. Dependency Resolution:

   • Reports may not reflect real-time composer.json changes. Run composer install first if discrepancies arise.
   • Circular dependencies in composer.json can cause infinite loops in the report. Validate your composer.json separately.

3. Environment Mismatches:

   • Reports include server-level details (e.g., phpversion(), exec('uname')). Ensure these match your deployment environment to avoid "works on my machine" issues.

4. Version Skew:

   • The package may not support future Laravel versions immediately. Check the release notes for compatibility.

Debugging

• Silent Failures: Enable verbose output for troubleshooting:

  php artisan decomposer:report --verbose
  

• Missing Data: If fields are empty, verify:
  • The DecomposerServiceProvider is registered in config/app.php.
  • No custom logic in AppServiceProvider is overriding the report.

Extension Points

1. Custom Report Formatters: Implement the Lubusin\LaravelDecomposer\Contracts\ReportFormatter interface:

   use Lubusin\LaravelDecomposer\Contracts\ReportFormatter;
   
   class CustomFormatter implements ReportFormatter {
       public function format(array $report): string {
           return "Custom: " . json_encode($report);
       }
   }
   

   Register in config/decomposer.php:

   'formatters' => [
       'custom' => \App\Services\CustomFormatter::class,
   ],
   

2. Filtering Packages: Exclude specific packages from the report:

   Decomposer::setExcludedPackages(['vendor/package-to-exclude']);
   

3. Hooks: Listen for DecomposerGenerated events to modify reports dynamically:

   event(new DecomposerGenerated($report));
   

Pro Tips

• Compare Environments: Use the JSON output to diff reports between dev/staging/prod:

  php artisan decomposer:report --format=json > prod-report.json
  

  Then compare with jq or a diff tool.

• Documentation: Embed the markdown report in your project’s README.md as a "Setup Requirements" section:

  ## Environment Requirements
  ```include storage/app/public/decomposer-report.md```
  

• Security: Restrict access to report endpoints in production:

  Route::middleware(['auth:sanctum'])->get('/report', function () {
      return Decomposer::getReport();
  });