IDE Helper and Code Generation

This document covers the friendsofhyperf/ide-helper component, which generates PHPDoc annotations and helper files to improve IDE autocomplete support for Hyperf applications. The component analyzes the application's code structure, facades, models, and service container bindings to produce accurate type hints that enable intelligent code completion in PHPStorm, VSCode, and other IDEs.

For interactive debugging capabilities, see Tinker and Web Tinker. For console command enhancements, see Console Enhancements.

---

Purpose and Architecture

The IDE helper component addresses a fundamental challenge in Hyperf development: many framework features rely on dependency injection, facades, macros, and dynamic resolution that IDEs cannot analyze statically. Without generated helper files, IDEs show warnings for valid code and lack autocomplete for available methods and properties.

The component operates in three modes:

1. Facade Helper Generation - Analyzes static facade classes and generates PHPDoc with actual service method signatures
2. Model Helper Generation - Inspects database tables to generate property and relationship annotations for Eloquent models
3. Container Binding Documentation - Creates helper files documenting DI container bindings and their resolved types

Component Structure

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

---

Dependencies and Integration Points

The IDE helper relies on several key dependencies for its analysis and generation capabilities:

Dependency	Purpose
barryvdh/reflection-docblock	Parse and generate PHPDoc blocks using reflection
composer/composer	Discover installed packages and autoload configuration
hyperf/filesystem	Read and write generated helper files
hyperf/stringable	String manipulation for code generation
hyperf/collection	Data structure operations during analysis

Optional dependency doctrine/dbal enables advanced model analysis including column renaming detection.

Integration with Component Ecosystem

Sources: src/ide-helper/composer.json24-33 src/facade/composer.json1-59 src/macros/composer.json1-56 src/helpers/composer.json1-64

---

Facade Documentation Generation

The facade generator analyzes static facade classes and produces PHPDoc annotations that map facade method calls to the underlying service implementations. This is critical for autocomplete in IDEs, which cannot resolve the dynamic __callStatic magic method used by facades.

Facade Resolution Process

The component examines each facade class registered in the application:

1. Facade Discovery - Scans ConfigProvider classes for facade registrations
2. Service Resolution - Resolves the underlying service class from the facade's accessor
3. Method Extraction - Uses reflection to extract all public methods from the service
4. Signature Generation - Generates PHPDoc @method annotations with full signatures
5. File Writing - Writes annotations to a central helper file or inline documentation

Example generated output for a facade:

Macro Method Detection

The facade generator also detects and documents macro methods registered via Hyperf\Macroable\Macroable. This is essential because macros add methods dynamically at runtime:

Sources: src/facade/composer.json1-59 src/macros/composer.json1-56 src/helpers/composer.json22-30

---

Model Documentation Generation

The model generator inspects database tables to produce accurate PHPDoc annotations for Eloquent model properties, relationships, and query builder methods. This eliminates IDE warnings about "undefined properties" and enables autocomplete for model attributes.

Database Schema Analysis

The generator connects to configured databases and analyzes table structures:

Analysis Step	Purpose
Column Discovery	Extract column names, types, nullable status
Type Mapping	Map database types to PHP types (string, int, float, bool, etc.)
Default Values	Detect default column values
Relationship Inference	Identify foreign keys and generate relationship hints
Accessor/Mutator Detection	Find getter/setter methods on model classes

Generated Annotations

For a model with database table users:

Relationship Documentation

The generator detects relationship methods and documents their return types:

Sources: src/ide-helper/composer.json24-33 src/model-observer/composer.json1-46

---

Helper Function Documentation

The component generates documentation for global helper functions provided by the friendsofhyperf/helpers package. These functions are defined in Functions.php files that are autoloaded at bootstrap.

Function Signature Extraction

The generator parses helper function files and extracts:

• Function names
• Parameter types and names
• Return types
• Default parameter values
• PHPDoc descriptions

Generated helper file structure:

Conditional Function Documentation

Some helper functions are conditionally defined (only if not already present). The generator handles this by checking function_exists() conditions:

Sources: src/helpers/composer.json44-51 src/facade/composer.json1-59

---

Usage Workflow

Command Execution

The IDE helper provides console commands for generating different types of documentation:

Integration with Development Workflow

Sources: src/ide-helper/composer.json6-10

---

Configuration and Customization

The IDE helper component uses a configuration file for customizing generation behavior:

Configuration Options

Option	Type	Description
enabled	bool	Enable/disable helper generation
filename	string	Name of generated helper file (default: _ide_helper.php)
meta_filename	string	Name of meta file (default: .phpstorm.meta.php)
include_fluent	bool	Include fluent setter methods for models
include_factory_builders	bool	Document factory builder methods
model_locations	array	Directories to scan for models
ignored_models	array	Model classes to skip
write_model_magic	bool	Write annotations directly to model files

Namespace and Class Filtering

The generator can be configured to include or exclude specific namespaces and class patterns:

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

---

Integration with Other Components

Macro Extension Documentation

The IDE helper automatically detects and documents macros registered through the friendsofhyperf/macros component:

Example documented macros:

• Request::boolean(string $key, bool $default = false): bool - Type-safe boolean parameter retrieval
• Request::collect(string $key = null): Collection - Convert input to collection
• Request::validate(array $rules): array - Inline validation with rules
• Builder::fastPaginate(int $perPage = 15): FastPaginator - Optimized pagination

Sources: src/macros/composer.json1-56 src/helpers/composer.json22-24

---

Advanced Features

Generic Type Support

The generator creates PHPDoc with generic type annotations for collections and relationships:

Container Binding Documentation

The meta generator creates .phpstorm.meta.php files that document DI container bindings for PHPStorm's advanced type inference:

This enables PHPStorm to infer return types when resolving services from the container.

Custom Caster Support

The generator can be extended with custom type casters for specific column types:

Sources: src/ide-helper/composer.json32-34

---

Performance Considerations

The IDE helper component is designed for development use only and should not be run in production environments:

Aspect	Implementation
Execution Time	Commands analyze entire codebase - can take several seconds on large projects
Memory Usage	Reflection and schema inspection require significant memory
File I/O	Writes multiple helper files and potentially modifies model files
Database Queries	Model generator executes DESCRIBE queries for every table

Best Practices

1. Version Control - Commit generated helper files to Git for team consistency
2. Automation - Run generators in pre-commit hooks or CI pipeline
3. Conditional Execution - Only generate when needed (e.g., after migrations or facade changes)
4. Exclude from Production - Use --dev requirement in composer.json

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

---

Relationship to Other Developer Tools

The IDE helper complements other development tools in the ecosystem:

• Tinker (#10.1) - Interactive REPL benefits from IDE helper's autocomplete when editing commands
• PHPStan - Static analysis tools use helper files for more accurate type checking
• PHP-CS-Fixer - Helper files provide context for code style analysis
• Command Validation (#10.3) - Command signature documentation aids validation logic

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