Chisel Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native: Perfect fit for Laravel ecosystems (starter kits, installers, scaffolding tools). Leverages Laravel’s service container, Artisan commands, and Prompts for a cohesive UX.
• Modular Design: Decouples question definition (user prompts) from mutations (file/dependency removal), enabling reuse across projects.
• AST-Based PHP Edits: Uses nikic/php-parser for safe, semantic PHP modifications (e.g., removing traits/interfaces), reducing risk of syntax errors compared to string-based tools.
• Section Markers: Provides a declarative way to wrap optional code (PHP/JSX) with /* @chisel-* */ comments, making mutations explicit and maintainable.

Integration Feasibility

• Low Friction: Single composer require with minimal boilerplate (e.g., chisel.php script + Artisan command).
• Composer/Artisan Integration: Works seamlessly with Laravel’s CLI ecosystem, enabling integration into post-install-cmd or custom commands.
• npm/Yarn/Pnpm Support: Auto-detects package managers for conditional dependency removal, aligning with modern frontend tooling.
• Extensibility: Supports custom question types (via collectAnswers() callbacks) and mutations (via apply()), allowing adaptation to niche use cases.

Technical Risk

• PHP Parser Dependency: Relies on nikic/php-parser for AST edits. Potential risks:
  • Version Compatibility: May need pinning if parser behavior changes (e.g., PHP 8.3+ attributes).
  • Complex Edits: Advanced PHP constructs (e.g., anonymous classes, attributes) might require custom logic.
• File System Assumptions: Assumes Unix-like paths (e.g., dirname(__DIR__)). Windows support may need adjustments.
• npm Script Detection: Auto-detection of package managers (npm, yarn, etc.) could fail in edge cases (e.g., custom setups).
• Interactive Prompts: CLI-based UX may not suit headless/CI environments without --answers flag.

Key Questions

1. Target Use Case:
   • Is this for public starter kits (e.g., Jetstream) or internal templates? Public kits need robust error handling; internal tools can tolerate more risk.
2. CI/CD Impact:
   • How will this integrate with composer create-project or custom installers? Will it run in CI, or is it user-driven?
3. PHP Version Support:
   • What’s the minimum PHP version for your projects? Chisel’s AST edits may need adjustments for older versions.
4. Frontend Tooling:
   • Are you using Vite, Laravel Mix, or another build tool? Chisel’s npm integration assumes standard setups.
5. Rollback Strategy:
   • How will users recover if a mutation accidentally deletes critical files? Version control (e.g., Git) is recommended.
6. Testing:
   • Do you have a strategy to test mutations? Chisel lacks built-in test utilities; you’ll need to mock file systems or use Docker.

Integration Approach

Stack Fit

• Laravel Ecosystem: Ideal for projects using:
  • Laravel Framework (Artisan, Prompts, service container).
  • Laravel Starters (Jetstream, Breeze, Forge).
  • Composer-Based Installers (e.g., laravel/installer).
• PHP Projects: Works with any PHP project, but Laravel-specific features (e.g., base_path()) require Laravel.
• Frontend Tooling: Supports npm/yarn/pnpm/bun for dependency management.

Migration Path

1. Pilot Project:
   • Start with a non-critical starter kit (e.g., internal template).
   • Define a chisel.php script for 1–2 optional features (e.g., queues, notifications).
2. Artisan Command:
   • Create a custom command (e.g., php artisan install:features) to render prompts and execute mutations.
3. Gradual Adoption:
   • Add more features to chisel.php incrementally.
   • Integrate with post-install-cmd in composer.json for automatic execution:

     "scripts": {
       "post-install-cmd": [
         "php artisan install:features"
       ]
     }
     

4. CI/CD Integration:
   • Use the --answers flag to automate in CI (e.g., php artisan install:features --answers='{"auth_features": ["email-verification"]}').

Compatibility

• Laravel Versions: Tested with Laravel 10+ (assumes Prompts v10+). May need adjustments for older versions.
• PHP Versions: Requires PHP 8.1+ (for nikic/php-parser compatibility).
• File System: Works on Unix-like systems; Windows support may need path adjustments (e.g., str_replace('\\', '/', ...)).
• npm/Yarn/Pnpm: Auto-detects package managers but may fail in custom setups (e.g., pnpm with workspaces).

Sequencing

1. Define Script:
   • Create chisel.php with questions and mutations.
   • Example: Disable debug tools in production:

     Chisel::script(dirname(__DIR__))
         ->questions([
             Question::confirm(
                 name: 'debug_tools',
                 label: 'Enable debug tools (Xdebug, Telescope)?',
                 default: false,
             ),
         ])
         ->selected('debug_tools', true)
             ->apply(fn (Chisel $c) => $c->php('config/app.php')->removeLinesContaining('debug'))
         ->else()
             ->apply(fn (Chisel $c) => $c->files('routes/debug.php')->delete());
     

2. Build Artisan Command:
   • Extend Illuminate\Console\Command to handle prompts and execute chisel().
3. Test Locally:
   • Run php artisan install:features interactively.
   • Test edge cases (e.g., missing files, invalid answers).
4. Integrate with Composer:
   • Add to post-install-cmd or use a post-create-project script in custom installers.
5. Document:
   • Add a CHISEL.md file to your repo explaining available features and how to customize.

Operational Impact

Maintenance

• Pros:
  • Declarative: Changes to mutations are self-documenting (e.g., removeSection('passkeys')).
  • Reusable: chisel.php can be copied across projects with minimal changes.
  • Laravel-Aligned: Uses familiar patterns (Artisan, Prompts).
• Cons:
  • Mutation Complexity: AST-based edits require understanding of PHP parser quirks.
  • Dependency Management: nikic/php-parser and laravel/prompts must stay updated.
  • Script Maintenance: If starter kits evolve, chisel.php may need updates to reflect new features.

Support

• Developer Onboarding:
  • Easy: Developers familiar with Laravel CLI will adapt quickly.
  • Hard: Non-Laravel devs may struggle with Artisan commands or PHP AST concepts.
• Troubleshooting:
  • Common Issues:
    • Missing files during mutations (handle with ->exists() checks).
    • Broken imports after trait/interface removal (test thoroughly).
    • npm script failures (ensure package manager is detected).
  • Debugging Tools:
    • Use dd($script->questions()) to inspect the script definition.
    • Mock file systems in tests (e.g., Mockery + Storage facade).
• Error Handling:
  • Chisel lacks built-in rollback; users must commit changes before running or use Git to revert.

Scaling

• Performance:
  • File Mutations: Linear with the number of files (e.g., deleting 100 files is fast; processing 10,000 may be slow).
  • npm Operations: Installing/removing packages can be resource-intensive in CI.
  • AST Parsing: PHP files with complex syntax (e.g., large classes) may slow down mutations.
• Parallelization:
  • Mutations are sequential by design. For large projects, consider batching (e.g., group file deletions).
• Distributed Systems:
  • Not applicable; Chisel is single-process. For multi-repo setups, distribute chisel.php via templates.

Failure Modes