Getting Started

Minimal Steps to Begin

Installation:
```
composer require --dev orchestra/workbench
php artisan workbench:install
```
- This generates a workbench directory with stubs for routes, migrations, and config.
First Use Case:
- Serve the Workbench:
```
php artisan workbench:serve
```
  - Access the Workbench at http://localhost:8000 to preview your package’s routes, views, and configuration in isolation.
Key Files to Review:
- workbench/testbench.yaml: Configuration for Workbench (e.g., Laravel version, package namespace).
- workbench/routes/web.stub: Stub for package routes.
- workbench/database/migrations/: Migrations for testing database interactions.
- workbench/app/Models/User.php: Default user model (customizable via TESTBENCH_USER_MODEL).
Quick Test:
- Register a route in your package’s routes/web.php:
```
Route::get('/test', function () {
    return 'Package works!';
});
```
- Run php artisan workbench:serve and visit http://localhost:8000/test.

Implementation Patterns

Core Workflows

1. Package Development Loop

Iterate Locally:
```
php artisan workbench:serve
```
- Use the Workbench to test routes, middleware, and CLI commands in a real Laravel environment.
Update Stubs:
```
php artisan workbench:devtool
```
- Regenerates stubs (e.g., routes/web.stub, app/Models/User.php) based on your package’s configuration.

2. Testing Integration

Run Tests in Workbench:
```
php artisan workbench:test
```
- Executes tests in a fresh Workbench environment, ensuring your package works as expected.
Customize Testbench: Modify workbench/testbench.yaml to:
```
packages:
    - vendor/package-name
```
- Override Laravel version or add environment variables.

3. Configuration Management

Environment Variables: Use Orchestra\Workbench\Actions\WriteEnvironmentVariables to dynamically set .env values:

use Orchestra\Workbench\Actions\WriteEnvironmentVariables;

WriteEnvironmentVariables::run([
    'APP_ENV' => 'testing',
    'DB_CONNECTION' => 'sqlite',
]);

Stub Replacement: Replace placeholders in stub files (e.g., routes/web.stub) using:

use Orchestra\Workbench\StubRegistrar;

StubRegistrar::replaceInFile(
    'workbench/routes/web.stub',
    '{{ PACKAGE_NAMESPACE }}',
    'Your\Package'
);

4. CI/CD Integration

Add to .github/workflows/test.yml:

- name: Test Package with Workbench
  run: php artisan workbench:test

Use workbench:test as a gatekeeper to ensure package compatibility before merging.

Integration Tips

With Laravel Packages

Publish Assets: If your package publishes assets (e.g., views, configs), ensure they’re included in the Workbench stubs:

// In your package's ServiceProvider
if ($this->app->environment('workbench')) {
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'package');
}

Middleware Testing: Register middleware in workbench/app/Http/Kernel.php to test package middleware:
```
protected $middleware = [
    \Your\Package\Middleware\YourMiddleware::class,
];
```

With Testbench

Custom Factories: Override the default UserFactory in workbench/database/factories/UserFactory.php:

namespace Database\Factories;

use Illuminate\Database\Eloquent\Factories\Factory;
use Orchestra\Workbench\App\Models\User;

class UserFactory extends Factory
{
    protected $model = User::class;

    public function definition()
    {
        return [
            'name' => 'Test User',
            'email' => 'test@example.com',
        ];
    }
}

Database Testing: Use Workbench’s SQLite setup for fast, isolated tests:

public function test_package_feature()
{
    $user = User::factory()->create();
    $response = $this->actingAs($user)->get('/test');
    $response->assertStatus(200);
}

With Artisan Commands

Test CLI Commands: Run commands directly in Workbench:

php artisan workbench:serve --command=your:command

Or test in a test case:

$this->artisan('your:command')
     ->expectsQuestion('Confirm?', 'yes')
     ->assertExitCode(0);

Gotchas and Tips

Pitfalls

User Model Hardcoding:
- Issue: Workbench previously hardcoded Workbench\App\Models\User. If your package uses a custom user model, set the TESTBENCH_USER_MODEL env variable:
```
TESTBENCH_USER_MODEL=App\Models\CustomUser php artisan workbench:serve
```
- Fix: Updated in v9.15.0+ to resolve from TESTBENCH_USER_MODEL.
Stub File Conflicts:
- Issue: Manually editing stub files (e.g., routes/web.stub) can cause conflicts when regenerating with workbench:devtool.
- Fix: Use StubRegistrar::replaceInFile() for dynamic updates instead of manual edits.
Route Registration Timing:
- Issue: Routes defined in workbench/routes/web.stub may not load if the package’s service provider isn’t registered early.
- Fix: Ensure your package’s register() method runs in Workbench by checking the environment:
```
if ($this->app->environment('workbench')) {
    $this->app->register(\Your\Package\ServiceProvider::class);
}
```
Database Migrations:
- Issue: Running php artisan migrate in Workbench may fail if migrations depend on package-specific tables not included in stubs.
- Fix: Include necessary migrations in workbench/database/migrations/ or use SQLite for testing.
Vite Assets:
- Issue: If your package uses Vite, Workbench may not compile assets automatically.
- Fix: Run npm run dev or npm run build separately, or configure Workbench’s Vite setup in workbench/vite.config.js.

Debugging Tips

Check Workbench Logs:
- Enable debug mode in workbench/.env:
```
APP_DEBUG=true
```
- View logs at storage/logs/laravel.log.
Inspect Stub Generation:
- Run php artisan workbench:devtool --verbose to see which stubs are being generated/updated.
Testbench Configuration:
- Validate workbench/testbench.yaml for typos or incorrect package paths. Example:
```
packages:
    - vendor/your-package
```

Environment Variables:

Override variables in .env or via command line:

TESTBENCH_PACKAGE_NAMESPACE=Your\Package php artisan workbench:serve

Middleware Debugging:
- Disable middleware temporarily in workbench/app/Http/Kernel.php to isolate issues:
```
protected $middleware = [];
```

Extension Points

Custom Actions:

Extend Workbench by creating custom actions (e.g., Orchestra\Workbench\Actions\YourAction). Example:

namespace Orchestra\Workbench\Actions;

class YourAction
{
    public static function run()
    {
        // Custom logic (e.g., seed test data)
        \Your\Package\Models\TestModel::factory()->create();
    }
}

Call actions in workbench/app/Console/Kernel.php:

protected function commands()
{
    $this->load(__DIR__.'/Commands');
    YourAction::run();
}

Dynamic Stub Replacement:

Use StubRegistrar to inject package-specific values into stubs:

use Orchestra\Workbench\StubRegistrar;

StubRegistrar::replaceInFile(
    'workbench/routes/web.stub',
    '{{ PACKAGE_PREFIX }}',
    'your-package'
);

Custom Testbench Commands:

Add commands to workbench/app/Console/Kernel.php:

protected $commands = [
    \Your\Package\Console\YourCommand::class,
];

Integration with Orchestra/Sidekick:
- Use orchestra/sidekick for advanced package development (

Workbench Laravel Package