 |
VOOZH | about |
|
VOOZH | about |
The friendsofhyperf/components repository is a monorepo containing 50+ production-ready components that extend the Hyperf framework. Each component is independently usable and provides specific functionality ranging from observability tools (Sentry, Telescope) to developer utilities (Tinker, IDE Helper) to infrastructure services (cache, locks, messaging). The repository uses Composer's replace mechanism to enable both full-suite and granular component installation while maintaining shared versioning and development infrastructure.
This page provides a high-level understanding of the monorepo architecture, component organization, installation patterns, and foundational design principles. For detailed information about specific component categories, see Component Catalog. For installation procedures and version requirements, see Installation and Setup.
The monorepo employs Composer's replace mechanism to publish individual components while maintaining a single codebase. The root composer.json119-168 defines all 48 component packages in its replace section, allowing users to install either friendsofhyperf/components (full suite) or individual packages like friendsofhyperf/sentry.
Sources: composer.json1-330 README.md14-17
The root package maps each component namespace to its source directory via PSR-4 autoloading composer.json172-221 For example, FriendsOfHyperf\Sentry\ maps to src/sentry/src/. Each component additionally includes a ConfigProvider class registered in composer.json255-299 which Hyperf's component scanner discovers automatically at application boot to register services, listeners, and middleware.
Individual components maintain their own composer.json with specific dependencies. For instance, src/sentry/composer.json24-38 requires sentry/sentry: ^4.19.0 and suggests optional packages like hyperf/amqp for AMQP tracing. This ensures that installing a single component pulls only its required dependencies rather than the entire monorepo's dependency tree.
Sources: src/sentry/composer.json1-69 composer.json44-118
Components are organized into functional categories that align with typical application development needs. The following table maps category names to their constituent components and primary use cases:
| Category | Components | Primary Purpose |
|---|---|---|
| Observability | sentry, telescope, telescope-elasticsearch | Error tracking, APM, debug assistant with scalable storage |
| Developer Tools | tinker, web-tinker, ide-helper, co-phpunit, command-benchmark | Interactive REPL, code intelligence, coroutine testing, profiling |
| Core Utilities | support, helpers, macros, facade | Foundation layer, global functions, class extensions, static proxies |
| Communication | http-client, mail, notification, notification-mail, notification-easysms, tcp-sender | HTTP requests, email, multi-channel notifications, TCP messaging |
| Data & Storage | cache, lock, trigger, fast-paginate, elasticsearch | Caching API, distributed locks, binlog CDC, optimized pagination |
| Database Models | model-factory, model-observer, model-scope, model-hashids, compoships, mysql-grammar-addon | Testing fixtures, observers, scopes, Hashids, multi-column relations |
| Validation & Security | validated-dto, rate-limit, encryption, purifier, recaptcha, grpc-validation | DTOs, traffic control, crypto, HTML sanitization, CAPTCHA |
| Messaging & Queues | amqp-job, dispatch system | AMQP job queue, unified job dispatch API |
| Configuration | config-consul, confd | Dynamic config from Consul, confd integration |
Sources: README.md65-161 composer.json119-168
All components follow the naming pattern friendsofhyperf/[component-name] in Packagist, map to namespace FriendsOfHyperf\[ComponentName]\ in code, and reside in directory src/[component-name]/ in the monorepo. For example:
friendsofhyperf/http-clientFriendsOfHyperf\Http\Client\src/http-client/Sources: composer.json172-221
The friendsofhyperf/support component serves as the foundation layer that most other components depend on, providing common utilities, dispatch abstractions, and backoff strategies.
Sources: src/support/composer.json1-62 composer.json172-221 src/support/README.md1-282
The support package src/support/composer.json22-34 depends only on Hyperf core packages (hyperf/di, hyperf/context, hyperf/macroable, etc.), making it a stable foundation. It provides:
dispatch() function src/support/README.md26-166 with fluent API for AsyncQueue, AMQP, and KafkaBackoffInterface implementations including ArrayBackoff src/support/src/Backoff/ArrayBackoff.php1-155PendingAsyncQueueDispatch, PendingAmqpProducerMessageDispatch, PendingKafkaProducerMessageDispatchAll components use Hyperf\Context\Context for coroutine-safe state storage. The Sentry component exemplifies this pattern with SingletonAspect and SentrySdk override to ensure Sentry Hub instances are stored per-coroutine context rather than as static singletons.
Sources: Diagram 2 (Sentry Integration Architecture), src/support/composer.json24
Every component implements a ConfigProvider class that Hyperf's scanner automatically discovers and invokes during bootstrap. This enables zero-configuration installation for most components.
Sources: composer.json254-301 src/sentry/composer.json64-66
The root composer.json255-299 declares all ConfigProvider classes in its extra.hyperf.config array. For example, line 291 registers FriendsOfHyperf\Sentry\ConfigProvider. When Hyperf boots, it invokes each ConfigProvider::__invoke() method, which returns arrays for:
dependencies: Service bindings for DI containerlisteners: Event listeners to registeraspects: AOP aspects for method interceptionpublish: Configuration files to copy via vendor:publish commandcommands: Console commands to registerThis pattern eliminates the need for manual service provider registration in most cases. Components requiring configuration files (like Sentry) use the publish array, and users run php bin/hyperf.php vendor:publish friendsofhyperf/[component] to copy defaults to config/autoload/.
Sources: composer.json254-301 Diagram 1 (Monorepo Architecture)
The monorepo supports two installation approaches:
Installs all 48 components simultaneously. The root composer.json composer.json16-42 declares all shared dependencies (e.g., sentry/sentry, psy/psysh), ensuring compatibility across the entire suite.
Sources: README.md36-40 README_CN.md38-40
Installs only the specified component and its dependencies. Each component's composer.json declares precise requirements. For example, telescope does not pull in Sentry dependencies unless explicitly required.
Sources: README.md42-55 src/sentry/composer.json24-47
All components maintain version parity using the constraint ~3.1.0 for Hyperf dependencies composer.json50-98 The root package uses replace: "*" composer.json119-168 to indicate that installed version of the full suite satisfies any component requirement. Individual component packages published to Packagist carry semantic versions (e.g., v3.1.78) aligned with the monorepo release tags CHANGELOG-3.1.md1-10
Sources: composer.json119-168 CHANGELOG-3.1.md1-39
Two components act as cross-cutting concerns that monitor other components' operations:
The sentry component src/sentry/composer.json1-69 uses AOP aspects to instrument database queries, Redis commands, HTTP requests, and message queue operations. It stores Hub instances in Hyperf\Context\Context via SingletonAspect to ensure coroutine safety.
Sources: Diagram 2 (Sentry Integration Architecture), src/sentry/composer.json24-47
The telescope component provides a web UI for inspecting requests, queries, Redis commands, and exceptions. It offers two storage backends: database (default) and Elasticsearch via telescope-elasticsearch component.
Sources: Diagram 1 (Monorepo Architecture - Observability Stack), README.md69
| Requirement | Version Constraint |
|---|---|
| PHP | >= 8.1 |
| Hyperf | ~3.1.0 |
| Swoole | 5.1.8, 6.0.2, or 6.1.3 (tested) |
| Composer | ^2.0 |
The CI/CD pipeline tests 9 combinations (3 PHP versions × 3 Swoole versions) to ensure broad compatibility tests/Pest.php1-98
Sources: composer.json17 README.md29-32 Diagram 6 (Development and Testing Infrastructure)
The monorepo includes comprehensive development tooling:
co-phpunit for coroutine-safe testing tests/Pest.php18-58Sources: composer.json302-329 README.md188-208 Diagram 6 (Development and Testing Infrastructure)
Refresh this wiki