Xhprof Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require jns/xhprof-bundle
   

   Add to config/bundles.php:

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

2. Enable XHProf Extension Ensure the xhprof PHP extension is installed and enabled in php.ini:

   extension=xhprof.so
   

3. Basic Configuration Add to config/packages/jns_xhprof.yaml:

   jns_xhprof:
       enabled: true
       output_dir: '%kernel.project_dir%/var/log/xhprof'
       ignore_functions: ['ignore_me']
   

4. First Use Case Trigger profiling via the Symfony profiler toolbar (appears automatically in dev environment) or manually in code:

   use Jns\XhprofBundle\Xhprof;
   
   $profiler = new Xhprof();
   $profiler->start('my_custom_profile_name');
   // Code to profile...
   $profiler->stop();
   

Implementation Patterns

Workflows

1. Web Profiling

   • Toolbar Integration: The bundle auto-injects XHProf data into Symfony’s Web Profiler toolbar. Click the "XHProf" tab to view results.
   • Manual Profiling:

     $profiler->start('user_auth_flow');
     $user = $this->authService->authenticate($request);
     $profiler->stop();
     

   • Route-Specific Profiling:

     # config/routes.yaml
     app_profile_route:
         path: /profile-heavy-task
         controller: App\Controller\HeavyController::index
         methods: GET
         xhprof: true  # Enable XHProf for this route only
     

2. Console Command Profiling

   use Jns\XhprofBundle\Xhprof;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class MyCommand extends Command {
       protected function execute(InputInterface $input, OutputInterface $output) {
           $profiler = new Xhprof();
           $profiler->start('console_import');
           // Command logic...
           $profiler->stop();
           $output->writeln('Profiling data saved to: ' . $profiler->getOutputDir());
       }
   }
   

3. Conditional Profiling Use environment variables or config flags to toggle profiling:

   # config/packages/dev/jns_xhprof.yaml
   jns_xhprof:
       enabled: '%env(bool:XHPROF_ENABLED)%'
   

Integration Tips

• Symfony Events: Profile event listeners or subscribers:

  $profiler->start('event_dispatcher');
  $this->eventDispatcher->dispatch($event);
  $profiler->stop();
  

• Doctrine Queries: Profile database interactions:

  $profiler->start('db_queries');
  $entity = $entityManager->find(Entity::class, $id);
  $profiler->stop();
  

• Custom Data Collection: Extend profiling with metadata:

  $profiler->addMetadata(['user_id' => $user->id, 'action' => 'update_profile']);
  

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • XHProf adds ~10-30% overhead to execution time. Disable in production:

     # config/packages/prod/jns_xhprof.yaml
     jns_xhprof:
         enabled: false
     

   • Use sparingly in staging; avoid profiling in CI/CD pipelines.

2. Output Directory Permissions Ensure var/log/xhprof is writable:

   mkdir -p var/log/xhprof
   chmod -R 775 var/log/xhprof
   

   Default path: %kernel.project_dir%/var/log/xhprof.

3. Ignored Functions Exclude vendor or internal functions to reduce noise:

   jns_xhprof:
       ignore_functions:
           - 'Symfony\\'
           - 'Doctrine\\'
           - 'Illuminate\\'
   

4. Console Command Quirks

   • Profiling console commands requires Symfony 2.3+. For older versions, use manual triggers.
   • Output files may clutter the directory. Clean up old files periodically:

     find var/log/xhprof -type f -mtime +7 -delete
     

5. Memory Limits XHProf can consume significant memory for long-running processes. Monitor with:

   $profiler->setMemoryLimit(500); // MB
   

Debugging

• Missing Toolbar Tab:

  • Verify enabled: true in config.
  • Check if xhprof extension is loaded (php -m | grep xhprof).
  • Clear cache: php bin/console cache:clear.

• Empty Profiles:

  • Ensure start()/stop() are called around the code to profile.
  • Check ignore_functions isn’t filtering out critical calls.

• Corrupted Data:

  • Delete var/log/xhprof and retry. Files are auto-generated with timestamps.

Extension Points

1. Custom Profiler Classes Extend Jns\XhprofBundle\Xhprof to add logic:

   class CustomProfiler extends Xhprof {
       public function startWithMetadata($name, array $metadata) {
           $this->addMetadata($metadata);
           parent::start($name);
       }
   }
   

2. Post-Processing Hooks Override getOutputDir() or generateReport() to customize output format (e.g., JSON for APIs):

   $profiler->setOutputFormat('json');
   

3. Integration with Blackfire Use XHProf for broad profiling and Blackfire for deep dives (complementary tools).

4. Symfony Flex Recipes Although the bundle is archived, you can manually create a recipe for auto-configuration in modern Symfony apps:

   # config/recipes/jns_xhprof.yaml
   jns_xhprof:
       enabled: '%kernel.debug%'
       output_dir: '%kernel.project_dir%/var/log/xhprof'