Cli Snapshot Profiler Xhprof Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony CLI Profiling: The bundle is designed specifically for Symfony CLI applications, leveraging XHProf (a hierarchical profiler for PHP) to capture execution snapshots. This aligns well with Laravel if:
  • The Laravel application exposes CLI commands via Symfony’s Console component (e.g., via symfony/console integration).
  • Profiling is needed for long-running CLI jobs (e.g., queue workers, migrations, or custom scripts) rather than HTTP requests.
• XHProf Dependency: Requires ext-xhprof, which is not natively supported in Laravel (unlike tideways/xhprof). This introduces a non-standard dependency that may conflict with Laravel’s default profiling tools (e.g., Laravel Debugbar, Blackfire).
• Production Profiling: Targets production-grade profiling, which is a niche use case for Laravel (typically, profiling is dev-focused). Justification for production use must address:
  • Overhead impact on performance.
  • Storage/retention of profiling data (XHGUI integration).

Integration Feasibility

• Symfony Bundle in Laravel: Laravel does not natively support Symfony bundles, but integration is possible via:
  • Symfony Console Component: If Laravel CLI commands extend Symfony\Component\Console\Command, the bundle can be manually initialized in the command’s initialize() method.
  • Service Container: Register the bundle’s services manually in Laravel’s AppServiceProvider (e.g., binding AEATech\CLISnapshotProfilerXhprofBundle\Profiler).
• XHGUI Compatibility: XHGUI is a standalone PHP tool for visualizing XHProf data. Laravel would need:
  • A separate XHGUI instance (Dockerized, as per the README) to store/serve snapshots.
  • Custom logic to export Laravel CLI command output to XHGUI’s expected format (e.g., via a post-execution hook).

Technical Risk

Key Questions

1. Why XHProf?
   • Is there a specific need for XHProf’s function-level granularity over alternatives like:
     • Tideways/XHProf (Laravel-native, supports HTTP/CLI).
     • Blackfire (production-safe, but paid).
     • Laravel’s built-in dd() or Xdebug?
2. Production Use Case
   • What CLI commands are being profiled? Are they idempotent (safe for overhead)?
   • How will profiling data be accessed/analyzed (XHGUI UI, custom dashboard)?
3. Alternatives Evaluated
   • Has spatie/laravel-profiler or barryvdh/laravel-debugbar been considered for CLI profiling?
   • Would a custom XHProf wrapper (without Symfony bundle) reduce integration risk?
4. Operational Trade-offs
   • Who will manage XHGUI infrastructure (Docker, scaling, backups)?
   • How will profiling be enabled/disabled in production (feature flag, env var)?

Integration Approach

Stack Fit

• Laravel + Symfony Console:
  • Best Fit: If Laravel CLI commands already extend Symfony\Component\Console\Command, integration is low-effort (see "Manual Installation" below).
  • Partial Fit: For vanilla Laravel Artisan commands, a wrapper class would be needed to delegate to the profiler.
• XHProf/XHGUI:
  • Dockerized XHGUI: The package recommends a Docker setup for XHGUI. Laravel would need to:
    • Configure a reverse proxy (Nginx) to route /xhgui to the Docker container.
    • Set AEA_TECH_CLI_SNAPSHOT_PROFILER_XHPROF_XHGUI env var to the XHGUI endpoint (e.g., http://xhgui:80).
  • Snapshot Storage: XHGUI stores data in ./xhgui/data/. For Laravel, consider:
    • Mounting a volume (Docker) or S3 sync for persistence.
    • Automated cleanup (e.g., aws s3 rm for old snapshots).

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Install the bundle in a staging environment with is_profiling_enabled: true.
   • Test with a single CLI command (e.g., php artisan queue:work).
   • Validate:
     • Snapshots appear in XHGUI.
     • Performance overhead is acceptable (<5%).
2. Phase 2: Laravel Integration
   • Option A (Symfony Console): Extend Laravel commands with Symfony\Component\Console\Command and initialize the profiler in initialize().

     use AEATech\CLISnapshotProfilerXhprofBundle\Profiler;
     
     class MyCommand extends Command {
         public function initialize(Profiler $profiler) {
             $profiler->start();
         }
     
         protected function execute(InputInterface $input, OutputInterface $output) {
             // Command logic
             $profiler->stop(); // Ensure snapshots are saved
         }
     }
     

   • Option B (Manual Service Binding): Register the profiler as a Laravel service:

     // AppServiceProvider
     $this->app->bind(Profiler::class, function ($app) {
         return new Profiler($app['config']['aea_tech_cli_snapshot_profiler_xhprof']);
     });
     

3. Phase 3: Production Rollout
   • Enable profiling only for critical commands (e.g., via env var).
   • Set up XHGUI monitoring (e.g., Prometheus metrics for snapshot volume).
   • Document snapshot retention policy (e.g., 30-day TTL).

Compatibility

Sequencing

1. Prerequisites:
   • Install ext-xhprof and xhgui/xhgui:0.22.1 (Docker).
   • Configure php.ini for CLI:

     extension=xhprof.so
     xhprof.output_dir=/tmp/xhprof
     

2. Bundle Installation:
   • Use manual installation (avoid Symfony Flex due to Laravel’s non-Symfony stack).
   • Enable in config/bundles.php for both dev/prod (if production profiling is needed).
3. Configuration:
   • Set is_profiling_enabled: true in aea_tech_cli_snapshot_profiler_xhprof.yaml.
   • Configure xhgui.import_uri to point to the Dockerized XHGUI instance.
4. Testing:
   • Run a CLI command and verify snapshots in XHGUI.
   • Check Laravel logs for errors (e.g., missing services).
5. Monitoring:
   • Add a health check for XHGUI (e.g., HTTP endpoint ping).
   • Set up alerts for high snapshot volume (indicates profiling overhead).

Operational Impact

Maintenance

• Bundle Updates:
  • **No