Filament Plugin Workbench Laravel Package

Technical Evaluation

Architecture Fit

• Docker-Centric Development: The package excels as a shared Docker infrastructure for Filament plugin development, abstracting container lifecycle management (up/down/fresh/logs/shell) and proxying CLI tools (artisan, phpunit, etc.) into containers. This aligns perfectly with Laravel plugin ecosystems where isolation and reproducibility are critical.
• Filament-Specific Optimizations: Tailored for Filament plugins (e.g., auto-injecting extra.laravel.providers into testbench.yaml, Playwright browser caching), reducing boilerplate for plugin maintainers.
• Minimal Host Dependencies: Only requires Docker, making it portable across dev environments (Linux/macOS/WSL). Avoids Python/jq as runtime dependencies, relying on python3 as a fallback (common on 99% of systems).

Integration Feasibility

• Git Submodule Pattern: Designed for inclusion as a submodule (packages/workbench/), with dynamic path resolution for Dockerfile and stubs. This is low-friction for existing Laravel/Filament plugins.
• Composer Integration: Symlinks vendor/bin/workbench and vendor/bin/sail, enabling seamless CLI access without manual setup.
• Testbench Compatibility: Generates testbench.yaml with provider auto-detection, reducing manual configuration for testing.

Technical Risk

• POSIX Sh Constraints: The workbench CLI is written in strict POSIX sh (no Bashisms), which may limit future feature additions (e.g., arrays, advanced string handling). Risk: Maintenance overhead if complex logic is needed.
• Docker Volume Ownership: Relies on pre-created /tmp/.cache/ms-playwright in the image to avoid permission issues. Risk: Edge cases with custom Docker setups or non-standard volume mounts.
• Python Dependency for JSON Parsing: Uses python3 for parsing composer.json (with Docker fallback). Risk: Minor performance overhead or failure on exotic environments (though mitigated by the fallback).
• No Plugin-Specific Extensions: Hardcodes PHP extensions (e.g., intl, pcntl) and Chromium libraries. Risk: Overhead for plugins not using Playwright (~20MB), but justified by simplicity.

Key Questions

1. Adoption Barrier: With 0 stars and 0 dependents, how will this package gain traction? Will Filament’s core team or major plugin authors adopt it?
2. Long-Term Maintenance: The MIT license is permissive, but who will maintain the package if the author (CoringaWc) steps away? Is there a backup plan (e.g., Filament team sponsorship)?
3. Customization Limits: The package enforces strict rules (e.g., no plugin-specific Dockerfile overrides). Will this frustrate developers needing non-standard setups?
4. Performance Impact: The Chromium libraries add ~20MB to the base image. Is this acceptable for all use cases, or will it deter lightweight plugin developers?
5. Cross-Platform Testing: While Docker is cross-platform, has this been rigorously tested on Windows (non-WSL) and macOS (Apple Silicon)? Volume ownership and symlink resolution may vary.
6. Testbench Integration: How robust is the testbench.yaml provider auto-detection? Will it handle edge cases (e.g., malformed composer.json, missing providers) gracefully?
7. Future-Proofing: PHP 8.4 and Node 22 are modern, but will this package support Laravel 11+ and Filament 3.x migrations smoothly? Are there plans for versioned Docker images?

Integration Approach

Stack Fit

• Primary Use Case: Filament plugin development (e.g., filament-acl, filament-media-library). Ideal for teams building plugins requiring:
  • Isolated Docker environments.
  • Testbench integration for testing.
  • Playwright for browser automation.
• Secondary Use Case: Any Laravel package needing Sail-like CLI proxying without Laravel’s full Sail overhead.
• Unsuitable For: Monolithic Laravel apps (use Laravel Sail instead) or plugins not using Filament/Testbench.

Migration Path

1. Add as Submodule:

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

2. Initialize Workbench:

   ./vendor/bin/workbench install
   

   • Copies docker-compose.yml.stub → docker-compose.yml (with dynamic build.context).
   • Copies testbench.yaml.stub → testbench.yaml (with provider auto-fill).
3. Start Development:

   ./vendor/bin/workbench up
   ./vendor/bin/sail artisan migrate
   

4. Daily Workflow:
   • Use ./vendor/bin/sail for all CLI commands (artisan, phpunit, etc.).
   • Use ./vendor/bin/workbench for environment management (fresh, logs, shell).

Compatibility

• Docker Version: Requires Docker Compose v2 (tested with docker compose syntax).
• Host OS: Tested on Linux/macOS (WSL). Windows non-WSL may need adjustments for symlinks/volumes.
• PHP/Node: Locked to PHP 8.4 and Node 22. Plugins using other versions must override the Dockerfile.
• Filament/Testbench: Assumes Filament 2.x and Testbench compatibility. May need updates for Filament 3.x.

Sequencing

1. Pre-Development:
   • Add submodule → workbench install → workbench up.
   • Configure .env (e.g., DB_DATABASE path for SQLite).
2. During Development:
   • Use sail artisan for Laravel commands.
   • Use sail phpunit for tests.
   • Use workbench shell for debugging.
3. Post-Development:
   • workbench down to clean up.
   • Remove submodule if no longer needed:

     git submodule deinit -f packages/workbench
     rm -rf .git/modules/packages/workbench
     

Operational Impact

Maintenance

• Low Host Maintenance: No PHP/Composer/Node installed on the host—everything runs in containers.
• Submodule Management:
  • Updates require git submodule update --remote.
  • Risk: Breaking changes if the package’s Dockerfile or CLI scripts evolve.
• Stub Customization: Plugins can override docker-compose.yml or testbench.yaml post-generation.

Support

• Troubleshooting:
  • Docker Issues: Debug with docker compose logs.
  • Permission Errors: Ensure /tmp/.cache/ms-playwright has correct ownership (handled by the image).
  • CLI Errors: Run ./vendor/bin/workbench help or ./vendor/bin/sail --help.
• Fallbacks:
  • Python unavailable? Uses Dockerized Python.
  • realpath missing? Falls back to heuristics.
• Documentation: Lightweight (README.md + AGENTS.md). May need expansion for edge cases.

Scaling

• Multi-Plugin Workspaces: Not designed for monorepos with multiple plugins. Each plugin should have its own submodule instance.
• CI/CD:
  • GitHub Actions: Use workbench up + sail test in workflows.
  • Parallelization: Containers are independent; scale by running multiple docker compose instances.
• Resource Usage:
  • Base image: ~200MB (PHP 8.4 + Node 22 + Chromium libs).
  • Playwright cache: ~500MB–1GB (persisted in named volume).

Failure Modes

Ramp-Up

• For Developers:
  • Time to First Container: ~2 minutes (submodule add + workbench up).
  • Learning Curve: Low for Filament plugin devs; moderate for Laravel devs unfamiliar with Testbench.
• For Teams:
  • Onboarding: Standardize filament-plugin-workbench as a submodule in plugin templates.
  • Training: Focus on sail vs. workbench commands (e.g., sail artisan vs. `workbench shell