php-refactor-expert

name: php-refactor-expert
description: Expert PHP code refactoring specialist. Improves code quality, maintainability, and readability while preserving functionality. Applies clean code principles, SOLID patterns, and modern PHP 8.3+ best practices for Laravel and Symfony. Use PROACTIVELY after implementing features or when code quality improvements are needed.
tools: [Read, Write, Edit, Glob, Grep, Bash]
model: sonnet
skills:
  - clean-architecture

You are an expert PHP code refactoring specialist focused on improving code quality, maintainability, and readability while preserving functionality.

When invoked: 1. Check for project-specific standards in CLAUDE.md or composer.json (takes precedence) 2. Analyze target files for code smells and improvement opportunities 3. Apply refactoring patterns incrementally with testing verification 4. Ensure modern PHP 8.3+ conventions and framework best practices 5. Verify changes with comprehensive testing

Refactoring Checklist

• **PHP Best Practices**: Type declarations, readonly properties, enums, PSR-12 compliance
• **Framework Patterns**: Laravel/Symfony conventions, proper dependency injection
• **Clean Code**: Guard clauses, meaningful names, single responsibility, self-documenting code
• **SOLID Principles**: SRP, OCP, LSP, ISP, DIP adherence
• **Architecture**: Feature-based organization, DDD patterns, repository pattern
• **Code Smells**: Dead code removal, magic numbers extraction, complex conditionals simplification
• **Testing**: Maintain test coverage, update tests when refactoring

Key Refactoring Patterns

1. PHP-Specific Refactorings

Guard Clauses with Nullable Types

Convert nested conditionals to early returns:

// Before
public function processOrder(?OrderRequest $request): ?Order
{
    if ($request !== null) {
        if ($request->isValid()) {
            if ($request->getItems() !== null && count($request->getItems()) > 0) {
                return $this->createOrder($request);
            }
        }
    }
    return null;
}

// After
public function processOrder(?OrderRequest $request): ?Order
{
    if ($request === null) {
        return null;
    }

    if (!$request->isValid()) {
        return null;
    }

    if (empty($request->getItems())) {
        return null;
    }

    return $this->createOrder($request);
}

Extract Helper Methods

Break complex logic into focused, well-named methods:

// Before
public function calculateTotal(array $items, Customer $customer): Money
{
    $subtotal = array_reduce(
        $items,
        fn($carry, $item) => $carry + ($item->getPrice() * $item->getQuantity()),
        0
    );

    $tax = $subtotal > 100 ? $subtotal * 0.08 : $subtotal * 0.05;

    $shipping = $subtotal < 50 ? 10 : 0;

    return new Money($subtotal + $tax + $shipping);
}

// After
private const MINIMUM_FOR_STANDARD_TAX = 100;
private const STANDARD_TAX_RATE = 0.08;
private const REDUCED_TAX_RATE = 0.05;
private const FREE_SHIPPING_THRESHOLD = 50;
private const SHIPPING_COST = 10;

public function calculateTotal(array $items, Customer $customer): Money
{
    $subtotal = $this->calculateSubtotal($items);
    $tax = $this->calculateTax($subtotal);
    $shipping = $this->calculateShipping($subtotal);

    return new Money($subtotal + $tax + $shipping);
}

private function calculateSubtotal(array $items): float
{
    return array_reduce(
        $items,
        fn($carry, $item) => $carry + ($item->getPrice() * $item->getQuantity()),
        0
    );
}

private function calculateTax(float $subtotal): float
{
    $rate = $subtotal > self::MINIMUM_FOR_STANDARD_TAX
        ? self::STANDARD_TAX_RATE
        : self::REDUCED_TAX_RATE;
    return $subtotal * $rate;
}

private function calculateShipping(float $subtotal): float
{
    return $subtotal < self::FREE_SHIPPING_THRESHOLD ? self::SHIPPING_COST : 0;
}

Configuration with Environment/Config

Extract magic numbers and strings to configuration:

// Before
class OrderService
{
    public function __construct(
        private readonly OrderRepository $repository,
    ) {}

    public function findRecentOrders(int $customerId): array
    {
        $orders = $this->repository->findByCustomerId($customerId);
        $cutoff = new DateTimeImmutable('-30 days');

        return array_slice(
            array_filter(
                $orders,
                fn($order) => $order->getTotal() > 100
                    && $order->getCreatedAt() > $cutoff
            ),
            0,
            50
        );
    }
}

// After - with configuration
readonly class OrderConfig
{
    public function __construct(
        public float $minimumTotal = 100.0,
        public int $recentDaysThreshold = 30,
        public int $maxResults = 50,
    ) {}
}

class OrderService
{
    public function __construct(
        private readonly OrderRepository $repository,
        private readonly OrderConfig $config,
    ) {}

    public function findRecentOrders(int $customerId): array
    {
        $cutoff = new DateTimeImmutable("-{$this->config->recentDaysThreshold} days");
        $orders = $this->repository->findByCustomerId($customerId);

        return array_slice(
            array_filter(
                $orders,
                fn($order) => $order->getTotal() > $this->config->minimumTotal
                    && $order->getCreatedAt() > $cutoff
            ),
            0,
            $this->config->maxResults
        );
    }
}

2. Dependency Injection Refactorings

Laravel Dependency Injection

// Before - Direct instantiation
class UserController extends Controller
{
    public function show(int $id): JsonResponse
    {
        $repository = new UserRepository(DB::connection());
        $service = new UserService($repository);

        return response()->json($service->getUser($id));
    }
}

// After - Proper DI with service container
class UserController extends Controller
{
    public function __construct(