Monorepo Management

This page documents the monorepo tooling, processes, and workflows used to manage the friendsofhyperf/components repository. This includes the subtree split process for releasing individual components, composer scripts for development tasks, and version management strategies.

For information about the overall monorepo architecture and component organization, see Monorepo Architecture and Component Registry. For information about the CI/CD pipeline and testing infrastructure, see CI/CD Pipeline.

---

Monorepo Structure

The friendsofhyperf/components repository is organized as a monorepo containing 50+ independent components. Each component lives in its own subdirectory under src/ and maintains its own composer.json file while sharing common development dependencies and tooling at the root level.

Directory Layout

friendsofhyperf/components/
├── composer.json # Root composer file with replace directive
├── src/
│ ├── sentry/
│ │ ├── src/ # Component source code
│ │ ├── composer.json # Individual component composer.json
│ │ └── README.md # Component documentation
│ ├── telescope/
│ ├── http-client/
│ ├── helpers/
│ ├── cache/
│ └── ... (50+ components)
├── tests/ # Shared test infrastructure
├── bin/ # Development and release scripts
├── .github/
│ └── workflows/ # CI/CD pipeline definitions
└── docs/ # Documentation site

Each component follows a standardized structure with its source code in src/*/src/, its own composer.json defining its specific dependencies, and optionally configuration providers, function files, and component-specific tests.

Sources: composer.json172-221

---

The Replace Directive Strategy

The monorepo uses Composer's replace directive to provide all 50+ components through a single package installation. When a user installs friendsofhyperf/components, Composer treats it as if all individual component packages are installed.

Replace Configuration

The root composer.json declares all components in the replace section:

This allows two installation modes:

Install all components:

Install individual components:

The * version constraint in the replace directive means the monorepo satisfies any version requirement for individual components, ensuring compatibility when mixing monorepo and individual component installations.

Monorepo Replace Strategy

Sources: composer.json119-168 composer.json172-221 composer.json256-303

---

Subtree Split and Release Process

The monorepo uses subtree splitting to release individual components as separate Git repositories. This allows users to install specific components without pulling the entire monorepo while maintaining a single source of truth for development.

Release Workflow

The release process is triggered manually through GitHub Actions by providing a version tag (e.g., v3.1.0). The workflow executes the following steps:

1. Manual Trigger: Developer initiates the workflow with a tag input through the GitHub Actions UI
2. SSH Setup: Configures SSH keys for pushing to split repositories
3. Subtree Split: The ./bin/release.sh script splits each component into its own repository
4. Tag Creation: Creates the version tag on each split repository
5. Push: Pushes changes and tags to individual component repositories

Subtree Split Release Workflow

The workflow is defined in .github/workflows/release.yaml with the following key configuration:

• Trigger: workflow_dispatch with manual tag input
• Repository Check: Only runs on friendsofhyperf/components repository
• SSH Key: Uses SPLIT_PRIVATE_KEY secret for authentication
• Git History: Fetches full history (fetch-depth: 0) required for subtree splits

Sources: .github/workflows/release.yaml1-40

Subtree Split Characteristics

Each split repository contains:

• Only the files from its specific src/*/ directory
• Full Git history filtered to that directory
• Its own composer.json with proper dependencies
• Independent versioning synchronized with the monorepo tag

This approach provides several benefits:

Aspect	Benefit
Development	Single codebase, shared tooling, atomic cross-component changes
Distribution	Users can install only needed components, reducing dependency bloat
CI/CD	Single test run validates all components together
Versioning	All components share the same version number, ensuring compatibility

Sources: .github/workflows/release.yaml29-40

---

Development Scripts and Tooling

The monorepo provides several Composer scripts in the root composer.json for common development tasks. These scripts streamline code quality checks, testing, and repository maintenance.

Available Scripts

Script	Command	Purpose
test	composer test	Runs full test suite (lint + unit + types)
test:lint	composer test:lint	Checks code style with PHP-CS-Fixer (dry-run)
test:unit	composer test:unit	Runs Pest test suite
test:types	composer test:types	Analyzes type coverage with Pest
cs-fix	composer cs-fix	Fixes code style violations
analyse	composer analyse	Runs PHPStan static analysis
analyse:types	composer analyse:types	Runs type analysis with custom configuration
json-fix	composer json-fix	Normalizes all composer.json files
gen:readme	composer gen:readme	Regenerates README files from component list
repo:pending	composer repo:pending	Prepares pending repository changes

