Add documentation for co-phpunit and command-benchmark components

Co-authored-by: huangdijia <8337659+huangdijia@users.noreply.github.com>

Author: Copilot

docs/.vitepress/src/en/sidebars.ts

@@ -13,6 +13,14 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Cache',
                     link: '/en/components/cache.md'
                 },
+                {
+                    text: 'Co-PHPUnit',
+                    link: '/en/components/co-phpunit.md'
+                },
+                {
+                    text: 'Command Benchmark',
+                    link: '/en/components/command-benchmark.md'
+                },
                 {
                     text: 'Command Signals',
                     link: '/en/components/command-signals.md'

docs/.vitepress/src/zh-cn/sidebars.ts

@@ -26,6 +26,14 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Cache',
                     link: '/zh-cn/components/cache.md'
                 },
+                {
+                    text: 'Co-PHPUnit',
+                    link: '/zh-cn/components/co-phpunit.md'
+                },
+                {
+                    text: 'Command Benchmark',
+                    link: '/zh-cn/components/command-benchmark.md'
+                },
                 {
                     text: 'Command Signals',
                     link: '/zh-cn/components/command-signals.md'

docs/.vitepress/src/zh-hk/sidebars.ts

@@ -26,6 +26,14 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Cache',
                     link: '/zh-hk/components/cache.md'
                 },
+                {
+                    text: 'Co-PHPUnit',
+                    link: '/zh-hk/components/co-phpunit.md'
+                },
+                {
+                    text: 'Command Benchmark',
+                    link: '/zh-hk/components/command-benchmark.md'
+                },
                 {
                     text: 'Command Signals',
                     link: '/zh-hk/components/command-signals.md'

docs/.vitepress/src/zh-tw/sidebars.ts

@@ -26,6 +26,14 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Cache',
                     link: '/zh-tw/components/cache.md'
                 },
