Cli Snapshot Profiler Xhprof Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   pecl install xhprof
   docker run -d -p 8080:80 --name xhgui xhgui/xhgui:0.22.1
   

   Ensure extension=xhprof.so is in your php.ini for CLI.

2. Install the Bundle:

   composer require aeatech/cli-snapshot-profiler-xhprof-bundle
   

   Enable the bundle in config/bundles.php:

   AEATech\CLISnapshotProfilerXhprofBundle\AEATechCLISnapshotProfilerXhprofBundle::class => ['dev' => true, 'prod' => true],
   

3. Configure: Update config/packages/aea_tech_cli_snapshot_profiler_xhprof.yaml:

   aea_tech_cli_snapshot_profiler_xhprof:
       is_profiling_enabled: true
       app_version: '1.0.0'
       xhgui:
           import_uri: 'http://localhost:8080/xhgui'
   

4. First Use Case: Run a CLI command with profiling:

   php bin/console your:command --profile
   

   Snapshots will auto-upload to XHGUI at http://localhost:8080/xhgui.

Implementation Patterns

Workflows

1. Enable/Disable Profiling: Toggle via config (is_profiling_enabled) or CLI flag (--profile).

   # config/packages/aea_tech_cli_snapshot_profiler_xhprof.yaml
   is_profiling_enabled: '%kernel.debug%'  # Auto-enable in dev
   

2. Contextual Snapshots: Use the Snapshot service to manually trigger snapshots in critical paths:

   use AEATech\CLISnapshotProfilerXhprofBundle\Service\Snapshot;
   
   public function __invoke(Snapshot $snapshot)
   {
       $snapshot->start('pre-processing');
       // ... logic ...
       $snapshot->stop();
   }
   

3. Custom Metadata: Attach metadata to snapshots for better filtering in XHGUI:

   $snapshot->setMetadata(['user_id' => 123, 'env' => 'staging']);
   

4. Integration with Symfony Console: Extend commands to support profiling:

   use Symfony\Component\Console\Command\Command;
   use AEATech\CLISnapshotProfilerXhprofBundle\Attribute\AsProfiledCommand;
   
   #[AsProfiledCommand]
   class MyCommand extends Command { ... }
   

Integration Tips

• Environment-Specific Configs: Override app_version per environment (e.g., APP_VERSION env var).

  app_version: '%env(APP_VERSION)%'
  

• XHGUI Docker Setup: Use a named volume for persistence:

  docker run -d -p 8080:80 -v xhgui_data:/var/www/xhgui/data xhgui/xhgui:0.22.1
  

• CI/CD Profiling: Enable profiling only in specific environments:

  is_profiling_enabled: '%env(bool:ENABLE_PROFILING)%'
  

Gotchas and Tips

Pitfalls

1. XHProf Extension Conflicts:

   • Ensure xhprof is loaded before other extensions (e.g., opcache). Add to CLI php.ini:

     extension=xhprof.so
     opcache.enable=0  ; Disable during profiling
     

2. Snapshot Naming Collisions:

   • Default naming uses app_version + timestamp. Customize with:

     snapshot_naming_pattern: 'app-{app_version}-{command}-{timestamp}'
     

3. Memory Overhead:

   • Profiling adds ~5-10% overhead. Disable in performance-sensitive paths:

     $snapshot->disable();  // Temporarily pause profiling
     

4. XHGUI Import URI Issues:

   • If snapshots don’t appear, verify:
     • XHGUI is running (docker ps).
     • import_uri is accessible (use http:// not https:// for Docker).
     • No CORS blocks (XHGUI defaults to permissive settings).

Debugging

• Missing Snapshots: Check:

  • xhprof.enable is On in phpinfo().
  • No PHP errors during command execution (profiling fails silently on errors).
  • XHGUI logs (docker logs xhgui).

• CLI Flag Not Working: Ensure the --profile flag is passed before the command:

  php bin/console your:command --profile --option=value
  

Extension Points

1. Custom Profiler Events: Listen for snapshot events to add logic:

   use AEATech\CLISnapshotProfilerXhprofBundle\Event\SnapshotEvent;
   
   $eventDispatcher->addListener(SnapshotEvent::PRE_SNAPSHOT, function (SnapshotEvent $event) {
       $event->getSnapshot()->setMetadata(['custom_key' => 'value']);
   });
   

2. Post-Processing Snapshots: Override the SnapshotStorage service to transform data before upload:

   # config/services.yaml
   AEATech\CLISnapshotProfilerXhprofBundle\Service\SnapshotStorage:
       class: App\Service\CustomSnapshotStorage
       arguments:
           $client: '@http_client'
   

3. Multi-Environment XHGUI: Route snapshots to different XHGUI instances based on env:

   $snapshot->setXhguiUri(env('XHGUI_URI'));