Getting Started

Minimal Setup

Install via Composer in your Laravel package project:
```
composer require --dev orchestra/workbench
```
Publish assets and config:
```
php artisan workbench:install
```
This generates stubs for:
- app/Models/User.php (customizable via TESTBENCH_USER_MODEL)
- database/factories/UserFactory.php
- routes/web.php (with /workbench routes)
- routes/console.php (for package commands)
- DatabaseSeeder.php
Serve the Workbench:
```
php artisan workbench:serve
```
Access at http://localhost:8000/workbench (default port: 8000).
First Use Case:
- Test a package command interactively:
```
php artisan workbench:test --command=your-package:command
```
- Preview API routes or middleware by visiting /workbench and triggering endpoints.

Where to Look First

Documentation: packages.tools/workbench (official docs with CLI reference).
Stub Files: config/workbench.php (customize user model, ports, or default routes).
Artisan Commands:
- workbench:serve – Launch the Workbench server.
- workbench:test – Run package-specific tests in isolation.
- workbench:devtool – Generate or update stub files.
Key Directories:
- stubs/ – Predefined templates for models, factories, and routes.
- tests/ – Example test structure for package validation.

Quick Win

For a Laravel package with a CLI command (php artisan your-package:command), use Workbench to:

Test the command in isolation:

php artisan workbench:test --command=your-package:command --args="test-arg"

Debug interactively:
- Visit /workbench and use the Artisan Runner to execute commands with real-time output.
Mock dependencies:
- Override service providers or bindings via config/workbench.php:
```
'bindings' => [
    YourPackageService::class => MockService::class,
],
```

Implementation Patterns

Core Workflows

1. Package Development Loop

graph TD
    A[Code Package Feature] --> B[Run `workbench:devtool`]
    B --> C[Update Stubs]
    C --> D[Run `workbench:serve`]
    D --> E[Test in Browser/CLI]
    E --> F[Debug via Workbench Tools]
    F --> A

2. Testing Integration

Unit Tests: Use Laravel’s built-in testing with Workbench’s isolated environment:

use Orchestra\Workbench\Tests\TestCase;

class YourPackageTest extends TestCase {
    public function test_command_output() {
        $this->artisan('your-package:command')
             ->expectsOutput('Expected output')
             ->assertExitCode(0);
    }
}

Feature Tests: Leverage Workbench’s HTTP routes:

public function test_api_endpoint() {
    $response = $this->get('/workbench/api/your-package');
    $response->assertStatus(200);
}

3. Stub Customization

Extend or replace stubs via workbench:devtool:

# Generate a custom stub (e.g., for a new model)
php artisan workbench:devtool --stub=model --name=YourModel --force

# Replace a stub file (e.g., routes)
php artisan workbench:devtool --replace=routes/web.php --path=custom/web.php

Integration Tips

With Laravel Packages

Service Provider Binding: Override package bindings in config/workbench.php:

'bindings' => [
    \YourPackage\Services\PaymentGateway::class => \Mockery\MockInterface::class,
],

Command Testing: Use workbench:test to validate CLI commands:

php artisan workbench:test --command=your-package:command --args="--option=value"

With CI/CD

Add to .github/workflows/test.yml:

jobs:
  test-package:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install
      - run: php artisan workbench:test --command=your-package:command --env=testing

With IDEs

VS Code: Add a task to run Workbench:

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Workbench: Serve",
      "type": "shell",
      "command": "php artisan workbench:serve",
      "problemMatcher": []
    }
  ]
}

PHPStorm: Map php artisan workbench:serve to a run configuration for quick access.

Advanced Patterns

Dynamic Environment Variables

Use WriteEnvironmentVariables action to inject config:

use Orchestra\Workbench\Actions\WriteEnvironmentVariables;

$action = new WriteEnvironmentVariables([
    'APP_ENV' => 'testing',
    'YOUR_PACKAGE_DEBUG' => 'true',
]);
$action->execute();

Custom Actions

Extend Workbench’s actions (e.g., for database seeding):

use Orchestra\Workbench\Actions\Action;

class SeedDatabase implements Action {
    public function execute() {
        Artisan::call('db:seed', ['--class' => 'YourPackageSeeder']);
    }
}

'actions' => [
    \App\Actions\SeedDatabase::class,
],

Multi-Package Testing

For packages with shared dependencies, use Workbench’s namespace isolation:

# Test PackageA with PackageB mocked
php artisan workbench:test --package=PackageA --mock=PackageB

Gotchas and Tips

Pitfalls

User Model Hardcoding:
- Issue: Workbench defaults to Workbench\App\Models\User. If your package uses a custom user model, set TESTBENCH_USER_MODEL in .env:
```
TESTBENCH_USER_MODEL=App\Models\CustomUser
```
- Fix: Override in config/workbench.php:
```
'user_model' => \App\Models\CustomUser::class,
```
Route Conflicts:
- Issue: Workbench registers /workbench routes, which may conflict with your package’s routes.
- Fix: Exclude routes in config/workbench.php:
```
'routes' => [
    'exclude' => ['/workbench/api/your-package'],
],
```
Stub Overwrites:
- Issue: Running workbench:devtool without --force may fail if stubs exist.
- Fix: Use --force or customize stubs via --path:
```
php artisan workbench:devtool --stub=model --name=YourModel --path=custom/YourModel.php
```
PHP Version Mismatches:
- Issue: Workbench v11+ requires PHP 8.2+. Older versions may fail.
- Fix: Pin Workbench to a compatible version in composer.json:
```
"orchestra/workbench": "^10.0"
```
Database Seeding:
- Issue: Workbench’s DatabaseSeeder may not match your package’s migrations.
- Fix: Replace the seeder stub:
```
php artisan workbench:devtool --replace=database/seeders/DatabaseSeeder.php --path=custom/DatabaseSeeder.php
```

Debugging Tips

Check Workbench Logs:

tail -f storage/logs/laravel.log | grep -i workbench

Enable Debug Mode:
```
WORKBENCH_DEBUG=true
```
Inspect Stub Files: Workbench stubs are stored in stubs/. Override them by copying to config/workbench/stubs/.
Clear Workbench Cache:
```
php artisan workbench:clear-cache
```
Test Artisan Commands: Use the Artisan Runner in /workbench to debug commands interactively.

Configuration Quirks

Port Binding:
- Workbench defaults to 8000. Change in .env:
```
WORKBENCH_PORT=9000
```
Asset Compilation:
- Workbench uses Vite. If assets fail to compile, run:
```
npm
```

Workbench Laravel Package