Development Tools

This document covers the development-time tooling components designed to enhance developer productivity. These tools include interactive REPL environments for rapid prototyping, IDE integration for code intelligence, console output enhancements for better user feedback, and testing infrastructure for coroutine-aware test execution. For runtime observability tools, see Telescope Debug Assistant. For utility functions and helpers used in application code, see Core Utilities and Helper Functions.

Component Overview

The development tools ecosystem consists of several independent components that improve the development experience:

Sources: src/tinker/composer.json1-56 src/web-tinker/composer.json (referenced in CHANGELOG), src/ide-helper/composer.json1-51 src/console-spinner/composer.json1-46 tests/Pest.php1-98

Tinker REPL Environment

The Tinker component provides an interactive PHP REPL (Read-Eval-Print-Loop) powered by PsySH, allowing developers to execute code within the context of a running Hyperf application.

Core Architecture

The friendsofhyperf/tinker package requires PsySH versions 0.10.0 through 0.12.0 and integrates with Hyperf's command system. Custom casters provide enhanced output formatting for common Hyperf objects.

Sources: src/tinker/composer.json26-35

Web Tinker Interface

The friendsofhyperf/web-tinker component extends Tinker with a browser-based interface for remote interactive debugging. This was added in version 3.1.48 and provides HTTP access to the REPL environment.

The component can be bound to a specific server for HTTP access and includes authorization middleware for security.

Sources: CHANGELOG-3.1.md459-463

IDE Helper Code Generation

The IDE Helper component generates PHPDoc annotations and helper files to provide code intelligence in IDEs that lack native understanding of Hyperf's dynamic features.

Generator Architecture

The IDE Helper uses barryvdh/reflection-docblock version 2.0 for docblock parsing and Composer's API (versions 1.0 or 2.0) for package introspection. It analyzes registered facades and helper functions to generate appropriate IDE hints.

Sources: src/ide-helper/composer.json24-31

Integration with Facades

The IDE Helper integrates with the facade system (see Facade System) to generate method annotations:

Generated Annotation	Purpose
@method tags	Static method signatures for facade accessor
@see references	Link to underlying service class
@mixin declarations	IDE completion for macroable traits

Sources: src/ide-helper/composer.json1-51

Console Enhancement Components

Multiple components enhance the console command experience with visual feedback, signal handling, input validation, and performance analysis.

Console Spinner Progress Indicators

The friendsofhyperf/console-spinner component provides progress bars and spinners for long-running console operations. It requires Symfony Console and Process components (versions 5.3, 6.0, or 7.0) and integrates with Hyperf's context system for coroutine safety.

Sources: src/console-spinner/composer.json22-28

Signal Handling

The friendsofhyperf/command-signals component enables console commands to handle Unix signals (SIGINT, SIGTERM, etc.) for graceful shutdown and cleanup operations.

Command Validation

The friendsofhyperf/command-validation component applies validation rules to console command arguments and options, similar to HTTP request validation.

Performance Benchmarking

Added in version 3.1.57, the friendsofhyperf/command-benchmark component provides tools for measuring command execution performance and identifying bottlenecks.

Pretty Console Output

The friendsofhyperf/pretty-console component enhances console output with colored text, tables, and formatted structures for improved readability.

Sources: CHANGELOG-3.1.md319

Testing Infrastructure

The testing infrastructure provides coroutine-aware test execution, component-organized test suites, and integration with mock frameworks.

Pest Framework Configuration

The Pest configuration organizes tests by component using the uses()->group() pattern. Each component has its dedicated test group for selective execution. The faker() helper function provides convenient access to Faker instances.

Sources: tests/Pest.php18-58 tests/Pest.php86-97

Component Test Groups

The following test groups are defined for component-specific testing:

Group	Directory	Purpose
cache	tests/Cache	Cache repository tests
config-consul	tests/ConfigConsul	Consul configuration tests
elasticsearch	tests/Elasticsearch	Elasticsearch integration tests
encryption	tests/Encryption	Encryption service tests
facade	tests/Facade	Facade pattern tests
fast-paginate	tests/FastPaginate	Pagination optimization tests
helpers	tests/Helpers	Helper function tests
http-client	tests/HttpClient	HTTP client tests
macros	tests/Macros	Request macro tests
mail	tests/Mail	Mail component tests
notification	tests/Notification	Notification system tests
redis-subscriber	tests/RedisSubscriber	Redis pub/sub tests
sentry	tests/Sentry	Sentry integration tests
support	tests/Support	Support library tests
tinker	tests/Tinker	Tinker REPL tests
tcp-sender	tests/TcpSender	TCP sender tests
telescope	tests/Telescope	Telescope tests
lock	tests/Lock	Distributed lock tests
rate-limit	tests/RateLimit	Rate limiting tests
validated-dto	tests/ValidatedDTO	DTO validation tests

Sources: tests/Pest.php19-37

Validated DTO Test Setup

The validated-dto group includes specialized beforeEach() setup that mocks the validator factory and configuration interface:

This setup ensures DTO tests have consistent faker data and validator mocks that simulate successful validation.

Sources: tests/Pest.php38-58

Coroutine-Aware Testing

The friendsofhyperf/co-phpunit component, extracted in version 3.1.70, enables PHPUnit tests to run within Swoole coroutines. This ensures test isolation when dealing with coroutine-local storage and async operations.

In version 3.1.71, the NonCoroutine attribute was added to allow specific tests to skip coroutine execution when necessary:

The component optimizes autoloader detection using registered autoloaders rather than scanning all possible loaders.

Sources: CHANGELOG-3.1.md129 CHANGELOG-3.1.md109 CHANGELOG-3.1.md106-107

Mock Integration Patterns

The test infrastructure uses Mockery for dependency mocking and Faker for generating test data. The mock() helper function (from Hyperf's testing utilities) simplifies mock registration:

Mock Pattern	Purpose	Example Usage
Interface mocking	Replace service dependencies	mock(ValidatorFactoryInterface::class, fn($m) => ...)
Container refresh	Isolate tests with fresh container	Container reset between tests
Faker data	Generate realistic test data	faker()->name(), faker()->email()
Response sequences	Test HTTP client behavior	HTTP::fake()->sequence()

Sources: tests/Pest.php46-57

Custom Expectations

The Pest configuration extends the expectation API with custom assertions:

Additional custom expectations can be added following this pattern for domain-specific assertions.

Sources: tests/Pest.php71-73

Helper Functions for Development

Global helper functions facilitate common development tasks:

Function	Purpose	Component
test_property()	Returns test constant 'test_property'	Test utilities
faker(string $locale)	Creates Faker generator with locale	Test data generation

These are defined in the test bootstrap file and available to all tests.

Sources: tests/Pest.php86-97

Integration with CI/CD Pipeline

The development tools integrate with the GitHub Actions workflow defined in .github/workflows/tests.yaml (referenced in TOC 11.1). The test workflow:

1. Runs PHP-CS-Fixer for code style validation
2. Executes PHPStan for static analysis
3. Runs Pest tests across PHP 8.1-8.3 and Swoole 5.1.8-6.1.3
4. Uses component test groups for parallel execution
5. Includes type tests using PHPStan (added in version 3.1.70)

Sources: CHANGELOG-3.1.md131