Support Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require roberts/support
   

   Add to composer.json under require-dev if only using scaffolding tools.

2. First Use Case: Run the scaffolding command to bootstrap your project:

   composer support:scaffold
   

   This generates CI/CD pipelines, Docker configs, and static analysis tools in one command.

3. Where to Look First:

   • SCAFFOLDING.md: Detailed docs on generated files and customization.
   • src/Support/: Core traits/helpers (e.g., PackageHelper, ArrayHelper).
   • config/support.php: Package configuration (if published).

Implementation Patterns

Core Workflows

1. Package Development

• Trait Integration: Use PackageHelper for common package tasks (e.g., service provider bootstrapping):

  use Roberts\Support\Traits\PackageHelper;
  
  class MyServiceProvider extends ServiceProvider {
      use PackageHelper;
  
      public function boot() {
          $this->publishesConfig();
          $this->registerCommands();
      }
  }
  

• Configuration Publishing: Leverage publishesConfig() to auto-detect and publish config files with a single method call.

2. Application Utilities

• Array/Collection Helpers: Use ArrayHelper::dot() or CollectionHelper::groupBy() for nested data manipulation:

  use Roberts\Support\Helpers\ArrayHelper;
  
  $flattened = ArrayHelper::dot($request->all());
  

• Response Shortcuts: Use ResponseHelper::jsonError() for consistent API responses:

  use Roberts\Support\Helpers\ResponseHelper;
  
  return ResponseHelper::jsonError('Validation failed', $errors);
  

3. Testing

• Test Helpers: Use TestHelper::assertJsonStructure() to validate API responses:

  use Roberts\Support\Helpers\TestHelper;
  
  TestHelper::assertJsonStructure($response, ['data', 'meta.*']);
  

4. CI/CD Integration

• GitHub Actions: Generated workflows (run-tests.yml, phpstan.yml) include:
  • Parallel test execution.
  • PHPStan analysis with custom rules.
  • Dependency vulnerability scanning.

Integration Tips

• Laravel Packages: Extend Roberts\Support\Package base class for standardized package structures.
• Custom Commands: Use CommandHelper to scaffold artisan commands with built-in argument/option handling.
• Docker: Generated Dockerfile and cloudbuild.yaml support Cloud Run deployments out-of-the-box.

Gotchas and Tips

Pitfalls

1. Scaffolding Overwrite:

   • Running support:scaffold multiple times may overwrite existing files. Review SCAFFOLDING.md for merge strategies.
   • Fix: Backup critical files (e.g., .github/workflows/) before rerunning.

2. Trait Conflicts:

   • Avoid naming collisions with existing traits (e.g., ArrayHelper vs. Laravel’s Arrayable).
   • Fix: Use fully qualified namespaces or alias traits:

     use Roberts\Support\Helpers\ArrayHelper as SupportArrayHelper;
     

3. Docker Quirks:

   • Cloud Run-specific configs may not work for other platforms (e.g., ECS).
   • Fix: Customize docker-compose.yml or use --platform=local flag in scaffolding.

4. PHPStan Strict Rules:

   • Default PHPStan config uses strict levels (e.g., level: 8). Adjust phpstan.neon if needed:

     includes:
         - vendor/roberts/support/phpstan/level8.neon
     

Debugging

• Command Debugging: Use php artisan support:debug to inspect generated scaffolding paths and configs.
• Helper Logging: Enable debug mode in config/support.php:

  'debug' => env('SUPPORT_DEBUG', false),
  

  Logs helper method calls to storage/logs/support.log.

Extension Points

1. Custom Scaffolding Templates: Override default templates by publishing assets:

   php artisan vendor:publish --provider="Roberts\Support\SupportServiceProvider" --tag="scaffolding"
   

   Modify files in config/support/scaffolding/.

2. Adding Helpers: Extend existing helpers by creating a custom trait:

   namespace App\Support;
   
   use Roberts\Support\Traits\ArrayHelper as BaseArrayHelper;
   
   trait CustomArrayHelper {
       use BaseArrayHelper;
   
       public function customFlatten(array $array): array {
           // ...
       }
   }
   

3. CI/CD Customization: Extend generated workflows by adding steps to .github/workflows/custom.yml and referencing them in run-tests.yml:

   jobs:
     test:
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: ./vendor/bin/phpunit
         - run: ./vendor/bin/phpstan analyze --memory-limit=2G
   

Performance Tips

• Lazy-Load Helpers: Autoload helpers via composer.json to avoid runtime includes:

  "autoload": {
      "psr-4": {
          "App\\": "app/",
          "Roberts\\Support\\": "vendor/roberts/support/src/"
      }
  }
  

• Cache Config: Publish and cache the config to reduce I/O:

  $this->mergeConfigFrom(__DIR__.'/../config/support.php', 'support');
  Config::set('support', Cache::remember('support-config', now()->addHours(1), function () {
      return require __DIR__.'/../config/support.php';
  }));