Getting Started

Minimal Steps

Installation:
```
composer require --dev orchestra/canvas
```
For Laravel projects, register the service provider in config/app.php:
```
Orchestra\Canvas\LaravelServiceProvider::class,
```
This replaces Laravel’s default make: commands with Canvas-enhanced versions.
First Use Case: Generate a migration and model in one command (Laravel preset):
```
vendor/bin/canvas make:model Post -m
```
Or for a package (after setting up canvas.yaml):
```
vendor/bin/canvas make:job ProcessOrder --namespace="PackageName\Jobs"
```

Quick Preset Setup: For Laravel:

vendor/bin/canvas preset laravel

For a package (replace PackageName):

vendor/bin/canvas preset package --namespace="PackageName"

Where to Look First

canvas.yaml: Central configuration file for namespaces, paths, and stub customization.
Stub Files: Located in vendor/orchestra/canvas/stubs/, override these to modify generated files.
Command List: Run vendor/bin/canvas list to see all available commands (mirrors Laravel’s make: commands).

Implementation Patterns

Core Workflows

1. Laravel Project Scaffolding

Pattern: Use canvas.yaml to define project-wide namespaces (e.g., App\Modules\Auth).

preset: laravel
namespace: App\Modules
model:
  namespace: App\Modules\{ModuleName}

Workflow:

# Generate a module-specific model + migration
vendor/bin/canvas make:model Auth/User -m --namespace="Auth"

Integration Tip: Combine with --force to overwrite existing files during refactoring.

2. Package Development

Pattern: Leverage canvas.yaml to isolate package namespaces and paths.

preset: package
namespace: PackageName
paths:
  src: src
  resource: resources

Workflow:

# Generate a job with package-specific namespace
vendor/bin/canvas make:job ProcessPayment --namespace="PackageName\Jobs"

Integration Tip: Use composer exec canvas in package composer.json scripts for CI/CD:

"scripts": {
  "generate:tests": "canvas make:test UserTest --namespace=\"PackageName\\Tests\""
}

3. Stub Customization

Pattern: Override stubs in stubs/ directory (create if missing) to inject project-specific logic. Example: Modify model.stub to auto-add soft deletes:

<?php

namespace {{namespace}};

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class {{name}} extends Model
{
    use SoftDeletes;

    protected $dates = ['deleted_at'];
}

Workflow:
1. Copy the stub from vendor/orchestra/canvas/stubs/model.stub to stubs/model.stub.
2. Edit the stub as needed.
3. Regenerate files (Canvas will use your local stub).

4. Command Aliases

Pattern: Use --alias to create custom command shortcuts in canvas.yaml:

aliases:
  make:crud: "make:model make:migration make:controller make:resource"

Workflow:
```
vendor/bin/canvas make:crud Post
```
Expands to 4 commands automatically.

5. CI/CD Integration

Pattern: Use Canvas in GitHub Actions to enforce scaffolding standards:

# .github/workflows/scaffolding.yml
jobs:
  scaffold:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: composer exec canvas make:test UserTest --namespace="App\\Tests"

Pro Tips

Dry Runs: Use --dry-run to preview changes without writing files:
```
vendor/bin/canvas make:model Post -m --dry-run
```

Batch Generation: Chain commands with && for multi-step scaffolding:

vendor/bin/canvas make:model Post -m && vendor/bin/canvas make:controller PostController --resource

Laravel Integration: After installing the service provider, use php artisan make:model directly—Canvas overrides the default behavior.

Gotchas and Tips

Pitfalls

Namespace Conflicts:
- Issue: Generated files may use incorrect namespaces if canvas.yaml is misconfigured.
- Fix: Verify the namespace and paths sections in canvas.yaml. Use --namespace flag to override per command:
```
vendor/bin/canvas make:job ProcessOrder --namespace="App\Jobs"
```
Stub Overrides Not Applied:
- Issue: Local stubs in stubs/ are ignored.
- Fix: Ensure stubs are placed in the root directory (not app/ or src/). Restart the CLI if changes aren’t reflected.
Hidden Commands:
- Issue: Some commands (e.g., make:migration) may not appear in canvas list.
- Fix: Use the full Laravel-style syntax:
```
vendor/bin/canvas make:migration CreatePostsTable --create
```
Laravel Service Provider Clash:
- Issue: After installing Orchestra\Canvas\LaravelServiceProvider, default make: commands may behave unexpectedly.
- Fix: Run composer dump-autoload or restart your IDE/terminal. Use php artisan list to confirm Canvas commands are registered.
PHP Version Mismatch:
- Issue: Commands fail with PHP 8.5+ due to attribute syntax changes.
- Fix: Update Canvas to v10.1.1+ (released for PHP 8.5 compatibility).

Debugging

Verbose Output: Use -v or --verbose to debug command execution:
```
vendor/bin/canvas make:model Post -vv
```
Stub Debugging: Add {{ dump() }} to stubs to inspect variables during generation:
```
{{ dump() }}
namespace {{namespace}};
```
Command Resolution: Check if Canvas is overriding Laravel commands:
```
vendor/bin/canvas --version
php artisan --version
```
Ensure both point to the same Laravel version.

Extension Points

Custom Commands:
- Extend Canvas by creating a custom command class (e.g., MakeCrudCommand) and register it in canvas.yaml:
```
commands:
  make:crud: App\Console\Commands\MakeCrudCommand
```

Dynamic Stub Injection:

Use Laravel’s stubs config to load stubs from a custom path:

// config/canvas.php
'stubs' => [
    'model' => resource_path('stubs/model.stub'),
],

Preset Templates:

Create reusable presets by copying canvas.yaml and sharing them across projects. Example:

# .canvas-preset/auth.yaml
preset: package
namespace: AuthPackage
model:
  namespace: AuthPackage\Models

IDE Integration:
- Add Canvas commands to your IDE’s "Generate" menu (e.g., PhpStorm):
  - PhpStorm: Use the "Custom Script" plugin or configure vendor/bin/canvas as an external tool.

Configuration Quirks

Path Resolution: Canvas uses Illuminate\Filesystem\join_paths() for path resolution. Ensure paths in canvas.yaml are relative to the project root.
Case Sensitivity: Namespaces in canvas.yaml are case-sensitive. Use App\Models instead of app\models.
Default Values: If canvas.yaml is missing, Canvas falls back to Laravel’s defaults. Explicitly define the preset (preset: laravel or preset: package) to avoid surprises.

Performance Tips

Cache Stubs: Canvas caches stubs in vendor/orchestra/canvas/cache/. Clear the cache with:
```
vendor/bin/canvas cache:clear
```
Useful after stub modifications.
Batch Processing: For bulk generation (e.g., 10+ models), use a script to loop through commands:
```
for model in User Post Category; do
    vendor/bin/canvas make:model "$model" -m
done
```

Canvas Laravel Package