Composer Script Dependencies

Script Implementations

Testing Scripts

The test script orchestrates three validation stages:

1. Linting: Validates code style compliance using PHP-CS-Fixer in dry-run mode
2. Unit Tests: Executes the Pest test suite across all components
3. Type Coverage: Analyzes type annotations and ensures type safety

Code Quality Scripts

The cs-fix script automatically corrects code style violations based on the configuration in huangdijia/php-coding-standard. The analyse script runs PHPStan with unlimited memory (--memory-limit=-1) to perform static analysis across the entire monorepo.

JSON Maintenance Scripts

The json-fix script performs three operations:

1. Executes a custom ./bin/composer-json-fixer for monorepo-specific fixes
2. Normalizes the root composer.json using ergebnis/composer-normalize
3. Finds and normalizes all component composer.json files

Repository Preparation Scripts

The repo:pending script prepares changes for release by:

1. Running ./bin/pending-repositories.sh to identify components with changes
2. Executing ./bin/pending-composer-json to update component metadata
3. Fixing JSON formatting across all composer files
4. Regenerating README files with updated component lists

Sources: composer.json305-332

---

Version Management

The monorepo uses a unified versioning strategy where all components share the same version number. This ensures compatibility across the entire component suite and simplifies dependency management.

Versioning Strategy

Version Synchronization

All components are tagged with the same version number in the monorepo, and this version is propagated to individual split repositories during the release process. For example:

• Monorepo tag: v3.1.0
• All split repositories receive tag: v3.1.0

This approach guarantees that components with version 3.1.0 have been tested together and are compatible.

Branch Alias Configuration

Individual component composer.json files include a branch-alias in the extra section:

This allows developers to require ~3.1.0 for stability while Composer can still resolve the dev-main branch during development.

Version Management Flow

Compatibility Matrix

The monorepo maintains compatibility with specific versions of Hyperf and PHP:

Dependency	Version Constraint	Location
PHP	>=8.1	Root and all components
Hyperf	~3.1.0	All component dependencies
Swoole	5.1.8 - 6.1.3	CI/CD test matrix
Swow	dev-develop	Alternative runtime option

The CI/CD pipeline tests across this compatibility matrix to ensure all components work correctly with all supported versions.

Sources: composer.json16-18 .github/workflows/tests.yaml57-58 src/sentry/composer.json61-62

---

Component Composer.json Management

Each component maintains its own composer.json file that defines its specific dependencies and metadata. The monorepo provides tooling to keep these files synchronized and properly formatted.

Individual Component Structure

A typical component composer.json includes:

Example: Sentry Component

Key Configuration Sections

Section	Purpose	Example
name	Package identifier on Packagist	friendsofhyperf/sentry
require	Runtime dependencies	Hyperf components, third-party libraries
suggest	Optional dependencies	Additional Hyperf components for extended features
extra.branch-alias	Development version mapping	Maps dev-main to 3.1-dev
extra.hyperf.config	ConfigProvider registration	Auto-discovery class for Hyperf
support	Project links	Issues, source, docs, pull requests

Normalization Process

The json-fix script ensures all component composer.json files follow consistent formatting:

1. Custom Fixer: ./bin/composer-json-fixer applies monorepo-specific rules
2. Composer Normalize: Uses ergebnis/composer-normalize to standardize structure
3. Recursive Application: Finds and normalizes all components via shell command

This process maintains consistency across the 50+ component files and prevents merge conflicts from formatting differences.

Sources: src/sentry/composer.json1-68 composer.json313-317

---

Testing and Quality Assurance

The monorepo implements a comprehensive quality assurance pipeline that validates code across all components simultaneously. This ensures consistency and catches integration issues early.

Quality Gates

Quality Assurance Pipeline

Test Matrix

The CI pipeline tests against a comprehensive matrix of PHP and Swoole versions:

