Weave Code
Workbench Laravel Package
orchestra/workbench
Orchestra Workbench helps you preview and interact with your Laravel package during development. Spin up a local app environment to test routes, views, migrations, and configuration while building and validating your package before release.
Workbench Companion for Laravel Packages Development
Frequently asked questions about Workbench
- How does Orchestra Workbench help with Laravel package development?
- Workbench creates an isolated Laravel environment for your package, letting you test routes, migrations, and features as if they were in a real app. It automates boilerplate (factories, migrations) via `workbench:devtool` and integrates with Testbench for PHPUnit testing, so you can iterate faster without environment flakiness.
- Can I use Workbench with Laravel 13?
- Yes, but you must use Workbench v11+ and pin it in `composer.json` (e.g., `orchestra/workbench:^11.0`). Laravel 13 requires specific Workbench versions to avoid breaking changes, so always check the [official docs](https://packages.tools/workbench) for version alignment.
- Does Workbench work with Testbench for PHPUnit tests?
- Absolutely. Workbench is designed to work seamlessly with Testbench, generating stubs (factories, migrations) and setting up a clean environment for reproducible tests. Just run `php artisan workbench:install` and start writing tests without manual setup.
- How do I avoid namespace collisions when testing multiple packages?
- Workbench enforces strict namespace isolation using `TESTBENCH_NAMESPACE` and `TESTBENCH_PACKAGE` environment variables. For multi-package setups, configure each package’s namespace in `.env.testbench` or override stubs in `config/workbench.php` to prevent conflicts.
- What if my package has custom Artisan commands that conflict with Workbench’s?
- Workbench’s commands (e.g., `workbench:install`) are prefixed to avoid clashes. If you have existing commands, either rename them or use Workbench’s `--force` flag for installation. Check `config/workbench.php` for custom command mappings if needed.
- Can I use Workbench in CI/CD pipelines?
- Workbench is lightweight (~50MB) but adds overhead, so it’s best for local development. For CI, use Testbench-only for unit tests and reserve Workbench for integration tests. Enforce `.env.testbench` in CI to match local environments and avoid drift.
- How do I customize stub templates (factories, migrations) for my package?
- Use `workbench:devtool` to generate custom stubs or override defaults in `config/workbench.php`. For example, publish stubs with `php artisan workbench:publish --tag=stubs` and modify the published files in `resources/stubs`.
- Does Workbench support Vite or Laravel Mix for frontend assets?
- Workbench supports Vite out of the box and is compatible with Laravel’s frontend tooling. If you’re using Mix, ensure your `vite.config.js` or `webpack.mix.js` is configured to work with Workbench’s isolated environment. No additional setup is needed for basic asset pipelines.
- What’s the upgrade path if I switch from Laravel 12 to 13?
- Update Workbench to v11+ and pin it in `composer.json`. Run `composer update orchestra/workbench` and check for breaking changes in the [changelog](https://github.com/orchestral/workbench/blob/9.x/CHANGELOG.md). Test your package thoroughly, as Laravel 13 introduces new features (e.g., model binding changes) that may require adjustments.
- Are there alternatives to Workbench for Laravel package testing?
- For basic testing, you can use Laravel’s built-in `php artisan serve` or Docker/Sail, but they lack Workbench’s isolation and Testbench integration. Alternatives like `laravel-shift/blueprint` focus on scaffolding, not testing. Workbench is unique for its combination of stub generation, namespace isolation, and Testbench synergy.
Weaver
How can I help you explore Laravel packages today?