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, เมธอด/propertycamelCase, ค่าคงที่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/phpstanphpstan.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