README

中文说明

A monorepo of 48 independently installable components for Hyperf 3.2 and later.

Requirements

• PHP 8.2 or later
• Hyperf 3.2 or later
• Swoole or Swow, when required by the application or component

Each component declares its exact dependencies in src/<component>/composer.json.

Installation

Install the complete collection:

composer require friendsofhyperf/components

Or install only the components your application needs:

composer require friendsofhyperf/telescope
composer require friendsofhyperf/http-client
composer require friendsofhyperf/model-factory --dev

Most framework-integrated packages are discovered through their ConfigProvider. Some components also publish configuration or resources:

php bin/hyperf.php vendor:publish friendsofhyperf/<component>

Consult the component README and documentation before publishing files; not every component provides publishable resources.

Components

Development and Debugging

• telescope - request, exception, SQL, Redis, and runtime inspection
• tinker - interactive REPL
• web-tinker - browser-based Tinker interface
• ide-helper - IDE metadata generation
• pretty-console - improved console presentation

Database and Models

• model-factory, model-observer, model-scope, model-hashids, and model-morph-addon
• compoships, fast-paginate, mysql-grammar-addon, and trigger

Infrastructure and Integrations

• Cache and coordination: cache, lock, and redis-subscriber
• HTTP and APIs: http-client and oauth2-server
• Messaging: notification, notification-mail, notification-easysms, mail, and tcp-sender
• External services: elasticsearch, telescope-elasticsearch, openai-client, recaptcha, and sentry
• Configuration: confd and config-consul

Framework Extensions

• Commands: command-benchmark, command-signals, command-validation, and console-spinner
• Architecture: facade, ipc-broadcaster, and exception-event
• Security and validation: encryption, purifier, rate-limit, validated-dto, and grpc-validation
• Shared utilities: helpers, support, and macros
• Queue and testing: amqp-job and co-phpunit

Every component directory contains its own package metadata and README. The complete list is available under src/.

Documentation

The documentation site is available in four languages:

• Simplified Chinese
• Traditional Chinese
• Hong Kong Traditional Chinese
• English

Component documentation is maintained under docs/<locale>/components/. Component READMEs and documentation pages are separate sources, so behavior changes may require updates to both.

Repository Layout

src/<component>/        independently installable component packages
tests/<Component>/      shared Pest test suite
docs/<locale>/          VitePress documentation in four languages
types/                  PHP stubs checked at PHPStan max level
bin/                    repository maintenance, split, and release scripts

The root package aggregates all components. Most components integrate with Hyperf through a ConfigProvider; a small number are framework-independent libraries.

Development

Install dependencies from the repository root:

composer install

Run the standard local checks:

composer test          # code style, Pest tests, and type coverage
composer analyse       # PHPStan analysis
composer analyse:types # PHPStan max-level analysis for types/

Run focused checks while developing a component:

vendor/bin/pest --group cache
vendor/bin/pest tests/CoPhpunit
composer analyse src/cache
composer cs-fix -- src/cache

Pest groups are defined in tests/Pest.php. Not every component has a group, so use a test directory or file when necessary. composer test does not run PHPStan; run composer analyse separately before submitting code changes.

For documentation changes:

npm install
npm run docs:check

Simplified Chinese is the translation source. Keep the page set and heading structure synchronized across en, zh-cn, zh-hk, and zh-tw, then review generated translations before submission. npm run docs:translate modifies translated files and requires translation service configuration; run it only when intentionally regenerating translations.

Contributing

Read CONTRIBUTE.md and AGENTS.md before making changes.

• Treat component source and tests as the authority for documented behavior.
• Update tests when public behavior changes.
• Update the component README and documentation snippets when they are affected.
• Keep changes scoped; do not edit generated or unrelated files without a reason.
• Run targeted checks first, followed by the relevant repository-level checks.
• Use Conventional Commits, scoped to a component when possible.

Release Model

This monorepo is the source of truth. Maintenance workflows split src/<component> into individual friendsofhyperf/<component> repositories, and releases apply a shared version tag across the monorepo and component repositories.

The split and release scripts force-push or tag remote repositories. They are maintainer-only operations and should not be run during normal development.

Community

• Documentation
• GitHub Issues
• CNB Mirror
• Contributors

License

FriendsOfHyperf Components is open-sourced software licensed under the MIT License.