Xhprof Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   "require": {
       "aferrandini/xhprof-bundle": "dev-master"
   }
   

   Run:

   composer update aferrandini/xhprof-bundle
   

2. Enable the Bundle Register in config/bundles.php:

   return [
       // ...
       Aferrandini\XhprofBundle\XhprofBundle::class => ['all' => true],
   ];
   

3. Configure XHProf Publish the default config:

   php bin/console aferrandini:xhprof:install
   

   Edit app/config/xhprof.php to set:

   • enabled: true (for production/staging).
   • output_dir: Path to store .xhprof files (e.g., var/log/xhprof/).

4. First Use Case Trigger profiling via Symfony’s profiler:

   php bin/console debug:profiler
   

   Navigate to /_profiler/ in your browser. Click the "XHProf" tab to view raw data.

Implementation Patterns

Profiling Workflows

1. Automatic Profiling

   • Enable globally in xhprof.php:

     'enabled' => true,
     'always_on' => true, // Profiles all requests
     

   • Useful for staging environments where you want full coverage.

2. Manual Profiling

   • Start/stop profiling programmatically:

     $profiler = $this->get('xhprof.profiler');
     $profiler->start('my_custom_section');
     // ... code to profile ...
     $profiler->stop();
     

   • Ideal for isolating specific logic (e.g., API endpoints, cron jobs).

3. Conditional Profiling

   • Toggle via environment variables or runtime checks:

     if ($this->get('kernel')->getEnvironment() === 'staging') {
         $profiler->start('staging_request');
     }
     

4. Integration with Symfony Events

   • Profile controller actions or kernel events:

     # config/services.yaml
     services:
         App\EventListener\XhprofListener:
             tags:
                 - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
     

     // src/EventListener/XhprofListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         $profiler = $this->container->get('xhprof.profiler');
         $profiler->start('request_' . uniqid());
     }
     

Data Handling

• Output Formats

  • Raw .xhprof files (default) stored in output_dir.
  • Convert to HTML/JSON using XHProf’s tools:

    xhprof_html xhprof.out.12345 > profile.html
    

• Cleanup

  • Automate cleanup of old files via a cron job or Symfony command:

    php bin/console aferrandini:xhprof:cleanup --days=7
    

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • XHProf adds ~5-10% overhead to requests. Disable in production:

     'enabled' => false,
     

   • Use always_on: false to avoid unintended profiling.

2. File Permissions

   • Ensure output_dir is writable:

     chmod -R 775 var/log/xhprof/
     

   • Debug permission issues with:

     php bin/console debug:config aferrandini_xhprof
     

3. Memory Limits

   • Large applications may hit PHP’s memory_limit. Increase if needed:

     'memory_limit' => '256M', // in xhprof.php
     

4. Symfony 4+ Compatibility

   • The bundle is Symfony 2/3-focused. For Symfony 4/5:
     • Manually register the bundle in config/bundles.php.
     • Override autowiring if xhprof.profiler service isn’t found.

5. Missing Profiler Tab

   • If the /_profiler/ XHProf tab doesn’t appear:
     • Clear Symfony cache:

       php bin/console cache:clear
       

     • Verify xhprof extension is loaded in PHP:

       php -m | grep xhprof
       

Debugging Tips

• Check Profiler Status

  $profiler = $this->get('xhprof.profiler');
  var_dump($profiler->isEnabled()); // bool
  

• Log Errors Enable debug logging in xhprof.php:

  'debug' => true,
  

  Check var/log/dev.log for issues.

Extension Points

1. Custom Data Collection

   • Extend the profiler to track custom metrics:

     $profiler->addCustomData('user_id', $user->id);
     

   • Parse this in post-processing scripts.

2. Post-Processing Hooks

   • Override the XhprofBundle\Service\Profiler service to modify output:

     # config/services.yaml
     services:
         App\Service\CustomProfiler:
             decorates: 'xhprof.profiler'
             arguments: ['@App\Service\CustomProfiler.inner']
     

3. Alternative Output

   • Replace the default file writer by binding a custom service:

     // src/DependencyInjection/XhprofExtension.php
     $container->set('xhprof.writer', new CustomWriter());