Getting Started

Minimal Setup

Install Workbench in your package:

composer require --dev orchestra/workbench

Publish stubs (runs workbench:install):
```
php artisan workbench:install
```
- Accept defaults or customize paths (e.g., app/Workbench).
Boot the Workbench:
```
php artisan workbench:devtool
```
- Opens a browser to http://workbench.test (or your configured URL).
- Default credentials: email@example.com / password.

First Use Case: Previewing Routes/Views

Navigate to / in the Workbench to see your package’s routes/views rendered in a real Laravel context.
Use the Artisan CLI (accessible via Workbench’s terminal) to test commands:
```
php artisan your:package-command
```

Key Files to Know

config/testbench.php: Workbench/Testbench integration settings (e.g., TESTBENCH_USER_MODEL).
app/Workbench/Providers/: Stubbed service providers for your package.
database/factories/UserFactory.php: Customizable user factory for testing.
routes/web.php: Your package’s routes, auto-loaded in Workbench.

Implementation Patterns

Workflow: Local Development

Iterate on Package Code:
- Edit src/ files in your package.
- Trigger Workbench rebuild:
```
php artisan workbench:devtool --rebuild
```
Test Interactively:
- Use Workbench’s auth system to test user-specific features.
- Simulate API requests via /api routes.

Debug with Artisan:

Run package commands directly:

php artisan your:package:command --option=value

Workflow: Testbench Integration

Configure Testbench:

// In your Testbench test
$this->app->make(\Orchestra\Workbench\WorkbenchServiceProvider::class);

Leverage Workbench Stubs:
- Workbench auto-generates DatabaseSeeder, UserFactory, and routes/console.stub.
- Override defaults by publishing stubs:
```
php artisan vendor:publish --tag=workbench-stubs
```

Test with Real Environments:

Use WriteEnvironmentVariables action to inject .env vars:

use Orchestra\Workbench\Actions\WriteEnvironmentVariables;

WriteEnvironmentVariables::run([
    'APP_URL' => 'http://workbench.test',
    'DB_CONNECTION' => 'sqlite',
]);

Integration Tips

Namespace Isolation: Use ReplaceNamespaces action to ensure your package’s namespaces (e.g., Vendor\Package\) don’t clash with Workbench:
```
use Orchestra\Workbench\Actions\ReplaceNamespaces;

ReplaceNamespaces::run([
    'Vendor\Package' => 'Workbench\Package',
]);
```
Custom User Model: Set TESTBENCH_USER_MODEL in .env:
```
TESTBENCH_USER_MODEL=Workbench\Models\User
```
Stub Customization: Extend stubs by copying Workbench’s published files (e.g., app/Workbench/Providers/AppServiceProvider.php) and modifying them.

CI/CD Pattern

Reproducible Environments: Add to your CI script:

composer install --prefer-dist --no-interaction
php artisan workbench:install --quiet
php artisan workbench:devtool --no-interaction

Testbench + Workbench: Use Workbench’s DatabaseSeeder in CI:

php artisan migrate --env=testing
php artisan db:seed --class=DatabaseSeeder --env=testing

Gotchas and Tips

Pitfalls

Stub Overwrites:
- Running workbench:install replaces stub files. Back up custom stubs before updating Workbench.
- Fix: Use --keep flag or manually merge changes:
```
php artisan workbench:install --keep
```
Namespace Collisions:
- Workbench defaults to Workbench\ namespace. If your package uses similar names (e.g., WorkbenchServiceProvider), conflicts arise.
- Fix: Use ReplaceNamespaces action or rename stubs post-install.
Artisan Command Conflicts:
- Workbench registers its own commands (e.g., workbench:devtool). If your package has similarly named commands, they may override Workbench’s.
- Fix: Prefix your commands or use Orchestra\Canvas\Core\Actions to namespace them.
Database Migrations:
- Workbench’s DatabaseSeeder runs after your package’s migrations. If your seeder depends on package tables, ensure proper ordering.
- Fix: Extend the seeder:
```
// database/seeders/DatabaseSeeder.php
public function run()
{
    $this->call([
        \Vendor\Package\Database\Seeders\PackageSeeder::class,
    ]);
}
```
Environment Variables:
- Workbench’s .env may override your package’s .env.testing. Test locally with:
```
php artisan workbench:devtool --env=testing
```

Debugging Tips

Workbench Not Loading?
- Verify the WorkbenchServiceProvider is registered in config/app.php (added by workbench:install).
- Check routes/web.php for your package’s routes.

Stub Files Missing?

Ensure stubs are published:

php artisan vendor:publish --tag=workbench-stubs --force

User Factory Issues:
- Workbench’s UserFactory may not match your package’s model. Override it:
```
php artisan vendor:publish --tag=workbench-factories
```

Extension Points

Custom Actions: Extend Workbench’s actions (e.g., WriteEnvironmentVariables) by creating a service provider:

namespace Workbench\Providers;

use Orchestra\Workbench\Actions\WriteEnvironmentVariables;

class CustomActionsServiceProvider extends ServiceProvider
{
    public function boot()
    {
        WriteEnvironmentVariables::macro('custom', function ($vars) {
            // Custom logic
        });
    }
}

Dynamic Stub Generation: Override stub paths in config/testbench.php:

'stubs' => [
    'app/Providers/AppServiceProvider' => __DIR__.'/stubs/AppServiceProvider.stub',
],

Workbench as a Dependency: If your package requires Workbench for development (e.g., for a CLI tool), add it as a dev dependency and document the setup:
```
composer require --dev orchestra/workbench
```

Performance Quirks

Devtool Overhead: workbench:devtool spins up a full Laravel instance. For CI, use --no-interaction and disable queues:
```
php artisan workbench:devtool --env=testing --no-interaction --queue=disabled
```
Asset Compilation: Workbench uses Vite. If assets fail to compile, run:
```
npm install && npm run dev
```
(Ensure node_modules are included in .gitignore for CI.)

Configuration Quirks

TESTBENCH_USER_MODEL: Must be a fully qualified namespace (e.g., Workbench\Models\User). Relative paths (e.g., Models\User) fail silently.
Route Caching: Workbench routes are cached. Clear them after changes:
```
php artisan route:clear
```
Queue Workers: Workbench’s queues run in the foreground. For production-like testing, use:
```
php artisan queue:work --env=testing --once
```

Workbench Laravel Package