Canvas Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev orchestra/canvas
   

   For Laravel projects, optionally register the service provider in config/app.php under providers:

   Orchestra\Canvas\LaravelServiceProvider::class,
   

2. Initialize Preset: Choose either:

   • Laravel preset (for applications):

     vendor/bin/canvas preset laravel
     

   • Package preset (for standalone packages):

     vendor/bin/canvas preset package --namespace="Your\Package\Namespace"
     

   This generates a canvas.yaml config file in your project root.

3. First Use Case: Generate a migration:

   vendor/bin/canvas make:migration create_users_table --create=users
   

   Or use composer exec canvas for Laravel environments:

   composer exec canvas make:model User
   

Where to Look First

• canvas.yaml: Central configuration for namespaces, paths, and stubs.
• Stub Files: Located in vendor/orchestra/canvas/stubs/. Customize these for project-specific templates.
• CLI Commands: Mirror Laravel’s make: commands but work outside Laravel installations.

Implementation Patterns

Usage Patterns

1. Laravel Integration:

   • Register LaravelServiceProvider to override Laravel’s make: commands with Canvas equivalents.
   • Use php artisan make:model seamlessly—Canvas handles the rest under the hood.

2. Package Development:

   • Generate package-specific files (e.g., make:command) without a Laravel install.
   • Configure canvas.yaml with preset: package and adjust paths (e.g., src, resources).

3. Custom Stubs:

   • Override default stubs by copying from vendor/orchestra/canvas/stubs/ to stubs/ in your project.
   • Example: Modify model.stub to auto-inject traits or interfaces.

4. Workflow Integration:

   • CRUD Generation:

     composer exec canvas make:model Post -m -r -f
     

     Creates a model, migration, resource, and factory in one command.
   • Batch Generation: Use --batch flag for bulk operations (e.g., generating multiple migrations).

5. Testing:

   • Generate test classes with:

     composer exec canvas make:test Unit/FeatureTest --unit
     

   • Configure testing.namespace in canvas.yaml for consistency.

Integration Tips

• IDE Support:

  • Add vendor/bin/canvas to your IDE’s terminal or task runner for quick access.
  • Use composer exec canvas in Laravel projects to avoid path issues.

• CI/CD:

  • Include Canvas in your CI pipeline to enforce scaffolding standards:

    # Example GitHub Actions step
    - run: composer exec canvas make:test Unit/UserTest --unit
    

• Team Onboarding:

  • Document canvas.yaml conventions in your project’s CONTRIBUTING.md.
  • Example:

    # Required for all new developers
    namespace: App\Modules\Auth
    model:
      namespace: App\Modules\Auth\Models
    

• Stub Customization:

  • Extend stubs with project-specific logic (e.g., auto-generating API resources):

    {# stubs/api-resource.stub #}
    namespace {{ namespace }};
    
    use Illuminate\Http\Resources\Json\JsonResource;
    
    class {{ class }} extends JsonResource
    {
        public function toArray($request)
        {
            return [
                'id' => $this->id,
                'name' => $this->name,
                // Add custom fields here
            ];
        }
    }
    

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • If canvas.yaml namespaces don’t match your project structure, generated files may fail to autoload.
   • Fix: Verify composer dump-autoload runs after generation.

2. Stub Overrides:

   • Custom stubs in stubs/ must match the original filename (e.g., model.stub).
   • Fix: Use canvas:publish to copy stubs to your project:

     composer exec canvas publish:stubs
     

3. Laravel Service Provider:

   • Forgetting to register LaravelServiceProvider in Laravel projects may cause commands to fall back to Laravel’s defaults.
   • Fix: Add to config/app.php:

     Orchestra\Canvas\LaravelServiceProvider::class,
     

4. Path Resolution:

   • Custom paths in canvas.yaml (e.g., paths.src) must exist or generation will fail.
   • Fix: Create directories manually or use canvas:make-dirs:

     composer exec canvas make-dirs
     

5. PHP Version Mismatches:

   • Canvas supports PHP 8.4+. Older versions may break stub rendering.
   • Fix: Update PHP or pin Canvas to a compatible version (e.g., orchestra/canvas:9.x).

Debugging

• Verbose Output: Use --verbose to debug stub rendering:

  composer exec canvas make:model User --verbose
  

• Stub Debugging: Check rendered stubs by inspecting the generated file or using:

  composer exec canvas stub:show model
  

• Command Aliases: Canvas supports Laravel’s AsCommand aliases (e.g., make:controller → make:controller). If aliases don’t work, ensure the service provider is registered.

Tips

1. Preset Management:

   • Use --namespace with preset to avoid manual edits:

     composer exec canvas preset package --namespace="Acme\Package"
     

2. Stub Versioning:

   • Commit custom stubs to version control to maintain consistency across environments.

3. Performance:

   • For large projects, generate files in bulk to reduce I/O overhead:

     composer exec canvas make:migration create_table_1 --create=table1
     composer exec canvas make:migration create_table_2 --create=table2
     

4. Laravel 11+ Features:

   • Leverage Canvas’s support for Laravel 11’s AsCommand and new stub formats (e.g., make:enum).

5. Package Discovery:

   • In Laravel packages, ensure Orchestra\Canvas\LaravelServiceProvider is in providers to auto-register commands.

6. Hidden Commands:

   • Use canvas list to see all available commands, including hidden ones like make:view.

7. Testing Integration:

   • Generate test classes with --unit or --feature flags for Laravel’s testing conventions:

     composer exec canvas make:test Unit/UserTest --unit
     

8. Migration Prefixes:

   • Configure migration.prefix in canvas.yaml to avoid conflicts in multi-module projects:

     migration:
       prefix: 'auth_'