Xhprof Bundle Laravel Package

Getting Started

Minimal Setup

1. Install XHProf Extension Ensure the PHP xhprof extension is installed and enabled in your environment.

   • Linux: pecl install xhprof + add extension=xhprof.so to php.ini
   • Mac: pecl install xhprof or via MacPorts (sudo port install php-xhprof)
   • Verify with php -m | grep xhprof.

2. Install the Bundle Add the bundle to your project:

   composer require cristiansitov/xhprof-bundle
   

   Or manually clone into src/Jns/Bundle/XhprofBundle.

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

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

4. Configure the Bundle Add to config/packages/xhprof.yaml:

   jns_xhprof:
       enabled: true
       output_dir: '%kernel.project_dir%/var/log/xhprof'
       show_in_toolbar: true
   

5. First Use Case Trigger profiling in a controller:

   use Jns\Bundle\XhprofBundle\Xhprof\Xhprof;
   
   public function indexAction()
   {
       Xhprof::start('my_profile_session');
       // Your code here...
       $data = Xhprof::stop('my_profile_session');
       return $this->render('...', ['profile_data' => $data]);
   }
   

   View results in the Symfony Profiler toolbar or via the generated HTML UI in var/log/xhprof.

Implementation Patterns

Workflows

1. Profiling Critical Paths Use Xhprof::start() at the beginning of long-running actions (e.g., API endpoints, batch jobs) and Xhprof::stop() at the end. Example:

   public function processOrderAction()
   {
       Xhprof::start('order_processing');
       $order = $this->orderService->process();
       Xhprof::stop('order_processing');
       return $this->json($order);
   }
   

2. Conditional Profiling Enable/disable profiling dynamically based on environment or user role:

   if ($this->container->getParameter('kernel.environment') === 'prod') {
       Xhprof::start('prod_request');
   }
   

3. Integration with Symfony Events Profile event listeners or subscribers:

   public function onKernelRequest(GetResponseEvent $event)
   {
       if ($event->isMasterRequest()) {
           Xhprof::start('request_' . uniqid());
       }
   }
   

4. Generating Reports Use the built-in HTML UI or extend it to create custom reports:

   $profiler = new \Jns\Bundle\XhprofBundle\Xhprof\Profiler();
   $profiler->generateReport($data, 'var/log/xhprof/report.html');
   

Integration Tips

• Symfony Profiler Toolbar Enable show_in_toolbar: true to view profiling data alongside other Symfony profiler panels.
• Caching Profiles Store raw XHProf data in the database (e.g., Doctrine) for historical analysis.
• CI/CD Pipelines Automate profiling in tests or deployment pipelines to track performance regressions.
• Custom Metrics Extend the bundle to log custom metrics (e.g., database query counts) alongside XHProf data.

Gotchas and Tips

Pitfalls

1. Extension Not Loaded

   • Symptom: No profiling data appears.
   • Fix: Verify xhprof is enabled in phpinfo() and restart the web server.

2. Permission Issues

   • Symptom: Profiles not saved to output_dir.
   • Fix: Ensure the web server user (e.g., www-data) has write permissions:

     chmod -R 775 var/log/xhprof
     chown -R www-data:www-data var/log/xhprof
     

3. High Overhead

   • Symptom: Profiling slows down production requests.
   • Fix: Disable in production (enabled: false) or use a feature flag:

     jns_xhprof:
         enabled: '%kernel.debug%'
     

4. Memory Limits

   • Symptom: Profiles truncated or crashes.
   • Fix: Increase PHP memory limit (memory_limit: 512M) or reduce profiling scope.

5. Symfony Cache Conflicts

   • Symptom: Profiler toolbar disappears after cache:clear.
   • Fix: Clear cache after enabling the bundle or use debug:config to verify bundle registration.

Debugging

• Check Raw Data Inspect var/log/xhprof for raw JSON files. Use jq to parse:

  jq '.' var/log/xhprof/cj_12345.json
  

• Log Errors Enable Symfony debug mode (APP_DEBUG=true) to catch bundle initialization errors.

Tips

1. Profile Specific Routes Use middleware to profile only high-traffic routes:

   public function onKernelRequest(Request $event)
   {
       if (str_starts_with($event->getRequest()->getPathInfo(), '/api')) {
           Xhprof::start('api_request');
       }
   }
   

2. Compare Profiles Use tools like tideways/xhprof to diff profiles across versions.

3. Extend the Bundle Override the profiler class to add custom logic:

   // src/Xhprof/ExtendedProfiler.php
   class ExtendedProfiler extends \Jns\Bundle\XhprofBundle\Xhprof\Profiler
   {
       public function generateReport($data, $outputFile)
       {
           // Custom logic here...
           parent::generateReport($data, $outputFile);
       }
   }
   

   Register in services.yaml:

   Jns\Bundle\XhprofBundle\Xhprof\Profiler: '@app.xhprof.extended_profiler'
   

4. Exclude Vendor Code Filter out profiling data from third-party libraries by modifying the Xhprof service configuration.

5. Use with Blackfire Combine XHProf with Blackfire for deeper insights (though avoid running both simultaneously).