PHP Refactoring Techniques: Naming, Extraction, Early Return, Collections, and Consistency

Refactoring means modifying or rewriting code without changing its functionality.

#1 – Expressiveness (Naming)

Writing expressive code improves readability; use self‑explanatory names. Example before and after:

// ❌ 这个方法是用来做什么的，方法名表达并不清晰
// ❌ 是设置状态还是检查状态呢？
$status = $user->status('pending');

// ✅ 通过添加 is，使方法名表达的意图更清晰
// ✅ 检测用户状态是否与给定状态相等
// ✅ 同时新变量名让我们可以推断它是布尔值
$isUserPending = $user->isStatus('pending');

Example #2 – Naming (Factory)

// ❌ 这个类返回的是什么？类名？类全名？还是类路径？
return $factory->getTargetClass();

// ✅ 我们获取的是类路径
// ✅ 如果用户想要类名？则找错了方法
return $factory->getTargetClassPath();

#1 – Extraction

Before:

public function setCodeExamples(string $exampleBefore, string $exampleAfter)
{
    $this->exampleBefore = file_get_contents(base_path("$exampleBefore.md"));
    $this->exampleAfter = file_get_contents(base_path("$exampleAfter.md"));
}

After:

public function setCodeExamples(string $exampleBefore, string $exampleAfter)
{
    // ✅ 代码直接说明了我们的意图：获取code example(不关注如何获取)
    $this->exampleBefore = $this->getCodeExample($exampleBefore);
    $this->exampleAfter = $this->getCodeExample($exampleAfter);
}

private function getCodeExample(string $exampleName): string
{
    return file_get_contents(base_path("$exampleName.md"));
}

#2 – Extraction (Query Scope)

// ❌ 多重 where 语句，使阅读变得困难
// ❌ 意图究竟是什么呢？
User::whereNotNull('subscribed')->where('status', 'active');

// ✅ 这个新的scope方法说明了发生了什么事
// ✅ 如果我们需要了解更多细节，可以进入这个scope方法内部去了解
// ✅ "subscribed" scope 方法可在其他地方使用
User::subscribed();

#3 – Extraction (Command Handler)

Before:

protected function handle()
{
    // ❌ 这个方法包含太多代码
    $url = $this->option('url') ?: $this->ask('Please provide the URL for the import:');
    $importResponse = $this->http->get($url);
    // ❌ 进度条对用户很有用，不过却让代码显得杂乱
    $bar = $this->output->createProgressBar($importResponse->count());
    $bar->start();
    $this->userRepository->truncate();
    collect($importResponse->results)->each(function (array $attributes) use ($bar) {
        $this->userRepository->create($attributes);
        $bar->advance();
    });
    // ❌ 很难说清此处发生了哪些行为
    $bar->finish();
    $this->output->newLine();
    $this->info('Thanks. Users have been imported.');
    if ($this->option('with-backup')) {
        $this->storage
            ->disk('backups')
            ->put(date('Y-m-d').'-import.json', $response->body());
        $this->info('Backup was stored successfully.');
    }
}

After:

protected function handle(): void
{
    // ✅ handle方法是你访问该类首先会查看的方法
    // ✅ 现在可以很容易就对这个方法做了些什么有个粗略的了解
    $url = $this->option('url') ?: $this->ask('Please provide the URL for the import:');
    $importResponse = $this->http->get($url);
    $this->importUsers($importResponse->results);
    $this->saveBackupIfAsked($importResponse);
}

protected function importUsers($userData): void
{
    $bar = $this->output->createProgressBar(count($userData));
    $bar->start();
    $this->userRepository->truncate();
    collect($userData)->each(function (array $attributes) use ($bar) {
        $this->userRepository->create($attributes);
        $bar->advance();
    });
    $bar->finish();
    $this->output->newLine();
    $this->info('Thanks. Users have been imported.');
}

protected function saveBackupIfAsked(Response $response): void
{
    if ($this->option('with-backup')) {
        $this->storage
            ->disk('backups')
            ->put(date('Y-m-d').'-import.json', $response->body());
        $this->info('Backup was stored successfully.');
    }
}

