Monorepo Architecture and Component Registry

Purpose and Scope

This document explains the technical architecture of the friendsofhyperf/components monorepo, focusing on how Composer's replace directive enables a single package to provide 50+ individual components, how PSR-4 autoloading maps namespaces to source directories, and how the ConfigProvider pattern integrates components into the Hyperf framework. For information about the specific components available, see Component Catalog. For installation procedures, see Installation and Setup.

---

Monorepo Directory Structure

The repository organizes all components under a unified src/ directory, with each component maintaining its own namespace, source code, tests, and metadata:

Each component directory contains:

• src/ - Implementation code following PSR-4 conventions
• composer.json - Component-specific metadata and dependencies
• publish/ (optional) - Configuration templates for vendor:publish command

Sources: composer.json1-334 README.md14-16

---

The Replace Directive Strategy

Mechanism

The root composer.json uses Composer's replace directive to declare that installing friendsofhyperf/components satisfies the dependency requirements for all individual components:

Implementation

The replace block declares wildcards for all component versions, allowing any version requirement to be satisfied:

This enables three installation patterns:

Pattern	Command	Result
Complete Suite	composer require friendsofhyperf/components	All 50+ components available
Individual Component	composer require friendsofhyperf/sentry	Only Sentry and its dependencies
Mixed	Both commands used	Complete suite takes precedence

When a user requires an individual component (e.g., friendsofhyperf/sentry), Composer resolves it separately. When they require the main package, Composer installs once but marks all individual packages as satisfied.

Sources: composer.json119-168 README.md36-55

---

PSR-4 Autoloading Configuration

Namespace-to-Directory Mapping

The root composer.json defines PSR-4 autoloading rules that map each component's namespace to its source directory:

Configuration Structure

The autoload configuration follows a consistent pattern for all 50+ components:

Key Details:

• Namespace Root: All components use FriendsOfHyperf\ as the vendor namespace
• Component Namespace: Each component adds its own sub-namespace (e.g., Sentry, Cache)
• Path Pattern: src/{component-name}/src/ - double src/ is intentional
• Function Files: Global helper functions are loaded via the files array

Sources: composer.json171-238

---

Example Class Resolution

When PHP encounters new \FriendsOfHyperf\Sentry\Tracer():

1. Composer autoloader matches namespace FriendsOfHyperf\Sentry\ to src/sentry/src/
2. Class name Tracer maps to file src/sentry/src/Tracer.php
3. Full path: src/sentry/src/Tracer.php

For \FriendsOfHyperf\Http\Client\PendingRequest:

1. Namespace FriendsOfHyperf\Http\Client\ → src/http-client/src/
2. Class PendingRequest → src/http-client/src/PendingRequest.php

Sources: composer.json172-221

---

ConfigProvider Registration Pattern

Hyperf Discovery Mechanism

Hyperf uses Composer's extra metadata to discover component configurations. The root package declares all ConfigProvider classes in a single registry:

Registration Array

The extra.hyperf.config array lists all ConfigProvider classes that Hyperf should load:

During application bootstrap, Hyperf:

1. Reads extra.hyperf.config from all installed packages
2. Instantiates each ConfigProvider class
3. Calls the __invoke() method to retrieve configuration arrays
4. Merges configurations into the application's dependency injection container

Sources: composer.json256-303

---

ConfigProvider Structure

Each component defines its ConfigProvider class following a standard pattern:

Example: Sentry ConfigProvider

The Sentry component's ConfigProvider demonstrates the full registration pattern:

Registration Type	Purpose	Examples
dependencies	DI container bindings	ClientBuilderInterface → ClientBuilderFactory
listeners	Event subscribers	EventHandleListener, TracingAmqpListener
aspects	AOP method interceptors	DbConnectionAspect, RedisConnectionAspect
commands	Console commands	TestCommand, PublishCommand
annotations	Custom annotation handlers	scan.paths, scan.collectors
publish	Configuration files	sentry.php template

Sources: src/sentry/composer.json60-67 composer.json294

---

Component Dependency Graph

Components can depend on each other, forming a layered architecture:

Dependency Declaration Patterns

Components declare dependencies in their individual composer.json files:

Required Dependencies (must be installed):

Suggested Dependencies (optional, enables features):

Sources: src/helpers/composer.json22-31 src/cache/composer.json30-34 src/sentry/composer.json39-47

---

Installation Resolution Flow

Complete Suite Installation

When a user installs the main package:

Individual Component Installation

When installing a single component without the main package:

Note: Individual component packages are published separately via subtree splits during releases. See Monorepo Management for details on the split process.

Sources: README.md36-55 composer.json119-168

---

Component Metadata Consistency

Each component maintains its own composer.json that mirrors key information from the root package:

Field	Purpose	Consistency Rule
name	Package identifier	Must match replace key in root
version	Not specified	Inherited from git tags
extra.branch-alias	Development branch mapping	Always "3.1-dev"
extra.hyperf.config	ConfigProvider class	Must exist if component has registration logic
require	Dependencies	Can reference other components or Hyperf packages
suggest	Optional features	Documents optional integrations

Example Comparison

Root composer.json:

src/sentry/composer.json:

Sources: composer.json119-168 composer.json258-302 src/sentry/composer.json1-68

---

Function Autoloading

Components can provide global helper functions via the files autoload directive. These files are loaded immediately when Composer's autoloader initializes:

The root composer.json lists all function files:

These functions become globally available without explicit imports:

Sources: composer.json222-237 src/helpers/composer.json48-51

---

Testing and Development Configuration

The monorepo maintains shared test infrastructure while allowing component-specific tests:

The root composer.json includes all development dependencies needed across components:

Sources: composer.json44-118

---

Summary

The monorepo architecture achieves several goals through its design:

Goal	Mechanism
Unified Distribution	Single composer require installs all components via replace directive
Individual Flexibility	Each component can be installed separately with its own dependency tree
Automatic Discovery	Hyperf scans extra.hyperf.config to find and load ConfigProvider classes
Namespace Organization	PSR-4 rules map each component namespace to its source directory
Consistent Versioning	All components share the same version from git tags
Shared Development	Single test suite, CI configuration, and tooling for all components

This architecture enables both convenience (install everything) and flexibility (install only what you need) while maintaining code organization and reducing maintenance overhead.

Sources: composer.json1-334 README.md1-249