Getting Started

Minimal Setup

Add as a Git Submodule:

git submodule add https://github.com/CoringaWc/filament-plugin-workbench.git packages/workbench

Initialize Workbench:
```
./vendor/bin/workbench up
```
- This copies docker-compose.yml.stub and testbench.yaml.stub to your plugin root.
- Resolves the build.context dynamically to point to the Dockerfile in the submodule.
Start Development:
```
./vendor/bin/sail artisan serve
```
- Access your plugin at http://localhost:8001 (default port in stub).

First Use Case

Run Tests:
```
./vendor/bin/sail test
```
Run Linting:
```
./vendor/bin/sail lint
```
Open Shell:
```
./vendor/bin/sail shell
```

Implementation Patterns

Workflow Integration

Plugin Development Loop:

# Start environment (detached)
./vendor/bin/workbench up -d

# Run tests in watch mode
./vendor/bin/sail test --watch

# Serve the plugin
./vendor/bin/sail artisan serve

Fresh Environment:

./vendor/bin/workbench fresh  # Migrate + seed

Debugging:

./vendor/bin/workbench logs   # Tail container logs
./vendor/bin/sail shell       # Interactive shell

Key Patterns

Docker Context Resolution: The build.context in docker-compose.yml is dynamically replaced with the path to the submodule's Dockerfile (packages/workbench/docker/php). Use _fix_docker_context() to handle this during workbench up.
Provider Auto-Injection: The testbench.yaml stub includes a placeholder (# - Vendor\YourPlugin\...). Run ./vendor/bin/workbench up to auto-fill providers from composer.json under extra.laravel.providers.
Composer Scripts: The composer.json stub injects scripts like bootstrap:workbench, serve, and fresh:workbench. These are auto-generated if missing.
Playwright Integration: If your plugin uses @playwright/test, the Docker image pre-installs Chromium in a named volume (playwright-browsers). No manual setup required—just include the dependency in package.json.

Integration Tips

Custom Dockerfile: Override the Dockerfile by extending the base image in your plugin’s docker-compose.yml:

services:
  php:
    build:
      context: ./packages/workbench/docker/php
      dockerfile: Dockerfile.extends  # Your custom Dockerfile

Environment Variables: Use .env files in your plugin root. The stub includes comments for all available variables (e.g., DB_DATABASE, APP_URL).

Volume Mounts: Mount plugin directories explicitly in docker-compose.yml:

volumes:
  - ./:/var/www/html:cached
  - ./vendor:/var/www/html/vendor:cached

Gotchas and Tips

Pitfalls

POSIX Compliance:
- bin/workbench is written in POSIX sh (no Bashisms like [[, arrays, or $BASH_SOURCE). Test with:
```
sh -n ./vendor/bin/workbench
```
- Avoid Bash-specific syntax in custom scripts if they interact with workbench.
Docker Context Path:
- If workbench up fails with build.context errors, manually verify the path in docker-compose.yml:
```
./vendor/bin/workbench up --force  # Overwrites stubs (use cautiously)
```
Provider Mismatch:
- If tests fail with ClassNotFoundException, ensure extra.laravel.providers in composer.json matches your plugin’s namespace. Run:
```
./vendor/bin/workbench up  # Re-injects providers
```
Playwright Caching:
- If Playwright tests fail with permission errors, ensure the playwright-browsers volume exists and is owned by the workbench user (handled automatically by the Dockerfile).
Host Dependencies:
- Never call php, composer, or node directly on the host. All commands must proxy through docker compose exec (e.g., ./vendor/bin/sail artisan).
Symlink Resolution:
- If ./vendor/bin/workbench or ./vendor/bin/sail fails, resolve symlinks manually:
```
readlink -f ./vendor/bin/workbench
```

Debugging Tips

Container Logs:
```
./vendor/bin/workbench logs
```
- Look for errors in the php service logs.
Shell Access:
```
./vendor/bin/sail shell
```
- Inspect files, permissions, or run manual commands (e.g., composer dump-autoload).
Docker Compose Validation:
```
docker compose config
```
- Validate your docker-compose.yml for syntax errors.
Composer Cache:
- Clear the Composer cache inside the container:
```
./vendor/bin/sail composer clear-cache
```

Extension Points

Custom Dockerfile:
- Extend the base image by creating Dockerfile.extends in your plugin root and referencing it in docker-compose.yml:
```
build:
  context: ./packages/workbench/docker/php
  dockerfile: Dockerfile.extends
```
Custom Entrypoint:
- Override entrypoint.sh by copying it to your plugin root and updating the command in docker-compose.yml:
```
command: ["/var/www/html/entrypoint.sh"]
```

Additional Services:

Extend docker-compose.yml to include databases, Redis, or other services:

services:
  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: plugin_db

Custom Workbench Commands:
- Add subcommands to bin/workbench (POSIX sh) or bin/sail (Bash) following the subcommand reference. Example:
```
# In bin/workbench
cmd_migrate() {
  docker compose exec php php artisan migrate
}
```
  Add to the case block:
```
migrate) cmd_migrate "$@";;
```

Configuration Quirks

Testbench Database:
- The stub sets DB_DATABASE to /var/www/html/vendor/orchestra/testbench-core/laravel/database/database.sqlite by default. For HTTP requests, this avoids Testbench’s in-memory :memory: database. Override in .env if needed:
```
DB_DATABASE=mysql
```
Provider Auto-Fill:
- If _ensure_providers() fails silently, check:
  - extra.laravel.providers exists in composer.json.
  - The placeholder # - Vendor\YourPlugin\... is present in testbench.yaml.
Volume Ownership:
- If you encounter permission errors in /tmp/.cache/ms-playwright, ensure the Dockerfile pre-creates the directory with the correct ownership (handled automatically in the base image).

Performance Tips

Layer Caching:
- The Dockerfile separates Chromium libraries into a dedicated RUN block to avoid cache invalidation for plugins not using Playwright.
Composer Install:
- The entrypoint.sh skips composer install if vendor/autoload.php exists, speeding up container restarts.
Node Modules:
- Similarly, npm install is skipped if node_modules/ exists, reducing rebuild time.

Filament Plugin Workbench Laravel Package