Ahmed Rizawan

After spending 15+ years wrangling PHP codebases, I’ve seen my fair share of both beautiful and nightmare-inducing code. Let me share some battle-tested practices that have consistently helped me and my teams write cleaner, more maintainable PHP applications.

1. Embrace Meaningful Names That Tell a Story

Remember that time you came across a variable named $x or a function called processData()? Yeah, we’ve all been there. These vague names are like trying to navigate a city with street signs written in hieroglyphics. Let’s look at a real example:

// Poor naming
$p = ['name' => 'John', 'a' => 35, 's' => 'active'];
function calc($x, $y) {
    return $x + $y;
}

// Clean naming
$userProfile = [
    'name' => 'John',
    'age' => 35,
    'status' => 'active'
];
function calculateMonthlyRevenue(float $basicSalary, float $bonus): float {
    return $basicSalary + $bonus;
}

2. Single Responsibility Principle: One Job, One Class

Think of classes like employees in a company. Just as you wouldn’t want one person handling sales, accounting, and IT support, your classes shouldn’t try to do everything. Here’s a practical example:

// Bad approach - class doing too much
class OrderProcessor {
    public function processOrder($order) {
        $this->validateOrder($order);
        $this->calculateTotalPrice($order);
        $this->saveToDatabase($order);
        $this->sendEmail($order);
        $this->updateInventory($order);
    }
}

// Better approach - separated responsibilities
class OrderValidator {
    public function validate(Order $order): bool {
        // Validation logic
    }
}

class PriceCalculator {
    public function calculateTotal(Order $order): float {
        // Price calculation logic
    }
}

class OrderRepository {
    public function save(Order $order): void {
        // Database operations
    }
}

3. Keep Methods Short and Sweet

Long methods are like those friends who tell stories that never end – they’re hard to follow and usually trying to do too much. I’ve found that methods longer than 20 lines are usually crying out to be broken down into smaller, more focused pieces.

// Instead of this monster method
public function processUserRegistration($userData) {
    // 50+ lines of validation, database operations,
    // email sending, and notification logic
}

// Break it down into focused methods
public function processUserRegistration(array $userData): void {
    $validatedData = $this->validateUserData($userData);
    $user = $this->createUser($validatedData);
    $this->sendWelcomeEmail($user);
    $this->notifyAdmins($user);
}

4. Use Type Declarations and Return Types

PHP 7+ gave us powerful type system features, and not using them is like driving without a seatbelt – technically possible, but why take the risk? They serve as built-in documentation and catch errors early.

// Before PHP 7 - living dangerously
function calculateDiscount($price, $percentage) {
    return $price * ($percentage / 100);
}

// Modern PHP - type-safe and self-documenting
function calculateDiscount(float $price, float $percentage): float {
    return $price * ($percentage / 100);
}

5. Meaningful Exception Handling

Don’t just catch exceptions and swallow them into the void. Proper exception handling is like having a good insurance policy – you hope you won’t need it, but you’ll be glad it’s there when things go wrong.

// Poor exception handling
try {
    $user->save();
} catch (Exception $e) {
    // Silent fail or generic message
    error_log('Error occurred');
}

// Better exception handling
try {
    $user->save();
} catch (DatabaseConnectionException $e) {
    $this->logger->critical('Database connection failed', [
        'user_id' => $user->getId(),
        'error' => $e->getMessage()
    ]);
    throw new UserSaveException('Unable to save user due to database error');
} catch (ValidationException $e) {
    $this->logger->warning('User validation failed', [
        'errors' => $e->getErrors()
    ]);
    throw new UserSaveException('Invalid user data provided');
}

6. Dependency Injection Over Service Location

Think of dependency injection like ordering a pizza – instead of your code going to find all the ingredients (service location), it receives a ready-made pizza (injected dependencies). This makes testing easier and reduces coupling.

// Avoid this
class UserService {
    public function __construct() {
        $this->db = Database::getInstance();
        $this->logger = Logger::getInstance();
    }
}

// Do this instead
class UserService {
    public function __construct(
        private DatabaseInterface $db,
        private LoggerInterface $logger
    ) {}
}

7. Use Early Returns to Reduce Nesting

Deep nesting is like a maze – the deeper you go, the harder it is to find your way out. Early returns keep your code flat and easier to follow.

// Deeply nested code
public function processOrder(Order $order): bool {
    if ($order->isValid()) {
        if ($order->hasStock()) {
            if ($order->payment->process()) {
                // Process order
                return true;
            }
        }
    }
    return false;
}

// Clean code with early returns
public function processOrder(Order $order): bool {
    if (!$order->isValid()) {
        return false;
    }
    
    if (!$order->hasStock()) {
        return false;
    }
    
    if (!$order->payment->process()) {
        return false;
    }
    
    // Process order
    return true;
}

8. Write Self-Documenting Code

Your code should read like a well-written story. If you need extensive comments to explain what your code does, consider rewriting it to be more self-explanatory.

// Needs explanation
if ($p && $u->s == 1 && time() - $u->t < 7200) { }

// Self-documenting
$isSubscribed = $premium && $user->status === 'active';
$sessionIsValid = time() - $user->lastLoginTime < TWO_HOURS;
if ($isSubscribed && $sessionIsValid) { }

9. Use Value Objects for Complex Types

Instead of passing around primitive types, encapsulate related data in value objects. They’re like specialized containers that ensure data integrity and provide meaningful operations.

// Instead of primitive types
function createUser($email, $password) {
    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
        throw new InvalidArgumentException('Invalid email');
    }
}

// Use value objects
class Email {
private string $email;

public function __construct(string $email) {
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {