Canvas Core Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require orchestra/canvas-core
   

   Publish the configuration file (if needed):

   php artisan vendor:publish --provider="Orchestra\Canvas\Core\CanvasServiceProvider" --tag="config"
   

2. First Use Case: Generate a basic model with migrations, factory, and tests:

   php artisan canvas:generate model User --with=migration,factory,test
   

   • Check config/canvas.php for available presets and options.

3. Where to Look First:

   • Documentation: Canvas Core Docs (if available).
   • Presets: Explore config/canvas.php under the presets key for built-in generators.
   • Customization: Review app/Canvas/ (auto-generated) for blueprints and generators.

Implementation Patterns

Core Workflows

1. Standardized Generation: Use presets to enforce team conventions:

   php artisan canvas:generate model Post --preset=api
   

   • Presets (e.g., api, admin) bundle related generators (e.g., model + controller + migration + API resource).

2. Custom Blueprints: Extend existing generators by creating custom blueprints:

   // app/Canvas/Blueprints/ModelBlueprint.php
   namespace App\Canvas\Blueprints;
   
   use Orchestra\Canvas\Core\Blueprints\ModelBlueprint as BaseModelBlueprint;
   
   class ModelBlueprint extends BaseModelBlueprint
   {
       protected $customProperties = [
           'softDeletes' => true,
           'timestamps' => true,
       ];
   }
   

3. Dynamic Generation: Use actions (from orchestra/workbench) to conditionally generate code:

   // app/Canvas/Actions/GenerateWithPolicy.php
   namespace App\Canvas\Actions;
   
   use Orchestra\Workbench\Actions\Action;
   
   class GenerateWithPolicy extends Action
   {
       public function handle()
       {
           $this->call('canvas:generate policy', ['model' => $this->argument('model')]);
       }
   }
   

4. Integration with Artisan: Create custom commands that leverage Canvas:

   // app/Console/Commands/GenerateModule.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\GeneratorCommand;
   use Orchestra\Canvas\Core\Canvas;
   
   class GenerateModule extends GeneratorCommand
   {
       protected $signature = 'canvas:module {name}';
       protected $description = 'Generate a full module with Canvas';
   
       public function handle()
       {
           $canvas = app(Canvas::class);
           $canvas->generate([
               'model' => $this->argument('name'),
               'with' => ['migration', 'factory', 'test', 'controller', 'policy'],
           ]);
       }
   }
   

Best Practices

• Modularize Blueprints: Group blueprints by feature (e.g., app/Canvas/Blueprints/Auth/, app/Canvas/Blueprints/API/).
• Use Presets for Teams: Define presets in config/canvas.php to standardize workflows across developers.
• Leverage Actions: Chain actions (e.g., generate model → run migrations → seed data) for complex workflows.
• Test Generators: Write unit tests for custom blueprints to ensure consistency.

Gotchas and Tips

Common Pitfalls

1. Configuration Overrides:

   • If generators is set to null in config/canvas.php, the package may fail silently. Ensure it’s an array:

     'generators' => [
         'model' => Orchestra\Canvas\Core\Generators\ModelGenerator::class,
         // ...
     ],
     

2. Path Conflicts:

   • Custom blueprints must reside in app/Canvas/Blueprints/ or be registered in the service provider. Misplaced blueprints will throw ClassNotFound errors.

3. Deprecated Methods:

   • Avoid possibleModelsUsingCanvas() (soft-deprecated in v10.1.1). Use Laravel’s native possibleModels() instead.

4. PHP Attributes:

   • Canvas uses PHP attributes (since v8.10.1). Ensure your project supports PHP 8.0+ and attributes are enabled in composer.json:

     "config": {
         "platform-check": false,
         "preferred-install": "dist"
     }
     

5. Migration Generator:

   • If using Illuminate\Console\MigrationGeneratorCommand, ensure your custom generators extend Orchestra\Canvas\Core\Generators\MigrationGenerator for compatibility.

Debugging Tips

• Enable Debug Mode: Set debug to true in config/canvas.php to log generator execution:

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

• Check Generator Events: Listen for generating and generated events to debug failures:

  // app/Providers/CanvasServiceProvider.php
  public function boot()
  {
      event(new \Orchestra\Canvas\Core\Events\Generating());
      event(new \Orchestra\Canvas\Core\Events\Generated());
  }
  

• Validate Blueprints: Use php artisan canvas:list to verify registered generators and blueprints.

Extension Points

1. Custom Generators: Extend Orchestra\Canvas\Core\Generators\Generator to create domain-specific generators:

   namespace App\Canvas\Generators;
   
   use Orchestra\Canvas\Core\Generators\Generator;
   
   class ApiResourceGenerator extends Generator
   {
       protected $type = 'api-resource';
       protected $blueprint = 'api-resource';
   }
   

2. Listeners: Implement Orchestra\Canvas\Core\Contracts\GeneratesCodeListener to hook into the generation lifecycle:

   namespace App\Canvas\Listeners;
   
   use Orchestra\Canvas\Core\Contracts\GeneratesCodeListener;
   
   class LogGeneration implements GeneratesCodeListener
   {
       public function afterCodeHasBeenGenerated($generator, $path)
       {
           \Log::info("Generated {$path} via {$generator}");
       }
   }
   

3. Preset Customization: Override default presets in config/canvas.php:

   'presets' => [
       'api' => [
           'model',
           'migration',
           'factory',
           'test',
           'controller',
           'api-resource',
       ],
   ],
   

4. Template Overrides: Override default templates by publishing assets and modifying them:

   php artisan vendor:publish --tag="canvas-views"
   

   Edit files in resources/views/vendor/canvas/ to customize generated code.