coding-standards（编码标准）

PHP Coding Standards

Language-level coding standards for PHP, applicable to any PHP project regardless of framework.

PSR-12 Compliance

File Structure

<?php
declare(strict_types=1);  // Required at file top

namespace App\Controller\User;  // PSR-4 autoloading

use Cake\Controller\Controller;  // Alphabetical imports
use Cake\Http\Response;

/**
 * User Controller
 *
 * Handles user management operations
 *
 * @property \App\Model\Table\UsersTable $Users
 */
class UserController extends Controller  // PascalCase for classes
{
    // Class body
}

Method Documentation (PHPDoc)

/**
 * Display user list
 *
 * Retrieves and displays paginated list of users for the current company.
 *
 * @return \Cake\Http\Response|null Renders user list view
 * @throws \Cake\Http\Exception\NotFoundException When user not found
 */
public function index(): ?Response
{
    // Method implementation
}

Type Hints (PHP 8.2+)

Required for all methods:

// Parameter type hints
public function findUser(int $id): ?User
{
    return $this->Users->get($id);
}

// Return type hints
public function getStatus(): string
{
    return 'active';
}

// Union types (PHP 8.0+)
public function process(string|int $value): bool
{
    return is_numeric($value);
}

// Nullable types
public function findOptional(int $id): ?User
{
    try {
        return $this->Users->get($id);
    } catch (RecordNotFoundException $e) {
        return null;
    }
}

Naming Conventions

// Classes: PascalCase
class UserManagementService {}

// Methods: camelCase
public function getUserById(int $id): ?User {}

// Constants: UPPER_SNAKE_CASE
const MAX_LOGIN_ATTEMPTS = 5;

// Properties: camelCase
private string $userName;

// Local variables: camelCase
$userData = $this->fetchData();

Code Formatting

// Indentation: 4 spaces (not tabs)
public function example(): void
{
    if ($condition) {
        // 4 space indent
        $this->doSomething();
    }
}

// Line length: <= 120 characters
public function methodWithLongName(
    string $firstParameter,
    int $secondParameter,
    bool $thirdParameter
): array {
    return [];
}

// Blank lines
class Example
{
    private string $property;  // Property declaration
                               // Blank line before methods
    public function method(): void
    {
        // Method body
    }
                               // Blank line between methods
    public function anotherMethod(): void
    {
        // Method body
    }
}

PHPDoc Standards

Required Elements

/**
 * Short description (one line)
 *
 * Long description if needed.
 * Can span multiple lines.
 *
 * @param string $name User name
 * @param int $age User age
 * @return bool Success status
 * @throws \InvalidArgumentException When age is negative
 */
public function validateUser(string $name, int $age): bool
{
    if ($age < 0) {
        throw new \InvalidArgumentException('Age cannot be negative');
    }
    return true;
}

Optional Elements

/**
 * Process user data
 *
 * @param array $data User data
 * @return User Processed user entity
 * @see UserValidator::validate() Related validation
 * @deprecated 2.0.0 Use processUserEntity() instead
 * @todo Add email validation
 */
public function processUser(array $data): User
{
    // Implementation
}

Property Documentation

/**
 * @var \App\Model\Table\UsersTable Users table instance
 */
public $Users;

/**
 * @var array<string, mixed> Configuration options
 */
private array $config;

Error Handling

Exception Types

// Use specific exception types
throw new \InvalidArgumentException('Invalid user ID');
throw new \RuntimeException('Database connection failed');
throw new \LogicException('Method called in wrong state');

// Document all thrown exceptions
/**
 * @throws \InvalidArgumentException When ID is invalid
 * @throws \RuntimeException When database fails
 */
public function getUser(int $id): User {}

Try-Catch Blocks

try {
    $user = $this->Users->get($id);
    $this->processUser($user);
} catch (RecordNotFoundException $e) {
    // Handle specific exception
    Log::error('User not found: ' . $id);
    throw new NotFoundException('User not found');
} catch (\Exception $e) {
    // Handle general exception
    Log::error('Unexpected error: ' . $e->getMessage());
    throw $e;
}

Code Quality Standards

Validation Rules

Check these in code review:

• All public methods have PHPDoc comments
• All parameters have type hints
• Return types are declared
• Exceptions are documented with @throws
• PSR-12 formatting applied (indentation, spacing, line length)
• No unused imports
• Properties have visibility modifiers
• No PHP short tags (<?=)

Static Analysis

Use PHPStan for type checking:

vendor/bin/phpstan analyse src tests --level 7

Code Style

Use PHP-CS-Fixer for automatic formatting:

vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php

Framework-Agnostic

These standards apply to:

• CakePHP projects
• Laravel projects
• Symfony projects
• Plain PHP projects
• Any PHP codebase

Framework-specific conventions should be defined in framework-level skills (e.g., php-cakephp/framework-conventions).