PHP namespace และ autoloading (PSR-4)



พอโปรเจกต์โต มีคลาสหลายสิบตัว ชื่อจะเริ่มชนกัน (User ของเราชนกับ User ของไลบรารี) และการ require ไฟล์ทีละอันจะยุ่งมาก namespace + autoloading แก้ทั้งสอง

ปัญหาที่ namespace แก้

ถ้าไม่มี namespace ทุกคลาสอยู่ใน “พื้นที่ชื่อเดียว” — ประกาศ class Logger สองที่ = fatal error

ประกาศ namespace

namespace ต้องเป็นคำสั่งแรกในไฟล์ (หลัง <?php และ declare):

<?php
// ไฟล์: src/Payment/StripeGateway.php
declare(strict_types=1);

namespace App\Payment;

class StripeGateway
{
    public function charge(int $satang): string
    {
        return 'ch_xxx';
    }
}

ชื่อเต็ม (fully-qualified name) ของคลาสนี้คือ App\Payment\StripeGateway

<?php
// ไฟล์: src/Log/Logger.php
namespace App\Log;

class Logger
{
    public function info(string $m): void { echo "[info] $m\n"; }
}

ตอนนี้มี App\Payment\StripeGateway กับ App\Log\Logger ไม่ชนกับใคร

use — นำเข้ามาใช้แบบสั้น

<?php
declare(strict_types=1);

namespace App;

use App\Payment\StripeGateway;
use App\Log\Logger;

$gateway = new StripeGateway();
$logger = new Logger();

ไม่มี use ก็เขียนชื่อเต็มได้ (ขึ้นต้นด้วย \):

<?php
$gateway = new \App\Payment\StripeGateway();

เปลี่ยนชื่อตอน import ด้วย as (แก้ปัญหาชื่อชน):

<?php
use App\Log\Logger;
use Monolog\Logger as MonologLogger;

import ฟังก์ชันและ constant ก็ได้:

<?php
use function App\Helpers\format_money;
use const App\Config\VERSION;

คลาสในตัว PHP อยู่ที่ namespace ราก

ในไฟล์ที่มี namespace การอ้าง DateTimeImmutable, PDO, Exception ต้องนำหน้าด้วย \ หรือ use:

<?php
namespace App\Order;

use DateTimeImmutable;
use InvalidArgumentException;

class Order
{
    public function __construct(
        public readonly DateTimeImmutable $createdAt,   // ต้อง use หรือ \DateTimeImmutable
    ) {}

    public function validate(): void
    {
        throw new \RuntimeException('...');   // \ นำหน้า
    }
}

ลืม \ แล้ว PHP จะหา App\Order\DateTimeImmutable ไม่เจอ — error ที่งงบ่อยสำหรับมือใหม่

PSR-4 — namespace ต้องตรงกับโฟลเดอร์

PSR-4 คือมาตรฐานที่บอกว่า “namespace map ไปเป็น path ของไฟล์ยังไง” ทำให้ autoloader หาไฟล์เจอ

namespace prefixโฟลเดอร์ฐาน
App\src/

ผลคือ:

คลาสไฟล์
App\Payment\StripeGatewaysrc/Payment/StripeGateway.php
App\Log\Loggersrc/Log/Logger.php
App\Usersrc/User.php

กฎ: ตัดตรงกับ prefix ออก แทนที่ \ ด้วย / เติม .php — และ ชื่อไฟล์ต้องตรงตัวพิมพ์เป๊ะกับชื่อคลาส

autoloading ด้วยมือ (ก่อนใช้ Composer)

spl_autoload_register() ลงทะเบียนฟังก์ชันที่ PHP จะเรียกเมื่อเจอคลาสที่ยังไม่โหลด:

<?php
// ไฟล์: bootstrap.php
declare(strict_types=1);

spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    $baseDir = __DIR__ . '/src/';

    // คลาสนี้อยู่ใน namespace ของเราไหม
    if (!str_starts_with($class, $prefix)) {
        return;
    }

    $relative = substr($class, strlen($prefix));          // Payment\StripeGateway
    $file = $baseDir . str_replace('\\', '/', $relative) . '.php';

    if (is_file($file)) {
        require $file;
    }
});

ใช้งาน:

<?php
// ไฟล์: index.php
require __DIR__ . '/bootstrap.php';

use App\Payment\StripeGateway;

$gateway = new StripeGateway();      // PHP เรียก autoloader -> require src/Payment/StripeGateway.php
echo $gateway->charge(10000), "\n";

ไม่ต้อง require ไฟล์คลาสเองอีกต่อไป — เขียน new หรืออ้างชื่อคลาส แล้ว autoloader จัดการ

ในบทหน้า Composer จะสร้าง autoloader PSR-4 ให้อัตโนมัติ เราแค่เขียนใน composer.json ว่า "App\\": "src/" — โค้ดข้างบนคือสิ่งที่มันทำให้เบื้องหลัง

จัด namespace ยังไงดี

  • prefix เป็นชื่อโปรเจกต์/บริษัท: App\, Acme\Shop\
  • แบ่งตามโดเมนของปัญหา ไม่ใช่ตามชนิดเทคนิค: App\Order\, App\Payment\, App\Catalog\ ดีกว่า App\Models\, App\Services\, App\Interfaces\
  • 1 ไฟล์ = 1 คลาส/interface/enum/trait และชื่อไฟล์ = ชื่อคลาส

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

  • namespace ไม่ได้อยู่บนสุด — ต้องเป็นคำสั่งแรกหลัง <?php/declare ไม่งั้น fatal error
  • ลืม \ หน้าคลาสในตัว PHP ในไฟล์ที่มี namespace — new DateTime() กลายเป็น new App\...\DateTime() ใช้ \DateTime หรือ use DateTime;
  • ชื่อไฟล์ตัวพิมพ์ไม่ตรงชื่อคลาส — บน Windows/macOS อาจรอด แต่บน Linux (production) จะหาไฟล์ไม่เจอ
  • หลาย namespace ในไฟล์เดียว — ทำได้ทางเทคนิคแต่สับสนมาก อย่าทำ
  • use App\Payment\StripeGateway as Gateway; แล้วยังเขียน new StripeGateway() — หลัง alias ต้องใช้ชื่อ alias
  • คิดว่า use โหลดไฟล์ — use แค่ทำ alias ชื่อ การโหลดไฟล์เป็นหน้าที่ของ autoloader

สรุป

  • namespace App\Payment; บนสุดของไฟล์ ทำให้ชื่อคลาสไม่ชนกัน
  • use App\Payment\StripeGateway; นำเข้าเพื่อเขียนชื่อสั้น, as เปลี่ยนชื่อ
  • ในไฟล์ที่มี namespace คลาสในตัว PHP ต้อง \DateTime หรือ use DateTime;
  • PSR-4: namespace map เป็น path (App\ → src/), ชื่อไฟล์ = ชื่อคลาสเป๊ะ
  • spl_autoload_register() ให้ PHP โหลดไฟล์คลาสอัตโนมัติ — Composer ทำให้ในบทหน้า

บทถัดไปว่าด้วย magic methods — __get, __set, __call, __toString, __invoke ที่ทำให้อ็อบเจกต์มีพฤติกรรมพิเศษ พร้อมข้อควรระวัง