Add support for hprof in order to have profiling. (#3881)

Author: ildyria

.gitignore

@@ -61,3 +61,6 @@ docker-compose.yml
 Lychee/*
 /public/embed/
 report_*
+
+# XHProf output
+public/vendor/

composer.json

@@ -109,6 +109,7 @@
         "filp/whoops": "^2.5",
         "friendsofphp/php-cs-fixer": "^3.3",
         "itsgoingd/clockwork": "^5.1",
+        "laracraft-tech/laravel-xhprof": "^1.2",
         "larastan/larastan": "^3.2",
         "lychee-org/phpstan-lychee": "^2.0.1",
         "mockery/mockery": "^1.5",

composer.lock

@@ -0,0 +1,10 @@
+<?php
+
+return [
+	'enabled' => env('XHPROF_ENABLED', false),
+
+	'skip' => [
+		'/__clockwork/',
+		'/_debugbar/',
+	],
+];

config/xhprof.php

@@ -0,0 +1,68 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+class CreateXHProfTable extends Migration
+{
+	/**
+	 * Run the migrations.
+	 *
+	 * @return void
+	 */
+	public function up()
+	{
+		if (DB::connection()->getDriverName() !== 'mysql') {
+			return;
+		}
+
+		Schema::create('details', function (Blueprint $table) {
+			$table->id('idcount');
+			$table->char('id', 64);
+			$table->char('url', 255)->nullable();
+			$table->char('c_url', 255)->nullable();
+			$table->timestamp('timestamp')->useCurrent()->useCurrentOnUpdate();
+			$table->char('server name', 64)->nullable();
+			$table->binary('perfdata')->nullable();
+			$table->tinyInteger('type')->nullable();
+			$table->binary('cookie')->nullable();
+			$table->binary('post')->nullable();
+			$table->binary('get')->nullable();
+			$table->integer('pmu')->nullable();
+			$table->integer('wt')->nullable();
+			$table->integer('cpu')->nullable();
+			$table->char('server_id', 64)->nullable();
+			$table->char('aggregateCalls_include', 255)->nullable();
+
+			$table->index('url');
+			$table->index('c_url');
+			$table->index('cpu');
+			$table->index('wt');
+			$table->index('pmu');
+			$table->index('timestamp');
+			$table->index(['server name', 'timestamp']);
+		});
+
+		if (DB::connection()->getDriverName() === 'mysql') {
+			DB::statement('ALTER TABLE details MODIFY COLUMN `perfdata` LONGBLOB');
+			DB::statement('ALTER TABLE details MODIFY COLUMN `cookie` LONGBLOB');
+			DB::statement('ALTER TABLE details MODIFY COLUMN `post` LONGBLOB');
+		}
+	}
+
+	/**
+	 * Reverse the migrations.
+	 *
+	 * @return void
+	 */
+	public function down()
+	{
+		if (DB::connection()->getDriverName() !== 'mysql') {
+			return;
+		}
+
+		Schema::dropIfExists('details');
+	}
+}

database/migrations/2025_12_22_163233_create_xhprof_table.php

@@ -0,0 +1,46 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class AddIndexToXHProfTable extends Migration
+{
+	/**
+	 * Run the migrations.
+	 *
+	 * @return void
+	 */
+	public function up()
+	{
+		if (DB::connection()->getDriverName() !== 'mysql') {
+			return;
+		}
+
+		Schema::table('details', function (Blueprint $table) {
+			$table->dropColumn('idcount');
+			$table->char('id', 64)->primary()->change();
+		});
+	}
+
+	/**
+	 * Reverse the migrations.
+	 *
+	 * @return void
+	 */
+	public function down()
+	{
+		if (DB::connection()->getDriverName() !== 'mysql') {
+			return;
+		}
+
+		Schema::table('details', function (Blueprint $table) {
+			$table->dropPrimary();
+		});
+
+		Schema::table('details', function (Blueprint $table) {
+			$table->id('idcount');
+			$table->char('id', 64)->change();
+		});
+	}
+}

database/migrations/2025_12_22_163234_add_index_to_xhprof_table.php

@@ -0,0 +1,78 @@
+# How to Enable and Use XHProf in Lychee
+
+XHProf is a profiling tool for PHP applications. This guide explains how to install, configure, and use XHProf in the Lychee project.
+
+---
+
+**This is only possible if you are using a MySQL/MariaDB database, as the XHProf storage implementation relies on it.**
+
+## Installation
+
+1. **Install XHProf**
+
+Run the following commands to install XHProf and its dependencies:
+
+```bash
+sudo add-apt-repository ppa:ondrej/php
+sudo apt-get update
+sudo apt-get install php php-xhprof graphviz
+```
+
+Verify the installation:
+
+```bash
+php -i | grep xhprof
+```
+
+If necessary, restart your web server or PHP-FPM service.
+
+2. **Download the Visualization Tool**
+
+Clone the XHProf visualization tool into the `public/vendor` directory:
+
+```bash
+git clone [email protected]:preinheimer/xhprof.git ./public/vendor/xhprof
+```
+
+3. **Set Up the Configuration**
+
+Copy the sample configuration file and update it:
+
+```bash
+cp public/vendor/xhprof/xhprof_lib/config.sample.php public/vendor/xhprof/xhprof_lib/config.php
+nano public/vendor/xhprof/xhprof_lib/config.php
+```
+
+Update the following settings in the configuration file:
+
+- **Database Credentials:** Set the database credentials to match your environment.
+- **Enable `dot_binary`:** Uncomment and configure the `dot_binary` section.
+- **Control IPs:** If running locally, set `$controlIPs` to `false`.
+
+---
+
+## Usage
+
+1. **Enable XHProf**
+
+Set the following environment variable in your `.env` file:
+
+```env
+XHPROF_ENABLED=true
+```
+
+2. **Profile Requests**
+
+Once enabled, every request to your application will be profiled automatically.
+
+3. **View Profiling Results**
+
+Open the following URL in your browser to view the profiling results:
+
+```
+<your-host>/vendor/xhprof/xhprof_html/
+```
+
+---
+
+*Last updated: December 22, 2025*

docs/specs/2-how-to/enable-hprof.md

@@ -32,6 +32,9 @@
     __DIR__ . '/app/Metadata/Laminas/Unicode.php',
 
     // Ignore all the test directory for now...
-    __DIR__ . '/tests/*'
+    __DIR__ . '/tests/*',
+	// Ignore all hprof related files
+	__DIR__ . '/public/vendor/xhprof/*',
+
 ]);
 return $rectorConfig;

rector.php

@@ -32,6 +32,6 @@ public function testOptimizeDb(): void
 	{
 		$optimize = new OptimizeDb();
 		$output = count($optimize->do());
-		self::assertTrue(in_array($output, [3, 34], true), 'OptimizeDb should return either 3 or 34: ' . $output);
+		self::assertTrue(in_array($output, [3, 34, 35], true), 'OptimizeDb should return either 3 or 34 or 35: ' . $output);
 	}
 }

tests/Unit/Actions/Db/OptimizeDbTest.php

@@ -32,6 +32,6 @@ public function testOptimizeTables(): void
 	{
 		$optimize = new OptimizeTables();
 		$output = count($optimize->do());
-		self::assertTrue(in_array($output, [3, 34], true), 'OptimizeTables should return either 3 or 30: ' . $output);
+		self::assertTrue(in_array($output, [3, 34, 35], true), 'OptimizeTables should return either 3 or 34 or 35: ' . $output);
 	}
 }