 |
VOOZH | about |
|
VOOZH | about |
This document describes the dependency hierarchy and layered architecture of the friendsofhyperf/components monorepo. It explains how the 50+ components are organized into layers, how they depend on each other, and their relationship with core Hyperf framework packages. This page focuses on the structural organization and dependency flow; for details on specific components, see Component Catalog, and for installation patterns, see Installation and Setup.
The friendsofhyperf/components monorepo follows a clear layered architecture where components are organized into distinct layers based on their role and dependencies. Each layer builds upon the layers beneath it, creating a stable dependency hierarchy.
Layer Responsibilities:
| Layer | Purpose | Examples | Key Classes/Functions |
|---|---|---|---|
| Application | User code consuming component APIs | Controllers, services, commands | N/A (user code) |
| Convenience | Laravel-style ergonomic APIs | Http::get(), cache(), dispatch() | src/helpers/src/Functions.php, RequestMixin |
| Feature | Domain-specific functionality | HTTP client, validation, caching | PendingRequest, CacheManager, LockManager |
| Observability | Cross-cutting monitoring/debugging | Sentry APM, Telescope | Tracer, EventHandleListener, aspects |
| Foundation | Shared utilities and patterns | Support classes, dispatch system | FriendsOfHyperf\Support\* |
| Hyperf Core | Framework primitives | DI container, coroutine context | Container, Context, EventDispatcherInterface |
Sources: composer.json1-333 composer.json171-221 src/helpers/composer.json22-42 </old_str>
<new_str>
The friendsofhyperf/components monorepo follows a clear layered architecture where components are organized into distinct layers based on their role and dependencies. Each layer builds upon the layers beneath it, creating a stable dependency hierarchy.
Layer Responsibilities:
| Layer | Purpose | Examples | Key Classes/Functions |
|---|---|---|---|
| Application | User code consuming component APIs | Controllers, services, commands | N/A (user code) |
| Convenience | Laravel-style ergonomic APIs | Http::get(), cache(), dispatch() | src/helpers/src/Functions.php, RequestMixin |
| Feature | Domain-specific functionality | HTTP client, validation, caching | PendingRequest, CacheManager, LockManager |
| Observability | Cross-cutting monitoring/debugging | Sentry APM, Telescope | Tracer, EventHandleListener, aspects |
| Foundation | Shared utilities and patterns | Support classes, dispatch system | FriendsOfHyperf\Support\* |
| Hyperf Core | Framework primitives | DI container, coroutine context | Container, Context, EventDispatcherInterface |
Sources: composer.json1-333 composer.json171-221 src/helpers/composer.json22-42
Components in the monorepo are categorized by their intended use case, affecting how they should be installed and whether they are required in production.
Installation Patterns:
| Component Type | Composer Flag | Example | Purpose |
|---|---|---|---|
| Runtime | (none) | composer require friendsofhyperf/sentry | Production features |
| Development | --dev | composer require --dev friendsofhyperf/telescope | Debugging, testing |
| Optional | (none) + suggests | See component's suggest section | Feature extensions |
Example from README:
README.md47-55 demonstrates the pattern:
Sources: README.md34-64 composer.json44-118
The friendsofhyperf/support component serves as the foundational layer for most components in the monorepo. It provides common utilities, traits, and abstractions that other components build upon.
Version Constraint Pattern:
The support component uses the tilde operator (~) for version constraints:
| Component | Support Version | Meaning |
|---|---|---|
| sentry | ~3.1.61 | >= 3.1.61, < 3.2.0 |
| http-client | ~3.1.61 | >= 3.1.61, < 3.2.0 |
| helpers | ~3.1.61 | >= 3.1.61, < 3.2.0 |
| macros | ~3.1.61 | >= 3.1.61, < 3.2.0 |
| facade | ~3.1.73 | >= 3.1.73, < 3.2.0 |
The ~ operator means "allow patch-level changes" - the rightmost digit can increment, but the minor version (3.1) is locked.
Sources: src/sentry/composer.json25 src/macros/composer.json23 src/helpers/composer.json24 src/http-client/composer.json23 src/facade/composer.json23
While the exact contents of the support component are not shown in the provided files, based on dependency patterns, it provides:
Feature components provide specific functionality and can depend on:
friendsofhyperf/support foundation layerDependency Examples:
| Component | Direct Dependencies (friendsofhyperf) | Core Hyperf Dependencies |
|---|---|---|
sentry | support ~3.1.61 | di, context, event, framework |
helpers | macros ~3.1.0, support ~3.1.61 | context, macroable, stringable |
http-client | support ~3.1.61 | guzzle, coroutine, macroable |
facade | support ~3.1.73 | di, context |
lock | (none) | config, context, macroable |
Sources: src/sentry/composer.json24-37 src/helpers/composer.json22-42 src/http-client/composer.json22-32 src/facade/composer.json22-26 src/lock/composer.json22-34
All components follow Hyperf's ConfigProvider pattern for automatic registration. The system uses Composer's extra section to declare configuration classes that are automatically discovered and invoked during framework bootstrap.
ConfigProvider Discovery Flow:
Root ConfigProvider Registry:
The root composer.json257-302 declares all 42 ConfigProvider classes:
Individual Component ConfigProvider:
Each component declares its own ConfigProvider for standalone installation. Example from src/sentry/composer.json60-67:
ConfigProvider Methods:
Each ConfigProvider class typically implements:
__invoke(): Returns configuration arraydependencies: DI container bindingslisteners: Event listener registrationsaspects: AOP aspect registrationscommands: Console command registrationsannotations: Annotation scanner configurationsSources: composer.json256-303 src/sentry/composer.json60-67 src/macros/composer.json48-55 src/cache/composer.json42-47
The convenience layer provides Laravel-style ergonomic APIs over Hyperf's services. It consists of three interdependent components that enable fluent, expressive code without sacrificing the underlying coroutine-safe architecture.
Dependency Chain:
helpers (line src/helpers/composer.json23) depends on macros ~3.1.0helpers (line src/helpers/composer.json24) depends on support ~3.1.61macros (line src/macros/composer.json23) depends on support ~3.1.61macros (line src/macros/composer.json25) depends on hyperf/macroable ~3.1.0facade (line src/facade/composer.json23) depends on support ~3.1.73Global Function Autoloading:
The root composer.json222-237 registers function files via Composer's files autoload mechanism:
These files are automatically loaded before any code executes, making functions like di(), app(), cache(), and dispatch() available globally.
Macro Extension Pattern:
Components like RequestMixin use Hyperf's Macroable trait to inject methods into framework classes at runtime, avoiding inheritance and maintaining coroutine safety.
Sources: composer.json222-237 src/helpers/composer.json22-42 src/macros/composer.json22-39 src/facade/composer.json22-42
Observability components (Sentry and Telescope) differ from feature components in that they instrument and monitor other components via aspect-oriented programming rather than being directly consumed by application code. They have no compile-time circular dependencies but dynamically intercept method calls.
Sentry Required Dependencies:
From src/sentry/composer.json24-38:
Optional Dependencies for Instrumentation:
Sentry uses suggest (lines src/sentry/composer.json39-47) to declare optional targets:
| Suggested Package | Purpose | Aspect Class |
|---|---|---|
elasticsearch/elasticsearch | Elasticsearch tracing | ElasticsearchRequestAspect |
hyperf/amqp | AMQP message tracing | AmqpProducerAspect |
hyperf/crontab | Cron job monitoring | TracingCrontabListener |
hyperf/database | SQL query tracing | DbConnectionAspect |
hyperf/engine | Coroutine engine | CoroutineAspect |
hyperf/rpc-multiplex | RPC tracing | RpcAspect |
phpmyadmin/sql-parser | SQL parsing utility | SqlParser class |
SQL Parser Usage:
The src/sentry/src/Util/SqlParser.php20-65 class demonstrates conditional dependency:
This pattern allows Sentry to function without phpmyadmin/sql-parser but gain enhanced SQL parsing capabilities when it's installed.
Sources: src/sentry/composer.json24-47 src/sentry/src/Util/SqlParser.php20-65
All friendsofhyperf components ultimately depend on core Hyperf framework packages. The most common dependencies are:
Dependency Frequency:
| Hyperf Package | Usage Count (in sample) | Purpose |
|---|---|---|
hyperf/di | 8/12 | Dependency injection and aspect-oriented programming |
hyperf/context | 10/12 | Coroutine-safe state management |
hyperf/support | 9/12 | Base utilities and helpers |
hyperf/macroable | 6/12 | Enable class extension via macros |
hyperf/stringable | 6/12 | Fluent string manipulation |
Sources: src/sentry/composer.json26-35 src/helpers/composer.json25-30 src/lock/composer.json23-28 src/http-client/composer.json25-32 src/facade/composer.json24-25
The monorepo uses consistent version constraints across components:
Root Dependencies:
composer.json16-42 defines minimum versions:
"php": ">=8.1"^2.0 || ^3.0)Component Dependencies:
All components require Hyperf ~3.1.0, which means:
This constraint appears consistently in src/sentry/composer.json26-33 src/lock/composer.json23-28 and other component files.
Sources: composer.json16-42 src/sentry/composer.json26-33 src/lock/composer.json23-28
The monorepo uses PSR-4 autoloading with a clear namespace-to-directory mapping:
Autoloading Configuration:
From composer.json171-221:
Pattern:
FriendsOfHyperf\{ComponentName}\src/{component-name}/src/Sources: composer.json171-221
The root composer.json119-168 uses the replace section to define all component packages:
Purpose:
friendsofhyperf/components as a single packagefriendsofhyperf/sentry)Components use the suggest section in composer.json to declare optional dependencies that unlock additional features without being required for basic functionality. This enables progressive feature adoption and keeps the dependency footprint minimal.
Optional Dependency Pattern:
Sentry Optional Dependencies (src/sentry/composer.json39-47):
Helpers Optional Dependencies (src/helpers/composer.json32-42):
Lock Optional Dependencies (src/lock/composer.json30-34):
Facade Optional Dependencies (src/facade/composer.json27-42):
This pattern allows components to provide integrations with 12+ framework subsystems while maintaining a lean core dependency set.
Sources: src/sentry/composer.json39-47 src/helpers/composer.json32-42 src/lock/composer.json30-34 src/facade/composer.json27-42
When to use: Development, prototyping, comprehensive feature set
When to use: Production, minimal footprint, specific features only
Sources: README.md34-55 composer.json119-168
The layered architecture prevents circular dependencies through strict dependency direction rules:
Rules:
Exception: Observability components (Sentry, Telescope) instrument other layers via aspect-oriented programming, but this is not a compile-time dependency.
Sources: System architecture diagrams, src/helpers/composer.json22-24 src/macros/composer.json22-29
The friendsofhyperf/components monorepo implements a disciplined layered architecture:
friendsofhyperf/support): Provides common utilities and abstractionsThis architecture enables:
~3.1.0 constrainthyperf/context used extensivelySources: composer.json1-330 System architecture diagrams
Refresh this wiki