Maintainable PHP Code

Most of a project’s life is maintenance: fixing bugs, adding features, upgrading. Code that is easy to change saves more time than code that is clever or fast.

Principles that matter

Single responsibility. A class or function has one reason to change. A class that validates, saves, emails and renders will change for four different reasons.

Don’t repeat yourself. One rule, one place (see Avoiding Duplicate Code). But do not merge things that only look alike.

Depend on abstractions. Ask for an interface, not a concrete class (see Dependency Injection). Swapping an implementation then does not ripple through the code.

Keep it simple. The simplest thing that works, and no speculative features.

Make illegal states impossible. Use types, enums and value objects so invalid data cannot exist.

Code smells

A smell is a sign that code may need work.

Example: replace a flag with clear methods

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<?php
// Unclear: what do the booleans mean?
function renderBad(string $text, bool $escape, bool $newlines): string
{
    $text = $escape ? htmlspecialchars($text) : $text;

    return $newlines ? nl2br($text) : $text;
}

// Clear
final class Html
{
    public static function escaped(string $text): string
    {
        return htmlspecialchars($text, ENT_QUOTES, "UTF-8");
    }

    public static function paragraphs(string $text): string
    {
        return nl2br(self::escaped($text), false);
    }
}

echo renderBad("a<b", true, false) . " | " . Html::paragraphs("line 1\nline 2");

1
2

a&lt;b | line 1<br>
line 2

Example: a value object instead of a loose string

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<?php
final class Email
{
    private function __construct(public readonly string $value) {}

    public static function from(string $raw): self
    {
        $email = strtolower(trim($raw));

        if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
            throw new InvalidArgumentException("Invalid email: $raw");
        }

        return new self($email);
    }
}

function sendWelcome(Email $to): string
{
    return "Welcome email to " . $to->value;   // no need to re-check the address
}

echo sendWelcome(Email::from("  Isha@Example.COM "));

1

Welcome email to isha@example.com

Once an Email exists, everyone can trust it. The checking happens in one place.

Refactoring safely

Refactoring means changing the structure of code without changing its behaviour. Do it in small steps:

1. Make sure there is a test (or at least a manual check) for the behaviour.
2. Make one small change (rename, extract, move).
3. Run the test. Commit.
4. Repeat.

Never mix a refactor with a new feature in one change. If something breaks, you will not know which one caused it.

Tests make change safe

Automated tests let you change code with confidence. Start with tests for the important business rules (prices, permissions, validation), not for every getter.

Document the important things

• A README that explains how to install, configure and run the project.
• Why comments for surprising decisions.
• Type declarations and DocBlocks for what the types cannot say (@param string[] $tags).
• A short architecture note: the folder layout and the request flow (see Clean PHP Project Structure).

Version control habits

• Small commits with clear messages (“Validate email on signup”).
• One purpose per pull request.
• Review each other’s code. A fresh reader finds confusing parts.

Handle upgrades early

Keep PHP, Composer packages and frameworks updated in small steps. Fix deprecation notices when they appear (see PHP Errors). A project that is five versions behind is expensive to rescue.

The final test

Could a new teammate:

1. Install and run the project from the README?
2. Find where a feature lives within a few minutes?
3. Change it without fear of breaking something unrelated?

If yes, the code is maintainable.