diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 236986f5b..fb6af4b97 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -5,9 +5,10 @@ This repository contains a monorepo of popular components for the Hyperf PHP fra ## Project Overview - **Repository**: friendsofhyperf/components -- **Type**: Monorepo containing 50+ Hyperf components +- **Type**: Monorepo containing 49 Hyperf components - **PHP Version**: >=8.1 - **Framework**: Hyperf >=3.1.0 +- **Testing Framework**: Pest (PHPUnit under the hood) - **License**: MIT - **Main Author**: Deeka Wong (huangdijia@gmail.com) @@ -15,12 +16,16 @@ This repository contains a monorepo of popular components for the Hyperf PHP fra ``` / -├── bin/ # Utility scripts +├── bin/ # Utility scripts (split, docs, JSON normalization) ├── docs/ # Multi-language documentation (VitePress) -├── src/ # Component source code (50+ components) -├── tests/ # Test suites +├── src/ # Component source code (49 components) +├── tests/ # Pest test suites mirroring src/ structure +├── types/ # PHP stubs for type hints ├── composer.json # Main composer configuration -└── package.json # Documentation build configuration +├── package.json # Documentation translation scripts +├── AGENTS.md # Repository guidelines for AI agents +├── CLAUDE.md # Claude Code guidelines +└── .github/ # GitHub workflows and copilot instructions ``` ## Component Architecture @@ -39,14 +44,55 @@ src/{component-name}/ ``` ### Key Components Include: -- **Cache**: Enhanced caching functionality -- **Http Client**: HTTP client utilities -- **Elasticsearch**: Elasticsearch integration -- **Notification**: Multi-channel notifications -- **Model Factory**: Database model factories -- **Telescope**: Application debugging and monitoring -- **Tinker**: Interactive REPL -- **Validation**: Enhanced validation features + +**Development Tools:** +- **telescope**: Application debugging and monitoring +- **tinker**: Interactive REPL +- **ide-helper**: IDE auto-completion support +- **pretty-console**: Enhanced console output +- **web-tinker**: Web-based REPL interface + +**Database & Models:** +- **model-factory**: Database model factories +- **model-observer**: Model event observers +- **model-scope**: Query scopes for models +- **model-hashids**: Hashids for model IDs +- **fast-paginate**: Optimized pagination +- **compoships**: Multi-column relationships +- **mysql-grammar-addon**: MySQL grammar extensions + +**Caching & Storage:** +- **cache**: Enhanced caching functionality +- **lock**: Distributed locking +- **redis-subscriber**: Redis pub/sub support + +**HTTP & API:** +- **http-client**: HTTP client utilities +- **oauth2-server**: OAuth2 server implementation +- **openai-client**: OpenAI API client + +**Notifications & Mail:** +- **notification**: Multi-channel notifications +- **notification-mail**: Email notifications +- **notification-easysms**: SMS notifications via EasySms +- **mail**: Email sending functionality + +**Search:** +- **elasticsearch**: Elasticsearch integration +- **telescope-elasticsearch**: Telescope with Elasticsearch storage + +**Security:** +- **encryption**: Encryption utilities +- **purifier**: HTML purification +- **recaptcha**: Google reCAPTCHA integration +- **validated-dto**: Data transfer object validation + +**Infrastructure:** +- **confd**: Configuration from external sources +- **config-consul**: Consul configuration center +- **facade**: Laravel-style facades +- **sentry**: Sentry error tracking integration +- **ipc-broadcaster**: Inter-process communication ## Development Conventions @@ -64,11 +110,15 @@ Each component typically includes a `ConfigProvider.php` file that defines: - Follows PSR-12 coding standards - Uses PHP-CS-Fixer for code formatting (`.php-cs-fixer.php`) - PHPStan for static analysis (`phpstan.neon.dist`) +- All files include `declare(strict_types=1)` +- 4-space indentation, short array syntax ### Testing -- Uses PHPUnit for testing (`phpunit.xml.dist`) -- Test files located in `tests/` directory -- Follows Hyperf testing patterns +- Uses Pest testing framework (`phpunit.xml.dist`) +- Test files located in `tests/` directory mirroring `src/` structure +- Tests are grouped by component using `->group()` modifier +- Run specific component tests with `--group` flag +- Follows AAA pattern (Arrange, Act, Assert) ## Documentation Structure @@ -87,17 +137,25 @@ Documentation is available in multiple languages: ## Build and Deployment ### Scripts Available: +- `bin/regenerate-readme.sh` - Generate component README files - `bin/generate-repository-doc.sh` - Generate component documentation - `bin/doc-translate` - PHP-based translation script -- `bin/doc-translate.github-model.js` - AI-powered translation +- `bin/doc-translate.js` - Node.js AI-powered translation +- `bin/doc-translate.github-model.js` - GitHub model translation - `bin/split-docs.sh` - Deploy documentation to separate repository +- `bin/split.sh` - Split components to individual repositories +- `bin/composer-json-fixer` - Fix component composer.json files +- `bin/pending-repositories.sh` - Check pending repository changes +- `bin/pending-composer-json` - Check pending composer.json changes ### GitHub Actions: -- `tests.yaml` - Run test suite +- `tests.yaml` - Run test suite (lint, unit, type coverage) - `docs-split.yaml` - Deploy documentation - `docs-translate.yaml` - Auto-translate documentation - `release.yaml` - Handle releases - `split.yaml` - Split components to individual repositories +- `update-changelog.yml` - Update changelog +- `cnb.yaml` - CNB workflow ## Development Workflow @@ -119,6 +177,9 @@ Documentation is available in multiple languages: ### Configuration Provider Template: ```php [], - 'commands' => [], - 'listeners' => [], - 'annotations' => [ + 'dependencies' => [], // DI container bindings + 'commands' => [], // Console commands + 'listeners' => [], // Event listeners + 'aspects' => [], // AOP aspects + 'annotations' => [ // Annotation scanning 'scan' => [ 'paths' => [ __DIR__, ], ], ], + 'publish' => [], // Publishable assets ]; } } @@ -167,11 +230,13 @@ class ConfigProvider ## Common Dependencies The project commonly uses: -- Hyperf framework components -- Symfony components for console, HTTP foundation -- Laravel components for certain utilities -- Guzzle for HTTP clients +- Hyperf framework components (hyperf/framework, hyperf/di, hyperf/command, etc.) +- Symfony components (console, http-foundation, process, var-dumper, uid) +- Laravel utilities (serializable-closure) - Carbon for date/time handling +- Guzzle for HTTP operations (via hyperf/guzzle) +- Ramsey UUID for UUID generation +- PSR interfaces for interoperability ## Installation Instructions @@ -187,10 +252,27 @@ composer require friendsofhyperf/components ## Testing Conventions +- Use Pest for all new tests - Test files should be in `tests/` directory -- Use Hyperf testing utilities +- Tests are grouped by component (e.g., `->group('telescope')`) +- Use descriptive test names and data providers +- Keep unit tests deterministic (no network calls) - Mock external dependencies appropriately - Follow AAA pattern (Arrange, Act, Assert) +- Run `composer test:types` to ensure type coverage + +### Running Specific Tests: +```bash +# Run tests for a specific component +vendor/bin/pest --group=telescope +vendor/bin/pest --group=http-client + +# Run a specific test file +vendor/bin/pest tests/HttpClient/PendingRequestTest.php + +# Run a specific test method +vendor/bin/pest --filter=test_method_name +``` ## Documentation Standards @@ -208,6 +290,13 @@ composer require friendsofhyperf/components 5. Update documentation 6. Submit pull request +### Commit Convention +Use Conventional Commits format: +- `feat(cache): add redis tagging` +- `fix(tinker): handle empty input` +- `docs(telescope): update installation guide` +- `refactor(http-client): simplify retry logic` + ## Deployment and Release - Components are split into individual repositories @@ -221,6 +310,25 @@ When working with this codebase, prioritize: 3. Comprehensive documentation 4. Test coverage 5. Performance considerations for framework components +6. Coroutine safety (Swoole/Swow compatibility) + +## Coroutine Safety + +All code must be coroutine-safe. Avoid: +- Global state without proper context management +- Blocking I/O operations +- Non-coroutine-safe third-party libraries without wrappers + +Use Hyperf's context API for request-scoped data: +```php +use Hyperf\Context\Context; + +// Store in context +Context::set('key', $value); + +// Retrieve from context +Context::get('key'); +``` ## Working with the Codebase @@ -238,11 +346,13 @@ However, if some tool calls depend on previous calls to inform dependent values ### Testing Strategy - Run existing tests before making changes to understand baseline -- Create focused tests for new functionality -- Use PHPUnit following Hyperf testing patterns -- Mock external dependencies appropriately +- Create focused tests for new functionality using Pest +- Use Pest's `uses()` helper to apply base test case +- Group tests by component using `->group()` modifier +- Mock external dependencies appropriately (ValidatorFactory, ConfigInterface, etc.) - Run tests iteratively after each change - Don't remove or edit unrelated tests +- Ensure `composer test:types` stays green before pushing ### Error Handling - Check for and handle PHP errors appropriately @@ -261,13 +371,20 @@ However, if some tool calls depend on previous calls to inform dependent values ### Build and Test Commands Common commands for this repository: -- `composer install` - Install PHP dependencies -- `composer test` - Run all tests (lint, unit, types) -- `composer cs-fix` - Run PHP-CS-Fixer -- `composer analyse` - Run PHPStan analysis +- `composer install` - Install PHP dependencies (requires PHP ≥8.1) +- `composer test` - Run all tests (lint, unit, type coverage) +- `composer test:unit` - Run Pest unit tests only +- `composer test:lint` - Run PHP-CS-Fixer checks (dry run) +- `composer test:types` - Run type coverage analysis +- `composer cs-fix` - Auto-fix code style issues +- `composer analyse` - Run PHPStan static analysis +- `composer analyse:types` - Run stricter type analysis +- `composer json-fix` - Normalize composer.json files +- `composer gen:readme` - Generate README files - `cd docs && pnpm install` - Install documentation dependencies - `cd docs && pnpm run docs:dev` - Run documentation dev server - `cd docs && pnpm run docs:build` - Build documentation +- `npm run docs:translate` - Translate documentation (from root) ### Reporting Progress - Use `report_progress` early to outline your plan