 |
VOOZH | about |
|
VOOZH | about |
This document provides an overview of the development and release infrastructure supporting the friendsofhyperf/components monorepo. It covers the continuous integration pipeline that validates code quality and tests across multiple PHP and Swoole versions, the multi-locale documentation website built with VitePress, and the automated tooling for releasing individual component packages from the monorepo.
For information about development tools used within the components themselves, see Development Tools.
The project uses GitHub Actions for continuous integration and deployment. The pipeline is defined in two primary workflows: tests.yaml for quality assurance and release.yaml for package distribution.
The tests workflow runs on every push and pull request (excluding documentation changes), and on a daily schedule at 2:00 AM UTC. It consists of two sequential jobs: cs-fix and tests.
Test Workflow Diagram:
Sources: .github/workflows/tests.yaml1-94
The cs-fix job runs on PHP 8.1 and performs two validation steps:
Composer Normalization: Validates that all composer.json files in the monorepo follow a consistent format using composer normalize --dry-run. This check runs both on the root composer.json and recursively on all component-level files.
PHP-CS-Fixer: Enforces code style standards across the entire codebase using vendor/bin/php-cs-fixer fix --dry-run --diff --verbose. The PHP_CS_FIXER_IGNORE_ENV environment variable is set to bypass environment checks.
Sources: .github/workflows/tests.yaml23-49
The tests job uses a matrix strategy to validate compatibility across:
| Dimension | Values |
|---|---|
| Operating System | ubuntu-latest |
| PHP Version | 8.3, 8.2, 8.1 |
| Swoole Extension | 6.1.3, 6.0.2, 5.1.8 |
This produces 9 parallel test executions (3 PHP versions × 3 Swoole versions). The matrix uses fail-fast: false to allow all combinations to complete even if one fails.
The PHP environment is configured with the following extensions: redis, pdo, pdo_mysql, bcmath, and swoole-{version} using shivammathur/setup-php@v2.
Sources: .github/workflows/tests.yaml50-77
After environment setup, the workflow runs three verification steps:
composer analyse src performs static analysis on all component source code.composer analyse:types validates type annotations using Pest's type coverage feature../.travis/setup.services.sh starts a Redis container via Docker for integration tests.vendor/bin/pest --parallel runs the test suite with parallelization enabled.The test execution uses nick-fields/retry@v3 with a 10-minute timeout and up to 2 retry attempts to handle transient failures.
Sources: .github/workflows/tests.yaml81-94 .travis/setup.services.sh1-11
The service setup script at .travis/setup.services.sh performs the following operations:
This starts a Redis container on port 6379 and verifies it is accessible.
Sources: .travis/setup.services.sh1-11
The release workflow automates the process of splitting the monorepo into individual component repositories and tagging them with version numbers.
Release Workflow Diagram:
Sources: .github/workflows/release.yaml1-40
The release workflow is manually triggered using the GitHub Actions workflow_dispatch event. It requires a tag input parameter (e.g., v3.1.0) and performs the following steps:
Deep Clone: Checks out the repository with fetch-depth: 0 to retrieve the complete git history, necessary for subtree splitting.
SSH Configuration: Writes the SPLIT_PRIVATE_KEY secret to ~/.ssh/id_rsa and configures SSH to skip host key verification with StrictHostKeyChecking no.
Git Configuration: Sets the git user identity to huangdijia@gmail.com and Deeka Wong.
Tag Validation: Verifies that the tag input is non-empty before proceeding.
Subtree Split Execution: Invokes ./bin/release.sh with the provided tag, which splits each component directory into its corresponding standalone repository.
Sources: .github/workflows/release.yaml18-40
The workflow only executes on the canonical repository:
This prevents forks from accidentally triggering release operations.
Sources: .github/workflows/release.yaml14
The documentation site is built using VitePress and supports four locales: Simplified Chinese (default), Traditional Chinese (Hong Kong), Traditional Chinese (Taiwan), and English.
Documentation Site Structure:
Sources: docs/.vitepress/config.mts1-179
The site defines locales in the locales object within config.mts:
| Locale Key | Label | Language Code | Link Prefix |
|---|---|---|---|
root | 简体中文 | zh | / |
zh-hk | 繁體中文（港） | zh-hk | /zh-hk/index |
zh-tw | 繁體中文（臺） | zh-tw | /zh-tw/index |
en | English | en | /en/index |
Each locale imports its own configuration, navigation, and sidebar structures from dedicated TypeScript modules under docs/.vitepress/src/{locale}/.
Sources: docs/.vitepress/config.mts52-100
Common theme settings include:
/logo.svg displayed in the navigation bar[2, 4] shows headings from level 2 to level 4 in the page navigationhttps://github.com/friendsofhyperf/components/edit/main/docs/:pathThe simplified Chinese locale (root) includes additional UI translations:
Sources: docs/.vitepress/config.mts110-177
The site integrates two analytics platforms by injecting script tags into the HTML head:
df278fe462855b3046c941a8adc19064 via the standard _hmt array pattern.pgqv4ftymf for session recording and heatmaps.Both scripts are embedded inline in the configuration.
Sources: docs/.vitepress/config.mts26-51
The site uses markdown-it-task-lists plugin to render GitHub-style task lists with checkboxes:
Sources: docs/.vitepress/config.mts101-106
VitePress generates a sitemap at https://docs.hdj.me/sitemap.xml for search engine crawlers:
Sources: docs/.vitepress/config.mts107-109
The homepage at docs/index.md uses VitePress's home layout to showcase key components:
| Feature | Description | Link |
|---|---|---|
| Sentry | Hyperf SDK for error tracking | /zh-cn/components/sentry/ |
| Telescope | Debug dashboard | /zh-cn/components/telescope/ |
| Tinker | REPL console | /zh-cn/components/tinker/ |
| Web Tinker | Browser-based REPL | /zh-cn/components/web-tinker/ |
| Encryption | Encryption utilities | /zh-cn/components/encryption/ |
| Cache | Multi-driver cache API | /zh-cn/components/cache/ |
| HttpClient | HTTP client library | /zh-cn/components/http-client/ |
| Validated DTO | Data validation | /zh-cn/components/validated-dto/ |
| Lock | Distributed locking | /zh-cn/components/lock/ |
The hero section displays:
Sources: docs/index.md1-50
The English navigation structure includes three main items:
Sources: docs/.vitepress/src/en/nav.ts1-14
The monorepo uses a "replace" strategy in the root composer.json to provide all 50+ component packages as a single installation. Individual components can also be installed separately from their split repositories.
Each component is located under src/{component-name}/ with its own:
composer.json defining the package metadatasrc/ directory containing the implementationConfigProvider.php registering services with the DI containerThe root composer.json defines automation scripts for common development tasks:
| Script | Command | Purpose |
|---|---|---|
analyse | phpstan analyse --memory-limit 1024M | Run static analysis on specified paths |
analyse:types | pest --type-coverage | Validate type coverage in tests |
cs-fix | php-cs-fixer fix | Auto-fix code style violations |
test | pest --parallel | Execute test suite in parallel |
These scripts are invoked by the CI pipeline as described above.
Sources: .github/workflows/tests.yaml84-94
The ./bin/release.sh script (referenced in the release workflow) performs subtree splitting to extract individual component histories into standalone repositories. This enables:
The split process preserves git history and maintains proper author attribution.
Sources: .github/workflows/release.yaml39
The repository uses CodeRabbit for automated code review with the following settings:
This configuration enables Chinese language reviews, automatic review on pull requests and drafts, and auto-reply in discussions.
Sources: .coderabbit.yaml1-17
For environments where Swoole is not pre-installed, the .travis/setup.swoole.sh script provides automated installation:
libcurl4-openssl-dev, libc-ares-dev, libpq-dev--enable-openssl--enable-swoole-curl--enable-cares--enable-swoole-pgsql--enable-brotliextension=swoole and swoole.use_shortname='Off' to php.iniThe script verifies installation by running php --ri swoole.
Sources: .travis/setup.swoole.sh1-29
The CI environment sets PHP_CS_FIXER_IGNORE_ENV=1 to bypass PHP-CS-Fixer's environment validation, ensuring consistent code style checks across different PHP versions.
Sources: .github/workflows/tests.yaml20
Refresh this wiki