PHP Version	Swoole Versions	Purpose
8.3	6.1.3, 6.0.2, 5.1.8	Latest PHP with all Swoole versions
8.2	6.1.3, 6.0.2, 5.1.8	Current stable PHP
8.1	6.1.3, 6.0.2, 5.1.8	Minimum supported PHP version

This results in 9 test combinations (3 PHP × 3 Swoole versions) to ensure broad compatibility.

Testing Infrastructure

Test Organization

Tests are organized using Pest with component-based groups:

This allows running tests for specific components:

Test Retry Mechanism

The CI pipeline uses nick-fields/retry@v3 action with the following configuration:

• Timeout: 10 minutes per attempt
• Max Attempts: 2
• Command: php vendor/bin/pest --parallel

This provides resilience against transient failures (network issues, race conditions) while maintaining fast feedback with parallel execution.

Code Quality Tools

Tool	Configuration	Purpose
PHP-CS-Fixer	huangdijia/php-coding-standard:^2.4	Enforces PSR-12 and custom coding standards
PHPStan	Level 5, unlimited memory	Static analysis with strict type checking
Pest	Parallel execution, type coverage	Unit testing with modern syntax
Composer Normalize	ergebnis/composer-normalize:^2.43	Ensures consistent composer.json formatting

Sources: .github/workflows/tests.yaml23-94 composer.json305-332 composer.json44-118

---

Monorepo Maintenance Scripts

The bin/ directory contains several custom scripts for monorepo maintenance tasks. While the scripts themselves aren't shown in the provided files, their usage is evident from the Composer scripts configuration.

Maintenance Script Overview

Script	Invoked By	Purpose
bin/release.sh	GitHub Actions workflow	Performs subtree splits and pushes to individual repositories
bin/regenerate-readme.sh	composer gen:readme	Generates README files from component metadata
bin/pending-repositories.sh	composer repo:pending	Identifies components with pending changes
bin/pending-composer-json	composer repo:pending	Updates component composer.json with pending changes
bin/composer-json-fixer	composer json-fix	Applies monorepo-specific composer.json fixes

Script Integration

These scripts integrate with the overall development workflow:

Development Workflow Integration

Component-Specific Metadata

The monorepo maintains metadata about each component for documentation generation and release preparation. This metadata likely includes:

• Component name and description
• Dependencies and suggestions
• Installation commands
• Documentation links
• Category classification (database, cache, HTTP, etc.)

This metadata is used by bin/regenerate-readme.sh to generate the component listings in README files and documentation pages.

Sources: composer.json309-322 .github/workflows/release.yaml39

---

Best Practices for Monorepo Contributors

Adding a New Component

1. Create Directory Structure: Create src/new-component/src/ for source code
2. Component composer.json: Add package metadata, dependencies, and Hyperf ConfigProvider
3. Update Root composer.json:
   • Add to replace section
   • Add PSR-4 autoload mapping
   • Add ConfigProvider to extra.hyperf.config
4. Run Maintenance Scripts: Execute composer json-fix and composer repo:pending
5. Write Tests: Add tests in tests/NewComponent/ with Pest configuration
6. Document: Update README and add component documentation

Making Cross-Component Changes

When a change affects multiple components:

1. Atomic Commits: Make all changes in a single commit for atomic releases
2. Test Together: Run composer test to validate all components
3. Version Compatibility: Ensure changes maintain version compatibility
4. Update Dependencies: If component A now depends on component B, update composer.json

Preparing for Release

1. Run Quality Checks: composer test must pass
2. Normalize JSON: Run composer json-fix
3. Update Documentation: Run composer gen:readme
4. Review Changes: Run composer repo:pending to see what will be released
5. Create Tag: Tag the monorepo with semantic version (e.g., v3.1.0)
6. Trigger Release: Use GitHub Actions UI to run the release workflow

Debugging Split Issues

If a component fails to split properly:

• Check Git History: Ensure the component has commits in its directory
• Verify SSH Keys: Confirm SPLIT_PRIVATE_KEY secret is configured
• Test Locally: Run git subtree split --prefix=src/component-name manually
• Check Remote: Verify the target repository exists and is accessible

Sources: composer.json119-303 .github/workflows/release.yaml17-40