+                {
+                    text: 'Co-PHPUnit',
+                    link: '/zh-tw/components/co-phpunit.md'
+                },
+                {
+                    text: 'Command Benchmark',
+                    link: '/zh-tw/components/command-benchmark.md'
+                },
                 {
                     text: 'Command Signals',
                     link: '/zh-tw/components/command-signals.md'

docs/en/components/co-phpunit.md

@@ -0,0 +1,180 @@
+# Co-PHPUnit
+
+## Introduction
+
+`friendsofhyperf/co-phpunit` is a PHPUnit extension specifically designed for testing Hyperf applications and other Swoole-based frameworks, enabling tests to run inside Swoole coroutines.
+
+## Installation
+
+```bash
+composer require friendsofhyperf/co-phpunit --dev
+```
+
+## Why Co-PHPUnit?
+
+When testing Hyperf applications, many components rely on Swoole's coroutine context to function properly. Running tests in a traditional synchronous environment can lead to issues such as:
+
+- Coroutine context not being available
+- Timers and event loops not working correctly
+- Coordinator pattern failures
+- Database connection pool issues
+
+Co-PHPUnit solves these problems by automatically wrapping test execution in a Swoole coroutine context when needed.
+
+## Usage
+
+### Basic Usage
+
+Simply use the `RunTestsInCoroutine` trait in your test class:
+
+```php
+<?php
+
+namespace Your\Namespace\Tests;
+
+use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine;
+use PHPUnit\Framework\TestCase;
+
+class YourTest extends TestCase
+{
+    use RunTestsInCoroutine;
+
+    public function testSomething()
+    {
+        // Your test code here
+        // This will automatically run inside a Swoole coroutine
+    }
+}
+```
+
+### Disabling Coroutine for Specific Tests
+
+If you need to disable coroutine execution for a specific test class, set the `$enableCoroutine` property to `false`:
+
+```php
+<?php
+
+namespace Your\Namespace\Tests;
+
+use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine;
+use PHPUnit\Framework\TestCase;
+
+class YourTest extends TestCase
+{
+    use RunTestsInCoroutine;
+
+    protected bool $enableCoroutine = false;
+
+    public function testSomething()
+    {
+        // This test will run in normal synchronous mode
+    }
+}
+```
+
+## How It Works
+
+The `RunTestsInCoroutine` trait overrides PHPUnit's `runBare()` method to:
+
+1. **Check Prerequisites**: Verifies that the Swoole extension is loaded and not already in a coroutine context
+2. **Create Coroutine Context**: Wraps test execution in `Swoole\Coroutine\run()`
+3. **Exception Handling**: Properly captures and re-throws exceptions from within the coroutine
+4. **Cleanup**: Clears all timers and resumes coordinator on test completion
+5. **Fallback**: If conditions aren't met, falls back to normal test execution
+
+### PHPUnit Patch
+
+The package includes a `phpunit-patch.php` file that automatically removes the `final` keyword from PHPUnit's `TestCase::runBare()` method, allowing the trait to override it. This patch is applied automatically when the package is autoloaded.
+
+## Requirements
+
+- PHP >= 8.0
+- PHPUnit >= 10.0
+- Swoole extension (when running tests in coroutine mode)
+- Hyperf >= 3.1 (for coordinator functionality)
+
+## Configuration
+
+### Composer Autoload
+
+The package automatically registers its autoload files in composer.json:
+
+```json
+{
+    "autoload-dev": {
+        "psr-4": {
+            "Your\\Tests\\": "tests/"
+        },
+        "files": [
+            "vendor/friendsofhyperf/co-phpunit/phpunit-patch.php"
+        ]
+    }
+}
+```
+
+### PHPUnit Configuration
+
+No special PHPUnit configuration is required. The package works seamlessly with your existing `phpunit.xml` configuration.
+
+## Best Practices
+
+1. **Use for Integration Tests**: This is particularly useful for integration tests that interact with Hyperf's coroutine-aware components
+2. **Selective Enablement**: Not all tests need to run in coroutines. Use `$enableCoroutine = false` for unit tests that don't require coroutine context
+3. **Test Isolation**: The package automatically cleans up timers and coordinator state between tests
+4. **Performance**: Tests running in coroutines may have slightly different performance characteristics
+
+## Example: Testing Hyperf Services
+
+```php
+<?php
+
+namespace App\Tests;
+
+use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine;
+use Hyperf\Context\ApplicationContext;
+use PHPUnit\Framework\TestCase;
+
+class ServiceTest extends TestCase
+{
+    use RunTestsInCoroutine;
+
+    public function testServiceWithCoroutineContext()
+    {
+        // Get service from container
+        $service = ApplicationContext::getContainer()->get(YourService::class);
+
+        // Test methods that use coroutine context
+        $result = $service->asyncOperation();
+
+        $this->assertNotNull($result);
+    }
+
+    public function testDatabaseConnection()
+    {
+        // Test database operations that require connection pool
+        $result = Db::table('users')->first();
+
+        $this->assertIsArray($result);
+    }
+}
+```
+
+## Troubleshooting
+
+### Tests Hang or Timeout
+
+If tests hang, ensure that:
+- All async operations are properly awaited
+- No infinite loops exist in coroutine callbacks
+- Timers are cleared in test teardown
+
+### "Call to a member function on null"
+
+This usually indicates that coroutine context is not available. Ensure:
+- Swoole extension is installed and enabled
+- The `RunTestsInCoroutine` trait is included
+- `$enableCoroutine` is set to `true`
+
+### PHPUnit Version Compatibility
+
+The package supports PHPUnit 10.x, 11.x, and 12.x. Ensure your PHPUnit version is compatible.

docs/en/components/command-benchmark.md

@@ -0,0 +1,139 @@
+# Command Benchmark
+
+## Introduction
+
+`friendsofhyperf/command-benchmark` is a benchmark component for Hyperf commands, forked from [christophrumpel/artisan-benchmark](https://github.com/christophrumpel/artisan-benchmark). It helps you analyze command execution time, memory usage, and SQL query count.
+
+## Installation
+
+```shell
+composer require friendsofhyperf/command-benchmark
+```
+
+## Features
+
+This component automatically adds performance monitoring to all Hyperf commands through AOP aspects, without modifying existing code. It automatically tracks:
+
+- **Execution Time**: Total time from command start to finish
+- **Memory Usage**: Memory consumption during command execution
+- **SQL Query Count**: Total number of database queries executed during command execution
+
+## Usage
+
+### Basic Usage
+
+After installing the component, all Hyperf commands automatically get an `--enable-benchmark` option. Simply add this option when running a command to enable benchmarking:
+
+```shell
+php bin/hyperf.php your:command --enable-benchmark
+```
+
+### Example Output
+
+When benchmarking is enabled, performance statistics are displayed at the end of the output after command completion:
+
+```
+⚡ TIME: 1.23s  MEM: 2.45MB  SQL: 15 
+
+```
+
+Output explanation:
+- **TIME**: Command execution time (automatically formatted as minutes/seconds/milliseconds)
+- **MEM**: Memory usage (in MB)
+- **SQL**: Number of SQL queries executed
+
+## How It Works
+
+The component uses Hyperf's AOP (Aspect-Oriented Programming) functionality to intercept command execution:
+
+1. **Constructor Interception**: Records start time and memory usage when command is instantiated
+2. **Event Listening**: Listens for database query events to count SQL queries
+3. **Execution Interception**: Calculates performance metrics after command execution completes
+4. **Result Display**: Outputs benchmark results in a colored format
+
+### Time Formatting
+
+Execution time automatically selects the most appropriate unit based on actual duration:
+
+- **≥ 60 seconds**: Displayed as minutes and seconds (e.g., 2m 30s)
+- **≥ 1 second**: Displayed as seconds (e.g., 1.23s)
+- **< 1 second**: Displayed as milliseconds (e.g., 450ms)
+
+## Configuration
+
+This component works out of the box with no additional configuration needed. The `CommandAspect` aspect is automatically registered after installation.
+
+If you need to customize behavior, you can modify or extend the `FriendsOfHyperf\CommandBenchmark\Aspect\CommandAspect` class.
+
+## Examples
+
+### Analyzing Database Migration Commands
+
+```shell
+php bin/hyperf.php migrate --enable-benchmark
+```
+
+Output:
+```
+Migration table created successfully.
+⚡ TIME: 2.5s  MEM: 12.34MB  SQL: 48 
+```
+
+### Analyzing Custom Commands
+
+```shell
+php bin/hyperf.php app:process-data --enable-benchmark
+```
+
+Output:
+```
+Data processing completed.
+⚡ TIME: 15.2s  MEM: 45.67MB  SQL: 1024 
+```
+
+## Best Practices
+
+1. **Performance Optimization**: Use this component to identify slow-running commands and potential performance bottlenecks
+2. **SQL Optimization**: Monitor SQL query counts to identify N+1 query problems
+3. **Memory Monitoring**: Track memory usage to prevent memory leaks
+4. **Continuous Monitoring**: Use in CI/CD pipelines to ensure command performance doesn't degrade
+
+## Technical Implementation
+
+### Aspect Configuration
+
+```php
+<?php
+
+namespace FriendsOfHyperf\CommandBenchmark;
+
+class ConfigProvider
+{
+    public function __invoke()
+    {
+        return [
+            'aspects' => [
+                Aspect\CommandAspect::class,
+            ],
+        ];
+    }
+}
+```
+
+### Key Features
+
+- **WeakMap Storage**: Uses `WeakMap` to store command performance metrics, avoiding memory leaks
+- **Event-Driven**: Counts SQL queries by listening to `QueryExecuted` events
+- **Non-Invasive**: No need to modify existing command code
+- **Automatic Cleanup**: Performance data is automatically cleaned up after command execution
+
+## Notes
+
+- The component intercepts all command constructor and execution methods, but only displays results when using the `--enable-benchmark` option
+- SQL query statistics depend on Hyperf's database component; if database is not used, this metric will always show 0
+- Performance data is only displayed after command execution completes; real-time monitoring is not supported
+
+## References
+
+- Original Project: [christophrumpel/artisan-benchmark](https://github.com/christophrumpel/artisan-benchmark)
+- Hyperf AOP Documentation: [https://hyperf.wiki/3.1/#/en/aop](https://hyperf.wiki/3.1/#/en/aop)