Weave Code
Workbench Laravel Package
orchestra/workbench
Orchestra Workbench helps you preview and interact with your Laravel package during development by providing a local “workbench” app environment. Ideal for building, testing, and iterating on packages with a real Laravel instance.
Workbench Companion for Laravel Packages Development
Frequently asked questions about Workbench
- How do I install Orchestra Workbench for Laravel package development?
- Install via Composer with `composer require orchestra/workbench --dev`. Then run `php artisan workbench:install` to set up the sandbox environment. The package integrates directly with Laravel’s service providers and artisan commands, so no additional configuration is needed for basic usage.
- Does Workbench support Laravel 13, or is it limited to older versions?
- Workbench is actively maintained for Laravel 10–13, including full support for Laravel 13. Check the [official docs](https://packages.tools/workbench) for version-specific setup instructions, as newer Laravel releases may require minor adjustments to stub files or configurations.
- Can I customize Workbench’s default Laravel setup (e.g., user model, database, or testing environment)?
- Yes, Workbench allows overriding defaults via `.env` variables or custom configuration files. For example, set `WORKBENCH_USER_MODEL` to point to your package’s user model. The [documentation](https://packages.tools/workbench) outlines all configurable options, including database connections and testing stubs.
- Will Workbench slow down my package development workflow, or is it lightweight?
- Workbench is designed to be lightweight, focusing only on package-specific testing and previewing. It avoids bloat by leveraging Laravel’s existing infrastructure (e.g., service providers, migrations) and doesn’t introduce unnecessary overhead. For large packages, ensure your CI/CD pipeline caches dependencies to minimize setup time.
- How do I integrate Workbench into GitHub Actions or other CI systems for automated testing?
- Add `php artisan workbench:test` to your CI pipeline to run package-specific tests in isolation. Workbench generates a clean Laravel instance per test run, so you can use it as a gate in your workflow. Example: `php artisan workbench:install && php artisan workbench:test --env=testing`.
- Does Workbench work with Pest or only PHPUnit for testing?
- Workbench integrates seamlessly with Laravel’s testing tools, including both PHPUnit and Pest. It generates a `phpunit.xml` or `pest.php` configuration tailored to your package’s needs. Just ensure your test files are placed in the correct directory (e.g., `tests/Feature` or `tests/Unit`).
- What if my package requires custom Artisan commands or migrations during development?
- Workbench supports custom Artisan commands and migrations out of the box. Publish your package’s migrations or commands using Laravel’s `publishes` array in the service provider, and Workbench will include them in the sandbox environment. No additional setup is required beyond your package’s standard configuration.
- Are there alternatives to Workbench for Laravel package development, and why choose this one?
- Alternatives include Spatie’s package tools or custom Docker setups, but Workbench stands out for its deep Laravel integration, zero external dependencies, and focus on package-specific workflows. It eliminates the need for manual environment setup while providing a real Laravel instance for testing edge cases like service providers or middleware.
- How do I handle environment-specific configurations (e.g., different databases for dev vs. testing)?
- Workbench uses Laravel’s `.env` system, so you can define environment variables like `DB_CONNECTION=sqlite` for testing or `DB_CONNECTION=mysql` for development. Override these in your package’s `workbench.php` config or via `.env.workbench` files. The sandbox resets per test run, ensuring isolation.
- What’s the best way to debug issues when Workbench behaves unexpectedly?
- Start by checking the Workbench logs (`php artisan workbench:logs`) and ensure your package’s service provider is registered in the sandbox’s `config/app.php`. If using custom stubs, verify they’re placed in `resources/stubs` and referenced correctly. The [GitHub issues](https://github.com/orchestral/workbench/issues) and [documentation](https://packages.tools/workbench) often cover common pitfalls.
Weaver
How can I help you explore Laravel packages today?