PHP มาตรฐานโค้ดและการวิเคราะห์แบบสถิต



โค้ดที่ทีมอ่านง่ายต้องหน้าตาสม่ำเสมอ และบั๊กหลายอย่างจับได้ก่อนรันถ้ามีเครื่องมือช่วยดู บทนี้ตั้งค่า 2 อย่างที่โปรเจกต์ PHP สมัยใหม่มีเกือบทุกที่

PSR-12 — มาตรฐานการจัดรูปแบบ

PSR-12 (ต่อยอดจาก PSR-1/PSR-2) เป็นข้อตกลงของ PHP-FIG ว่าโค้ดควรหน้าตายังไง ประเด็นหลัก:

  • เยื้องด้วย 4 ช่องว่าง (ไม่ใช่ tab)
  • <?php แล้วบรรทัดถัดไป declare(strict_types=1);
  • เปิดปีกกาของ คลาส/เมธอด ขึ้นบรรทัดใหม่, ของ โครงสร้างควบคุม (if, for) อยู่บรรทัดเดียวกัน
  • 1 use ต่อบรรทัด, มีบรรทัดว่างหลังบล็อก use
  • ชื่อ: คลาส PascalCase, เมธอด/property camelCase, ค่าคงที่ UPPER_SNAKE_CASE
  • keyword และ true/false/null ตัวพิมพ์เล็ก
  • บรรทัดไม่ควรเกิน ~120 ตัวอักษร
<?php

declare(strict_types=1);

namespace App\Billing;

use App\Money;
use DateTimeImmutable;

final class Invoice
{
    public function __construct(
        private readonly string $number,
        private array $lines = [],
    ) {
    }

    public function total(): Money
    {
        $sum = 0;

        foreach ($this->lines as $line) {
            $sum += $line['amount'];
        }

        return new Money($sum);
    }
}

ข่าวดีคือ ไม่ต้องจำ — ให้เครื่องมือจัดให้

PHP-CS-Fixer — จัดรูปแบบอัตโนมัติ

composer require --dev friendsofphp/php-cs-fixer

สร้าง .php-cs-fixer.dist.php ที่ราก:

<?php

$finder = PhpCsFixer\Finder::create()
    ->in([__DIR__ . '/src', __DIR__ . '/tests']);

return (new PhpCsFixer\Config())
    ->setRules([
        '@PSR12' => true,
        '@PHP83Migration' => true,
        'array_syntax' => ['syntax' => 'short'],
        'ordered_imports' => true,
        'no_unused_imports' => true,
        'trailing_comma_in_multiline' => true,
        'single_quote' => true,
    ])
    ->setFinder($finder);

ใช้งาน:

# ดูว่าจะแก้อะไรบ้าง (ไม่แตะไฟล์)
./vendor/bin/php-cs-fixer fix --dry-run --diff