#2 – Early Return

Before:

public function calculateScore(User $user): int
{
    if ($user->inactive) {
        $score = 0;
    } else {
        // ❌ 怎么又有一个 "if"?
        if ($user->hasBonus) {
            $score = $user->score + $this->bonus;
        } else {
            // ❌ 由于存在多个层级，大费眼神 ?
            $score = $user->score;
        }
    }
    return $score;
}

After:

public function calculateScore(User $user): int
{
    // ✅ 边缘用例提前检测
    if ($user->inactive) {
        return 0;
    }
    // ✅ 每个用例都有自己的代码块，使得更容易跟进
    if ($user->hasBonus) {
        return $user->score + $this->bonus;
    }
    return $user->score;
}

Before:

public function sendInvoice(Invoice $invoice): void
{
    if($user->notificationChannel === 'Slack')
    {
        $this->notifier->slack($invoice);
    } else {
        // ❌ 即使是简单的ELSE都影响代码的可读性
        $this->notifier->email($invoice);
    }
}

After:

public function sendInvoice(Invoice $invoice): bool
{
    // ✅ 每个条件都易读
    if($user->notificationChannel === 'Slack')
    {
        return $this->notifier->slack($invoice);
    }
    // ✅ 不用再考虑ELSE 指向哪里
    return $this->notifier->email($invoice);
}

#3 – Refactor to Collections

Before (score aggregation):

// ❌ 这里我们有一个临时变量 
$score = 0;
// ❌ 用循环没有问题，不过可读性还是有改善空间
foreach($this->playedGames as $game) {
    $score += $game->score;
}
return $score;

After:

// ✅ 集合是带有方法的对象
// ✅ sum 方法使之更具表现力
return collect($this->playedGames)
    ->sum('score');

Before (user filtering, sorting, mapping):

$users = [
    ['id'=>801,'name'=>'Peter','score'=>505,'active'=>true],
    ['id'=>844,'name'=>'Mary','score'=>704,'active'=>true],
    ['id'=>542,'name'=>'Norman','score'=>104,'active'=>false],
];
// 请求结果: 只显示活跃用户，以 score 排序  ["Mary(704)","Peter(505)"]
$users = array_filter($users, fn ($user) => $user['active']);
usort($users, fn($a, $b) => $a['score'] < $b['score']);
$userHighScoreTitles = array_map(fn($user) => $user['name'] . '(' . $user['score'] . ')', $users);
return $userHighScoreTitles;

After:

return collect($users)
    ->filter(fn($user) => $user['active'])
    ->sortBy('score')
    ->map(fn($user) => "{$user['name']} ({$user['score']})")
    ->values()
    ->toArray();

#4 – Consistency

Before (controller naming and brace style):

class UserController {
    // ❌ 确定如何命名变量(驼峰或是蛇形等)，不要混用！
    public function find($userId) {}
}
// ❌ 选择使用单数或者复数形式命名控制器，并保持一致
class InvoicesController {
    // ❌ 修改了样式，如花扣号的位置，影响可读性
    public function find($user_id) {}
}

After:

class UserController {
    // ✅ 所有变量驼峰式命名
    public function find($userId) {}
}
// ✅ 控制器命名规则一致(此处都使用单数)
class InvoiceController {
    // ✅ 花括号的位置(格式)一致，使代码更为可读
    public function find($userId) {}
}

Before (exporter method names):

class PdfExporter {
    public function handle(Collection $items): void { /* export items... */ }
}
class CsvExporter {
    public function export(Collection $items): void { /* export items... */ }
}
$pdfExport->handle();
$csvExporter->export();

After (using a common interface):

interface Exporter {
    public function export(Collection $items): void;
}
class PdfExporter implements Exporter {
    public function export(Collection $items): void { /* export items... */ }
}
class CsvExporter implements Exporter {
    public function export(Collection $items): void { /* export items... */ }
}
$pdfExport->export();
$csvExporter->export();

Refactoring ❤️ Testing

Refactoring does not change code behavior, making it safe to run existing tests after changes; therefore, write tests (or adopt TDD) before refactoring to ensure functionality remains intact.