Xhgui Collector Laravel Package

Technical Evaluation

Architecture Fit The perftools/xhgui-collector package is a legacy but functional tool for integrating XHProf profiling data into a Laravel application via MongoDB storage. While Laravel’s ecosystem has evolved toward modern observability tools (e.g., Laravel Telescope, Blackfire, or Tideways), this package offers a lightweight, customizable alternative for teams already invested in XHGUI or needing low-overhead profiling. Key architectural considerations:

• Profiling Granularity: Supports XHProf, UProfiler, and Tideways, making it adaptable to existing profiling extensions.
• MongoDB Dependency: Requires MongoDB (v2.2.0+), which may introduce operational complexity if not already in use.
• Legacy Compatibility: Targets PHP 5.3+, which is outdated for modern Laravel (8.x+). However, the package’s core logic (data collection/transmission) remains relevant for performance debugging in custom code paths.
• Laravel Integration: Relies on auto_prepend_file or manual inclusion, which can conflict with Laravel’s bootstrap process (e.g., bootstrap/app.php). Requires careful placement in the service provider lifecycle (e.g., register() vs. boot()).

Integration Feasibility

• High for Custom Profiling: Ideal for teams profiling specific routes, CLI commands, or legacy codebases where XHGUI’s UI is preferred over Laravel’s built-in tools.
• Low for Modern Stacks: Poor fit for Laravel-first observability (e.g., Telescope, Horizon) or SaaS alternatives (New Relic, Datadog).
• Middleware Hooks: Can be integrated via Laravel middleware (e.g., Kernel.php) or service providers, but requires manual setup of MongoDB connections and XHGUI configuration.
• Environment Variables: Supports Docker-friendly config via XHGUI_MONGO_URI, XHGUI_PROFILING_RATIO, etc., reducing hardcoded dependencies.

Technical Risk

• Critical Risks:
  • MongoDB Dependency: Adds a non-standard database to the stack, increasing operational overhead (backups, scaling, security).
  • Legacy PHP Support: PHP 5.3+ is unsupported and may conflict with Laravel’s modern dependencies (e.g., Symfony components).
  • Schema Changes: XHGUI’s 0.7.1 compatibility may break if future versions modify the data schema (see README compatibility table).
• Moderate Risks:
  • Profiling Overhead: XHProf itself adds ~5–10% runtime overhead; enabling for all requests (default PROFILING_RATIO=100) may impact performance.
  • Session Locking: Fixed in v1.5.3, but redirects during profiling could still cause issues in high-concurrency apps.
• Mitigation:
  • Isolate Profiling: Use PROFILING_RATIO (e.g., 10) to sample requests.
  • Containerize MongoDB: Use Docker/Kubernetes for portability.
  • Test Schema Compatibility: Validate against your XHGUI version before production use.

Key Questions

1. Why XHGUI?
   • Are we replacing an existing profiling tool (e.g., Blackfire, Xdebug), or is this a new initiative?
   • Does the team have XHGUI expertise, or will we need to train developers on its UI/analysis?
2. Operational Trade-offs
   • Can we dedicate a MongoDB instance for profiling, or will it share resources with production?
   • How will we monitor MongoDB performance under profiling load?
3. Laravel Integration
   • Where in the bootstrap lifecycle should we inject the collector (header.php) to avoid conflicts with Laravel’s service providers?
   • Will we need to customize the collector (e.g., filter specific routes)?
4. Deprecation Risk
   • The package is archived and recommends perftools/php-profiler. Should we migrate to a maintained alternative (e.g., Tideways)?
5. Cost vs. Value
   • What’s the ROI of profiling vs. using Laravel’s built-in tools (e.g., dd(), telescope) or SaaS?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Pros: Lightweight, no Laravel-specific dependencies (works with any PHP app).
  • Cons: No native Laravel integration (e.g., no laravel-profiler package). Requires manual setup.
  • Best For:
    • Legacy Laravel apps (pre-8.x) where modern tools aren’t available.
    • Custom CLI profiling (e.g., Artisan commands, queues).
    • Teams already using XHGUI for historical data or UI preferences.
• Alternative Stacks:
  • Symfony: Works identically (no Laravel-specific logic).
  • WordPress: Possible via mu-plugins or functions.php hooks.

Migration Path

1. Assess Profiling Needs:
   • Identify critical paths (e.g., API endpoints, slow queries) to profile.
   • Decide if sampling (PROFILING_RATIO) is sufficient or if full profiling is needed.
2. Set Up MongoDB:
   • Install MongoDB (v2.2.0+) and configure XHGUI_MONGO_URI (e.g., mongodb://xhgui:27017).
   • Ensure authentication/encryption is configured for production.
3. Integrate with Laravel:
   • Option A: auto_prepend_file (Global) Add to php.ini or .user.ini:

     auto_prepend_file = "/path/to/vendor/perftools/xhgui-collector/external/header.php"
     

     Risk: Affects all requests, including non-profiled routes.
   • Option B: Middleware (Selective) Create a middleware to include header.php only for profiled routes:

     // app/Http/Middleware/Profile.php
     public function handle($request, Closure $next) {
         if ($request->isProfiled()) { // Custom logic
             require __DIR__.'/../../vendor/perftools/xhgui-collector/external/header.php';
         }
         return $next($request);
     }
     

   • Option C: Service Provider (CLI) For Artisan commands, include header.php in a custom service provider:

     // app/Providers/ProfileServiceProvider.php
     public function boot() {
         if ($this->app->runningInConsole()) {
             require __DIR__.'/../../vendor/perftools/xhgui-collector/external/header.php';
         }
     }
     

4. Configure Environment Variables:

   export XHGUI_MONGO_DB=xhprof
   export XHGUI_PROFILING_RATIO=10  # Profile 10% of requests
   export XHGUI_PROFILING=enabled
   

5. Validate:
   • Test with XHGUI_PROFILING_RATIO=100 to ensure data is collected.
   • Verify MongoDB stores profiles in the correct collection (xhprof by default).

Compatibility

• Laravel 8.x+: Works, but PHP 8.x may require polyfills for legacy XHProf/Tideways extensions.
• MongoDB Drivers:
  • Recommended: alcaeus/mongo-php-adapter (Composer dependency).
  • Alternative: PECL mongo extension (v1.3.0+).
• Profiling Extensions:
  • XHProf: Requires PECL extension (pecl install xhprof).
  • Tideways: Requires tideways_xhprof extension (commercial).
  • UProfiler: PHP-only, no extensions needed.

Sequencing

1. Phase 1: Proof of Concept
   • Deploy in staging with PROFILING_RATIO=10.
   • Validate data in XHGUI UI.
2. Phase 2: Selective Profiling
   • Restrict to specific routes (e.g., /api/v1/*) via middleware.
3. Phase 3: Production Rollout
   • Gradually increase PROFILING_RATIO (e.g., 10 → 50).
   • Monitor MongoDB CPU/memory usage.
4. Phase 4: Maintenance
   • Set up alerts for MongoDB errors.
   • Document profiling workflows (e.g., "How to analyze a slow endpoint").

Operational Impact

Maintenance

• Configuration Management:
  • Store XHGUI_* variables in environment files (