# แก้จริง
./vendor/bin/php-cs-fixer fix
   1) src/Billing/Invoice.php
      ---------- begin diff ----------
      -    public function total() : Money{
      +    public function total(): Money
      +    {
      ---------- end diff ----------

Fixed 1 of 12 files

ตั้ง IDE ให้รัน fixer ตอนเซฟ หรือให้ CI เช็ค — ทีมจะเลิกเถียงเรื่องช่องว่างถาวร

ทางเลือกอื่น: PHP_CodeSniffer (phpcs/phpcbf) หรือ Laravel Pint (เป็น wrapper ของ CS-Fixer) — เลือกตัวเดียวพอ

PHPStan — หาบั๊กโดยไม่รันโค้ด

PHPStan อ่านโค้ดแล้ววิเคราะห์ว่าอะไรจะพัง — เรียก property ที่ไม่มี, ส่ง type ผิด, ลืมเช็ค null, dead code

composer require --dev phpstan/phpstan

phpstan.dist.neon ที่ราก:

parameters:
    level: 6
    paths:
        - src
        - tests
./vendor/bin/phpstan analyse

ตัวอย่างที่มันจับได้:

<?php
class Order
{
    public function __construct(public ?Customer $customer = null) {}

    public function customerEmail(): string
    {
        return $this->customer->email;   // PHPStan: อาจเป็น null
    }
}
 ------ ---------------------------------------------------------------
  Line   src/Order.php
 ------ ---------------------------------------------------------------
  10     Cannot access property $email on Customer|null.
 ------ ---------------------------------------------------------------

แก้:

<?php
public function customerEmail(): string
{
    if ($this->customer === null) {
        throw new \LogicException('order นี้ยังไม่มี customer');
    }
    return $this->customer->email;
}

level ของ PHPStan

0 (หลวมสุด) ถึง 10 (เข้มสุด) — เริ่มโปรเจกต์ใหม่ที่ 6 แล้วค่อยไต่ขึ้น, โปรเจกต์เก่าเริ่มที่ 0 แล้วไต่ทีละขั้น แต่ละ level เพิ่มการตรวจ เช่น:

  • level 2: เมธอด/property ที่ไม่มีจริง
  • level 5: type ของ argument ที่ส่งให้ฟังก์ชัน
  • level 6: type ที่ไม่ได้ระบุ (missing typehints)
  • level 9: การใช้ mixed อย่างไม่ปลอดภัย

docblock ช่วย PHPStan เข้าใจ generics

type ของ PHP บอก “array” ได้ แต่ไม่บอกว่า array ของอะไร — เติมใน docblock:

<?php
/**
 * @param list<int> $ids
 * @return array<string, User>
 */
function loadUsers(array $ids): array
{
    // ...
}

PHPStan อ่าน @param/@return/@var พวกนี้และตรวจตาม

รวมเข้า composer scripts

{
    "scripts": {
        "cs": "php-cs-fixer fix --dry-run --diff",
        "cs:fix": "php-cs-fixer fix",
        "stan": "phpstan analyse",
        "test": "phpunit",
        "check": ["@cs", "@stan", "@test"]
    }
}
composer check      # ก่อน commit ทุกครั้ง

CI (GitHub Actions ตัวอย่างสั้น ๆ)

.github/workflows/ci.yml:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
      - run: composer install --no-interaction
      - run: composer check

เรื่องที่คนมักพลาด

  • รัน php-cs-fixer fix ครั้งแรกบนโปรเจกต์เก่าแล้ว commit รวมกับงานจริง — diff มหาศาล review ไม่ได้ แยก commit “จัดรูปแบบทั้งหมด” ออกต่างหาก
  • ตั้ง PHPStan level สูงเกินบนโค้ดเก่า — error เป็นพัน ท้อ เริ่มต่ำแล้วไต่ หรือใช้ baseline (phpstan analyse --generate-baseline)
  • เพิกเฉย PHPStan error ด้วย @phpstan-ignore พร่ำเพรื่อ — กลายเป็นไม่มีประโยชน์ แก้ต้นตอ
  • ไม่ commit ไฟล์ config (.php-cs-fixer.dist.php, phpstan.dist.neon) — ทีมได้ผลไม่ตรงกัน
  • คิดว่า linter = เทสต์ — คนละเรื่อง linter ดูรูปแบบ, PHPStan ดู type, PHPUnit ดูพฤติกรรม ต้องมีครบ
  • ให้ IDE จัดรูปแบบด้วยกฎของตัวเอง ที่ไม่ตรงกับ CS-Fixer — สู้กันไปมา ตั้ง IDE ให้เรียก CS-Fixer แทน

สรุป

  • PSR-12 = มาตรฐานหน้าตาโค้ดของชุมชน — ไม่ต้องจำ ให้เครื่องมือจัดให้
  • PHP-CS-Fixer จัดรูปแบบอัตโนมัติ (fix --dry-run ดูก่อน, fix แก้จริง) ตั้ง rule @PSR12
  • PHPStan หาบั๊ก type/null/เมธอดไม่มีจริง โดยไม่รันโค้ด — เริ่ม level 6 (โปรเจกต์ใหม่), ใช้ docblock บอก generics
  • รวมทุกอย่างใน composer check แล้วให้ CI รันทุก push

บทถัดไปว่าด้วย error reporting — ความต่างของ error/warning/notice กับ exception การตั้งค่า display_errors/log_errors และ error handler สำหรับ dev เทียบ production