Custom Make Command Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: This package extends Laravel’s Artisan CLI by adding custom make: commands (e.g., make:controller, make:model, etc.) with predefined templates or configurations. It fits well in projects requiring standardized scaffolding (e.g., monorepos, design systems, or teams enforcing boilerplate patterns).
• Leverage Points:
  • Template Customization: Overrides default Laravel stubs (e.g., adding middleware, traits, or annotations).
  • Command Extensibility: Allows adding domain-specific commands (e.g., make:api-resource, make:job-with-retry).
  • Team Consistency: Reduces "snowflake" code by enforcing conventions via CLI.
• Anti-Patterns:
  • Overhead for Simple Projects: Adds complexity if the team doesn’t need custom scaffolding.
  • Stub Management: Custom templates require maintenance (e.g., syncing with Laravel updates).

Integration Feasibility

• Core Compatibility: Works with Laravel 8+ (PHP 8.0+). Minimal risk if using supported versions.
• Dependencies:
  • Relies on Laravel’s Artisan system (no external PHP dependencies).
  • Custom stubs must be stored in resources/stubs/ (or configurable path).
• Testing:
  • Unit Tests: Commands can be tested via Artisan::call().
  • Integration Tests: Verify stubs generate expected files (e.g., assertFileExists(), assertStringContainsFile()).

Technical Risk

Key Questions

1. Why Custom Stubs?
   • Are there recurring patterns (e.g., API resources with DTOs, jobs with queues)?
   • Does the team lack a shared IDE template system (e.g., VS Code snippets)?
2. Maintenance Burden
   • Who owns updating stubs when Laravel changes (e.g., new route model binding syntax)?
3. Alternatives
   • Could Laravel’s built-in make: commands + IDE templates suffice?
   • Is Laravel Shift or Laravel Jetstream a better fit for scaffolding?
4. Scalability
   • Will this be used across multiple repos? Consider a shared package (e.g., Git submodule or Composer package).
5. CI/CD Impact
   • Should stubs be validated in CI (e.g., "generated files match expected structure")?

Integration Approach

Stack Fit

• Best For:
  • Laravel Monorepos: Enforce consistent scaffolding across microservices.
  • Design Systems: Generate UI components with shared props/interfaces.
  • Legacy Refactoring: Standardize old codebases (e.g., add middleware to existing controllers).
• Less Ideal For:
  • One-off Projects: Overkill if no scaffolding needs exist.
  • Non-Laravel PHP: Not applicable outside the Laravel ecosystem.

Migration Path

1. Assessment Phase:
   • Audit existing make: usage (php artisan list --format=table | grep make).
   • Identify top 3–5 custom templates needed (e.g., API controllers, jobs).
2. Pilot Implementation:
   • Start with one custom command (e.g., make:api-controller).
   • Store stubs in resources/stubs/custom/ and update composer.json:

     "extra": {
       "laravel": {
         "stubs": "resources/stubs/custom"
       }
     }
     

3. Gradual Rollout:
   • Replace IDE snippets with CLI commands for team adoption.
   • Deprecate old templates via deprecation warnings in stubs.
4. Documentation:
   • Add a CONTRIBUTING.md with stub update guidelines.
   • Example: php artisan make:custom-command --help.

Compatibility

• Laravel Versions:
  • Test against LTS versions (e.g., 10.x, 11.x) before upgrading.
  • Use laravel/framework version constraints in composer.json.
• PHP Extensions:
  • No additional extensions required (pure PHP).
• Tooling:
  • IDE Support: Ensure stubs work with Laravel IDE Helper (e.g., barryvdh/laravel-ide-helper).
  • CI: Add a step to verify stubs (e.g., php artisan make:model TestModel && git diff --exit-code).

Sequencing

1. Phase 1: Core Commands (2–4 weeks)
   • Implement 3–5 high-impact commands (e.g., make:api-resource, make:job).
   • Add to team’s aliases in .bashrc/.zshrc:

     alias makec="php artisan make:custom-command"
     

2. Phase 2: Validation (1 week)
   • Run generated code through static analysis (e.g., PestPHP, PHPStan).
   • Add a pre-commit hook to lint generated files.
3. Phase 3: Expansion (Ongoing)
   • Add commands for testing (e.g., make:feature-test), migrations, or policies.
   • Explore dynamic stubs (e.g., make:controller --with-validation).

Operational Impact

Maintenance

• Stub Updates:
  • Process: Treat stubs like code—review changes via PRs.
  • Tools: Use git diff to track stub modifications; automate updates with a script:

    # Example: Sync stubs from a shared repo
    git submodule update --init --recursive
    

• Command Deprecation:
  • Add warnings in stubs (e.g., // DEPRECATED: Use make:api-resource instead).
  • Use Laravel’s deprecation container for runtime warnings.

Support

• Onboarding:
  • Documentation: Record a Loom video showing make: workflows.
  • Cheat Sheet: List all custom commands with examples:

    ```bash
    # Generate an API resource with FormRequest validation
    php artisan make:api-resource Post --with-validation
    

• Troubleshooting:
  • Common issues:
    • Stub not found: Verify extra.laravel.stubs path in composer.json.
    • Permission errors: Ensure storage/ is writable (chmod -R 775 storage).
  • Debugging: Add --verbose to commands or log stub paths:

    // In CustomMakeCommand.php
    $this->info("Using stub: " . $this->getStubPath());
    

Scaling

• Multi-Repo Sync:
  • Option 1: Shared Composer package (publish to GitHub Packages).
  • Option 2: Git submodule for stubs.
• Performance:
  • Stub Loading: Minimal impact (cached by Laravel).
  • Large Teams: Consider parallel command execution (e.g., make:model User Post --parallel).
• Customization Limits:
  • Dynamic Templates: Use replace() in stubs for dynamic values:

    {% for trait in traits %}
    use {{ trait }};
    {% endfor %}
    

Failure Modes

Ramp-Up

• Training:
  • Workshop: 1-hour session on customizing stubs (use php artisan make:command as a template).
  • Pair Programming: Have a TPM pair with devs to create their first stub.
• Adoption Metrics:
  • Track usage via Artisan::call() logs or Git stats (e.g., "How many make:api-resource commands ran this