Symfony Roadrunner Dumper Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-First Design: The package is explicitly built for Symfony applications, leveraging Symfony’s VarDumper component. While Laravel is not natively supported, the underlying mechanism (Roadrunner-compatible variable dumping) aligns with Laravel’s need for debugging in async/PSR-15 contexts (e.g., HTTP workers, queues, or CLI tasks).
• Roadrunner-Specific: Addresses a critical gap in Roadrunner’s default behavior, where dd() fails due to output buffering constraints. This is particularly relevant for Laravel TPMs adopting Roadrunner for performance (e.g., HTTP workers, queues) or CLI tooling.
• Minimal Overhead: The package replaces only the dd() function (\dev\dd()), avoiding invasive changes to existing Laravel debugging workflows (e.g., Tinker, Artisan).

Integration Feasibility

• Laravel Compatibility: Requires manual adaptation (e.g., aliasing \dev\dd to Laravel’s namespace or creating a facade). The StackedDumperLaravel example provides a blueprint.
• Roadrunner Dependency: Mandates Roadrunner as the process manager (not a hard blocker if already adopted, but adds friction for monolithic Laravel apps using PHP-FPM).
• Symfony VarDumper: Laravel’s var_dump() already uses Symfony’s VarDumper under the hood, reducing integration risk for core functionality.

Technical Risk

• Roadrunner-Specific Errors: The package’s primary value proposition (fixing dd() in Roadrunner) may not apply to all Laravel deployments. Risk of misalignment if Roadrunner isn’t the primary process manager.
• Debugging Context Loss: Roadrunner’s async nature means dumps may appear in worker logs/stderr, not the browser/CLI. Requires tooling (e.g., rr get-worker-errors) or logging configuration.
• Version Lock: Hard dependency on Symfony VarDumper (v3.3–5.0) may conflict with Laravel’s bundled version (e.g., if Laravel upgrades Symfony components independently).

Key Questions

1. Roadrunner Adoption: Is Roadrunner already in use, or is this a future migration? If the latter, does the team have a timeline for adoption?
2. Debugging Workflow: How are errors/logs currently surfaced (e.g., Sentry, Laravel Log, stderr)? Will Roadrunner’s worker logs integrate with existing tools?
3. Laravel-Specific Needs: Does the team need Laravel-native features (e.g., Tinker integration, Blade template dumps) that this package lacks?
4. Performance Impact: Will \dev\dd() introduce measurable overhead in production (e.g., if accidentally left in code)?
5. Alternatives: Has the team evaluated other solutions (e.g., custom dd() wrapper, Ray, Laravel Debugbar) for Roadrunner compatibility?

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Laravel apps using Roadrunner for:
  • HTTP workers (e.g., API microservices).
  • Queue workers (e.g., async job processing).
  • CLI tools (e.g., Artisan commands with Roadrunner).
• Secondary Use Case: Less critical for traditional Laravel apps using PHP-FPM, where dd() works natively.
• Dependencies:
  • Must-Have: Roadrunner (v1.0+), PHP 7.1+, Symfony VarDumper.
  • Nice-to-Have: Laravel 6.0+ (for Symfony component compatibility).

Migration Path

1. Pilot Phase:
   • Install in a dev environment: composer require --dev alshenetsky/symfony-roadrunner-dumper.
   • Create a Laravel facade/service to expose \dev\dd() (e.g., app(\Dev\Dumper::class)).
   • Test in a non-critical Roadrunner worker (e.g., a queue job).
2. Full Rollout:
   • Replace all dd() calls with \dev\dd() in Roadrunner-specific code.
   • Update CI/CD to include the package in dev dependencies (exclude from prod).
   • Configure Roadrunner to log worker errors to a centralized system (e.g., Sentry, ELK).
3. Fallback Plan:
   • If Roadrunner adoption stalls, revert to a custom dd() wrapper or use Laravel Debugbar for HTTP contexts.

Compatibility

• Roadrunner Versions: Tested with Roadrunner v1.0+ (check Roadrunner’s changelog for output buffer changes).
• Laravel Versions: No direct support, but Symfony VarDumper compatibility suggests broad Laravel version support (test with LTS versions: 8.x, 9.x, 10.x).
• Conflict Risk: Low with Laravel’s core, but potential conflicts with:
  • Other dd() wrappers (e.g., Laravel Debugbar).
  • Custom error handlers that modify VarDumper output.

Sequencing

1. Pre-requisite: Ensure Roadrunner is configured with worker.error logging enabled.
2. Step 1: Integrate the package in a dev-only namespace (e.g., Dev\Dumper).
3. Step 2: Replace dd() in Roadrunner-specific files (e.g., workers, CLI commands).
4. Step 3: Add CI checks to verify \dev\dd() works in Roadrunner’s test environment.
5. Step 4: Document the change in the team’s debugging guide (e.g., "Use \dev\dd() for Roadrunner workers").

Operational Impact

Maintenance

• Dev Dependency: Installed as --dev, reducing prod footprint.
• Updates: Monitor Symfony VarDumper updates for breaking changes (e.g., Laravel’s bundled version may diverge).
• Customization: Easy to extend (e.g., add Laravel-specific dump formatting) via facade/service layer.

Support

• Debugging Overhead: Dumps appear in Roadrunner worker logs, requiring:
  • Tooling to aggregate/worker errors (e.g., rr get-worker-errors).
  • Training for devs on interpreting async dumps (e.g., "This dump is from worker #4").
• Error Handling: No built-in support for production error masking (e.g., APP_DEBUG=false still shows dumps in logs).
• Community: Limited to Symfony/Roadrunner; Laravel-specific issues may need custom fixes.

Scaling

• Performance: Minimal impact in dev; negligible in prod if dd() calls are removed.
• Roadrunner Scaling: Dumps are worker-specific; scaling workers won’t amplify dump volume unless misconfigured.
• Log Volume: Risk of log explosion if \dev\dd() is accidentally left in prod code. Mitigate with:
  • CI checks for \dev\dd() in prod branches.
  • Feature flags to disable dumps in non-dev environments.

Failure Modes

Ramp-Up

• Onboarding Time: Low for teams familiar with Roadrunner/Symfony; higher for Laravel-only teams.
• Key Training Topics:
  • How to read Roadrunner worker logs.
  • Differences between \dev\dd() and dd() (e.g., no browser output).
  • When to use \dev\dd() vs. other tools (e.g., Laravel Tinker for CLI debugging).
• Documentation Gaps:
  • No Laravel-specific setup guide (must adapt from Symfony example).
  • Lack of examples for common Laravel use cases (e.g., dumping Eloquent models, Blade data).
• Recommended Resources:
  • Roadrunner Debugging Guide.
  • Symfony VarDumper Customization.