php-best-practices

PHP Best Practices

Modern PHP 8.x patterns, PSR standards, type system best practices, and SOLID principles. Contains 45+ rules for writing clean, maintainable PHP code.

When to Apply

Reference these guidelines when:

• Writing or reviewing PHP code
• Implementing classes and interfaces
• Using PHP 8.x modern features
• Ensuring type safety
• Following PSR standards
• Applying design patterns

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Type System	CRITICAL	type-
2	Modern Features	CRITICAL	modern-
3	PSR Standards	HIGH	psr-
4	SOLID Principles	HIGH	solid-
5	Error Handling	HIGH	error-
6	Performance	MEDIUM	perf-
7	Security	CRITICAL	sec-

Quick Reference

1. Type System (CRITICAL)

• type-strict-mode - Declare strict types
• type-return-types - Always declare return types
• type-parameter-types - Type all parameters
• type-property-types - Type class properties
• type-union-types - Use union types effectively
• type-intersection-types - Use intersection types
• type-nullable - Handle nullable types properly
• type-mixed-avoid - Avoid mixed type when possible
• type-void-return - Use void for no-return methods
• type-never-return - Use never for non-returning functions

2. Modern Features (CRITICAL)

• modern-constructor-promotion - Use constructor property promotion
• modern-readonly-properties - Use readonly for immutable data
• modern-readonly-classes - Use readonly classes
• modern-enums - Use enums instead of constants
• modern-attributes - Use attributes for metadata
• modern-match-expression - Use match over switch
• modern-named-arguments - Use named arguments for clarity
• modern-nullsafe-operator - Use nullsafe operator (?->)
• modern-arrow-functions - Use arrow functions for simple closures
• modern-first-class-callables - Use first-class callable syntax

3. PSR Standards (HIGH)

• psr-4-autoloading - Follow PSR-4 autoloading
• psr-12-coding-style - Follow PSR-12 coding style
• psr-naming-conventions - Class and method naming
• psr-file-structure - One class per file
• psr-namespace-declaration - Proper namespace usage

4. SOLID Principles (HIGH)

• solid-single-responsibility - One reason to change
• solid-open-closed - Open for extension, closed for modification
• solid-liskov-substitution - Subtypes must be substitutable
• solid-interface-segregation - Small, focused interfaces
• solid-dependency-inversion - Depend on abstractions

5. Error Handling (HIGH)

• error-custom-exceptions - Create specific exceptions
• error-exception-hierarchy - Proper exception inheritance
• error-try-catch-specific - Catch specific exceptions
• error-finally-cleanup - Use finally for cleanup
• error-never-suppress - Don't suppress errors with @

6. Performance (MEDIUM)

• perf-avoid-globals - Avoid global variables
• perf-lazy-loading - Load resources lazily
• perf-array-functions - Use native array functions
• perf-string-functions - Use native string functions
• perf-generators - Use generators for large datasets

7. Security (CRITICAL)

• sec-input-validation - Validate all input
• sec-output-escaping - Escape output properly
• sec-password-hashing - Use password_hash/verify
• sec-sql-prepared - Use prepared statements
• sec-file-uploads - Validate file uploads

Essential Guidelines

For detailed examples and explanations, see the rule files:

• type-strict-mode.md - Strict types declaration
• modern-constructor-promotion.md - Constructor property promotion
• modern-enums.md - PHP 8.1+ enums with methods
• solid-single-responsibility.md - Single responsibility principle

Key Patterns (Quick Reference)

<?php
declare(strict_types=1);

// Constructor promotion + readonly
class User
{
    public function __construct(
        public readonly string $id,
        private string $email,
    ) {}
}

// Enums with methods
enum Status: string
{
    case Active = 'active';
    case Inactive = 'inactive';

    public function label(): string
    {
        return match($this) {
            self::Active => 'Active',
            self::Inactive => 'Inactive',
        };
    }
}

// Match expression
$result = match($status) {
    'pending' => 'Waiting',
    'active' => 'Running',
    default => 'Unknown',
};

// Nullsafe operator
$country = $user?->getAddress()?->getCountry();

// Arrow functions
$names = array_map(fn(User $u) => $u->name, $users);

Output Format

When auditing code, output findings in this format:

file:line - [category] Description of issue

Example:

src/Services/UserService.php:15 - [type] Missing return type declaration
src/Models/Order.php:42 - [modern] Use match expression instead of switch
src/Controllers/ApiController.php:28 - [solid] Class has multiple responsibilities

How to Use

Read individual rule files for detailed explanations:

rules/modern-constructor-promotion.md
rules/type-strict-mode.md
rules/solid-single-responsibility.md