Canvas Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Centric Design: Canvas is a drop-in replacement for Laravel’s make: commands, leveraging the same stubs and conventions. This ensures zero architectural disruption for Laravel applications, as it integrates via LaravelServiceProvider to override Artisan commands.
• Package-First Approach: The canvas.yaml preset system allows customization for both applications and packages, making it ideal for monorepos or modular architectures where consistency across projects is critical.
• Stub-Based Customization: The ability to override stubs (e.g., factory.stub, user-model.stub) aligns with domain-driven design (DDD) or project-specific patterns, reducing boilerplate drift.
• Laravel Version Agnosticism: Supports Laravel 11–13 (and back to 10.x) with backward-compatible stubs, ensuring long-term viability for legacy systems.

Integration Feasibility

• Low-Coupling: Installs as a dev dependency (composer require --dev orchestra/canvas) and integrates via Artisan command overrides, requiring no changes to existing codebases.
• Dual-Mode Operation:
  • Laravel Projects: Overrides php artisan make: commands automatically (via LaravelServiceProvider).
  • Standalone Packages: Uses vendor/bin/canvas for generation outside Laravel, enabling package development without a full Laravel install.
• Configuration-Driven: The canvas.yaml file centralizes namespace, path, and preset logic, making it easy to switch between Laravel and package modes or enforce team conventions.
• IDE/Tooling Compatibility: Works with PHPStorm, VSCode, and CLI tools (e.g., Laravel Shift), as it generates standard PHP files with correct namespaces and structure.

Technical Risk

Key Questions

1. Stubs vs. Custom Logic:

   • Should we extend existing stubs (e.g., add traits/interfaces) or replace them entirely for project-specific needs?
   • Example: Does user-model.stub need Sanctum/Passport integration by default?

2. Package vs. Application Workflow:

   • Will teams primarily use Canvas for packages (standalone mode) or Laravel applications (Artisan override mode)?
   • Impact: canvas.yaml presets differ significantly between modes.

3. IDE Integration:

   • Should we add VSCode/PHPStorm snippets to complement Canvas-generated files (e.g., for quick edits)?
   • Tradeoff: Adds maintenance but improves DX.

4. Legacy Codebase:

   • How will Canvas handle existing, non-standard files (e.g., manually created controllers)?
   • Solution: Use canvas.yaml to enforce new conventions while grandfathering old files.

5. Testing Strategy:

   • Should we generate test files (e.g., make:test) with Canvas or use a separate tool (e.g., PestPHP)?
   • Rationale: Avoid mixing scaffolding tools to prevent confusion.

6. Rollout Phasing:

   • Should we pilot Canvas in one team/module (e.g., auth package) before full adoption?
   • Risk: Inconsistent stubs across teams if not standardized early.

7. Custom Commands:

   • Are there project-specific file types (e.g., make:graphql-schema) that should be added to Canvas?
   • Approach: Fork Canvas or submit PRs to the community.

Integration Approach

Stack Fit

• Primary Use Case: Laravel 11–13 applications and Laravel-compatible packages (e.g., Spatie, Orchestra packages).

• Secondary Use Case: PHP 8.4+ projects that need Laravel-like scaffolding without full Laravel (e.g., API platforms using Lumen or standalone PHP).

• Compatibility Matrix:

  Component	Supported Versions	Notes
  Laravel Framework	11.x, 12.x, 13.x	Tested via CI; stubs may lag minor releases.
  PHP	8.4+, 8.5	PHP 8.5+ features (e.g., enums) require Canvas v10.1.1+.
  Composer	2.5+	Required for canvas.yaml and dependency resolution.
  Database Drivers	MySQL, PostgreSQL, SQLite	Migration stubs are driver-agnostic but may need customization for niche DBs.
  Testing Frameworks	PestPHP, PHPUnit	Test stubs are framework-agnostic but assume PHPUnit by default.

• Toolchain Synergy:

  • Laravel Shift: Use Canvas for initial scaffolding, then Shift for refactoring (e.g., moving files to src/).
  • PHPStan: Validate generated files against custom rules (e.g., namespace consistency).
  • GitHub Actions: Automate stub updates or file generation in CI (e.g., on git push).

Migration Path

1. Assessment Phase:

   • Audit existing make: command usage (e.g., make:controller, make:migration) via Git history or developer surveys.
   • Identify custom stubs/templates in use (e.g., app/Stubs/) that may conflict with Canvas.

2. Pilot Phase:

   • Install Canvas in a staging environment:

     composer require --dev orchestra/canvas
     vendor/bin/canvas preset laravel
     

   • Test critical workflows (e.g., CRUD generation, package development) and compare output to manual files.
   • Validate canvas.yaml presets against team conventions (e.g., App\Modules\* namespaces).

3. Integration Phase:

   • Option A (Laravel Projects): Enable Artisan override by publishing the LaravelServiceProvider:

     php artisan vendor:publish --provider="Orchestra\Canvas\LaravelServiceProvider"
     

   • Option B (Packages): Use vendor/bin/canvas directly in package development workflows.
   • Customize Stub: Override defaults (e.g., resources/stubs/model.stub) for project-specific logic.

4. Adoption Phase:

   • Document: Create a CONTRIBUTING.md section or wiki page for Canvas usage (e.g., "How to Generate a Model with Canvas").
   • Train: Run a 30-minute workshop on canvas.yaml customization and common commands.
   • Enforce: Add CI checks (e.g., fail builds if canvas.yaml is missing or invalid).

5. Optimization Phase:

   • Benchmark: Measure time saved (e.g., "Controllers now generated in 0.5s vs. 2s manually").
   • Feedback Loop: Collect stub requests (e.g., "Add make:graphql-mutation") and prioritize community contributions.

Compatibility

• Artisan Command Conflicts:
  • Canvas overrides Laravel’s make: commands. If other