hyperf-explore/AGENTS.md

AGENTS.md - Hyperf Skeleton Development Guide

This document provides guidelines for agentic coding agents working in this Hyperf framework project.

Project Overview

• Framework: Hyperf ~3.1.0 (PHP coroutine framework)
• PHP Version: >= 8.1
• Runtime: Swoole
• License: Apache-2.0

---

Build/Lint/Test Commands

Run All Tests

composer test
# or
co-phpunit --prepend test/bootstrap.php --colors=always

Run Single Test

# By test method name
vendor/bin/phpunit --filter testExample

# By fully qualified class name
vendor/bin/phpunit --filter 'HyperfTest\\Cases\\ExampleTest::testExample'

# By test class
vendor/bin/phpunit test/Cases/ExampleTest.php

Code Style Fix

# Fix all files
composer cs-fix

# Fix specific file
php-cs-fixer fix app/Controller/IndexController.php

# Dry run (check only)
php-cs-fixer fix --dry-run --diff

# Fix with config explicitly
php-cs-fixer fix --config=.php-cs-fixer.php

Static Analysis (PHPStan)

composer analyse
# or
vendor/bin/phpstan analyse --memory-limit 300M

# With specific level
vendor/bin/phpstan analyse --memory-limit 200M -l 5

Start Development Server

composer start
# or
php ./bin/hyperf.php start

---

Code Style Guidelines

File Structure

PSR Standards

• PSR-2: Code must follow PSR-2 coding style
• PSR-4: Autoloading via namespaces

PHP CS Fixer Rules (from .php-cs-fixer.php)

Rule	Value
Array syntax	Short: [] instead of array()
List syntax	Short: list($a, $b) → [$a, $b]
Concat space	One space around .
Quote style	Single quotes
Declare strict types	Required: declare(strict_types=1);
Ordered imports	class → function → const
Global namespace import	use App\Foo; (no leading \)
Yoda style	Variable on right: $value === self::FOO
Blank line before statement	Before declare
Not operator	With successor space: ! $value
Constant case	Lower: const FOO = 1;

Imports Ordering

use App\Constants\ErrorCode;
use Hyperf\Constants\AbstractConstants;
use Hyperf\Constants\Annotation\Constants;
use Hyperf\HttpServer\Contract\RequestInterface;
use Psr\Container\ContainerInterface;

#[Constants]
class ErrorCode extends AbstractConstants
{
    // ...
}

Naming Conventions

Element	Convention	Example
Namespace	PascalCase	App\Controller, App\Constants
Class	PascalCase	IndexController, BusinessException
Method	camelCase	getUser(), handleMessage()
Property	camelCase	$request, $container
Constant	SCREAMING_SNAKE	SERVER_ERROR, DEFAULT_TIMEOUT
File	PascalCase.php	ErrorCode.php, IndexController.php

Type Declarations

• Use strict types: declare(strict_types=1);
• Use return type hints when possible
• Use property type hints

class QueueHandleListener implements ListenerInterface
{
    protected LoggerInterface $logger;

    public function __construct(ContainerInterface $container)
    {
        // ...
    }

    public function process(object $event): void
    {
        // ...
    }
}

PHPDoc Annotations

• Align PHPDoc annotations to the left
• Do NOT use @author annotation
• Use @param and @return with types

/**
 * @param int $code Error code
 * @param string|null $message Error message
 */
public function __construct(int $code = 0, string $message = null)

Dependency Injection

Use #[Inject] attribute for automatic injection:

use Hyperf\Di\Annotation\Inject;

class AbstractController
{
    #[Inject]
    protected ContainerInterface $container;

    #[Inject]
    protected RequestInterface $request;
}

Error Handling

• Business exceptions: App\Exception\BusinessException
• Extends Hyperf\Server\Exception\ServerException
• Use Hyperf's LoggerInterface for logging
• Use ErrorCode::getMessage($code) to get error messages

Directory Structure

app/
├── Constants/        # ErrorCode, system constants
├── Controller/      # HTTP controllers
├── Exception/        # Exception classes and handlers
├── Listener/         # Event listeners
├── Model/            # Database models
└── Process/          # Custom processes
test/
├── bootstrap.php     # Test bootstrap
├── Cases/            # Test cases
└── HttpTestCase.php  # HTTP test base class
config/
├── container.php     # DI container config
└── ...

Testing

• Tests extend Hyperf\Testing\TestCase or HyperfTest\HttpTestCase
• Test classes in HyperfTest\* namespace
• Use #[CoversNothing] for unit tests without coverage
• Use $this->get(), $this->post(), etc. for HTTP assertions

Gitignore Patterns

vendor/
runtime/
.env
.phpunit.cache/

---

CI/CD

The project uses GitHub Actions (see .github/workflows/build.yml). Docker build is triggered on push and pull requests.

Additional Resources

• Hyperf Wiki
• Hyperf Documentation
• PSR-2 Coding Style Guide