Namespace trong PHP: namespace, use và alias

Namespace trong PHP đặt các lớp, hàm và hằng số dưới một tiền tố để tên của chúng không thể trùng với tên của người khác. Bạn khai báo nó bằng namespace App\Models; làm câu lệnh đầu tiên của tệp, và các tệp khác gọi lớp đó là \App\Models\User, hoặc import nó bằng use App\Models\User; rồi chỉ cần viết User.

<?php
namespace App\Models;

class User
{
    public function __construct(public string $name) {}
}

function greet(User $u): string
{
    return "Hello, {$u->name}";
}

$u = new User('Ada');
echo greet($u), "\n";
echo User::class, "\n";
echo __NAMESPACE__, "\n";
echo get_class($u), "\n";

Bên trong namespace, User nghĩa là App\Models\User. User::class cho ra tên đầy đủ dưới dạng chuỗi mà không tạo ra gì cả, rất tiện cho việc ghi log và cho autoloader.

Hai namespace trong một tệp

Một dự án thực tế đặt mỗi namespace trong một tệp. Với một ví dụ gói gọn, một tệp có thể chứa nhiều namespace nếu mỗi namespace được bọc trong cặp ngoặc nhọn. Code không thuộc namespace nào đặt trong namespace { }:

<?php
namespace Shop {
    class Order
    {
        public function label(): string { return 'shop order'; }
    }
}

namespace Kitchen {
    class Order
    {
        public function label(): string { return 'kitchen ticket'; }
    }
}

namespace {
    // Global code: use the fully qualified names
    $a = new \Shop\Order();
    $b = new \Kitchen\Order();
    echo get_class($a), ': ', $a->label(), "\n";
    echo get_class($b), ': ', $b->label(), "\n";
}

Hai lớp cùng tên Order nằm cạnh nhau vì tên đầy đủ của chúng khác nhau. Đó chính là vấn đề namespace giải quyết khi bạn cài thư viện: Order của bạn, Order của một thư viện thanh toán và Order của một thư viện PDF không còn xung đột.

Import bằng use, đặt alias bằng as

Viết \Shop\Order ở khắp nơi thì rườm rà. use ở đầu tệp (hoặc đầu khối namespace) import một tên để bạn dùng dạng ngắn. Khi hai lệnh import có cùng tên ngắn ở cuối, as đặt cho một trong hai một tên khác:

<?php
namespace Shop {
    class Order { public string $kind = 'shop'; }
    class Invoice { public string $kind = 'invoice'; }
}

namespace Kitchen {
    class Order { public string $kind = 'kitchen'; }
}

namespace App {
    use Shop\Order;
    use Shop\Invoice;
    use Kitchen\Order as KitchenOrder;

    $orders = [new Order(), new KitchenOrder(), new Invoice()];
    foreach ($orders as $o) {
        echo get_class($o), ' -> ', $o->kind, "\n";
    }
    echo KitchenOrder::class, "\n";
}

use chỉ tạo một tên ngắn cho phần còn lại của tệp. Nó không nạp tệp hay chạy code, và hoạt động như nhau dù lớp đã tồn tại hay chưa. Bạn cũng có thể import theo nhóm: use Shop\{Order, Invoice};.

use function và use const

Hàm và hằng số trong một namespace được import bằng use function và use const:

<?php
namespace Utils\Text {
    const ELLIPSIS = '...';

    function shorten(string $s, int $max): string
    {
        return mb_strlen($s) > $max ? mb_substr($s, 0, $max) . ELLIPSIS : $s;
    }
}

namespace App {
    use function Utils\Text\shorten;
    use const Utils\Text\ELLIPSIS;

    echo shorten('Namespaces keep names apart', 10), "\n";
    echo 'Marker: ', ELLIPSIS, "\n";
    echo \Utils\Text\shorten('Fully qualified call works too', 15), "\n";
}

Lớp toàn cục cần dấu gạch chéo ngược

Bên trong một namespace, tên lớp không có tiền tố được tìm tương đối theo namespace đó, nên new DateTime() bên trong namespace App; sẽ tìm App\DateTime. Hàm và hằng số thì khác: nếu App\strlen không tồn tại, PHP quay về hàm strlen toàn cục. Lớp thì không bao giờ quay về.

<?php
namespace App;

echo strlen('works'), "\n";        // functions fall back to global
echo PHP_INT_SIZE, "\n";               // so do constants

try {
    $d = new DateTime('2026-03-14');
} catch (\Error $e) {
    echo $e->getMessage(), "\n";
}

$d = new \DateTime('2026-03-14');  // leading backslash: the global class
echo $d->format('D, d M Y'), "\n";

catch (\Error $e) cũng cần dấu gạch chéo ngược vì cùng lý do: không có nó, PHP sẽ tìm App\Error, không bao giờ khớp với lỗi thật, và script dừng lại với một Error không được bắt. Sửa bằng dấu gạch chéo ngược ở đầu như trên, hoặc bằng use DateTime; ở đầu tệp. Điều này cũng đúng với \Exception, \Throwable và mọi lớp có sẵn khác; xem try catch để biết cách bắt chúng.

Autoload và PSR-4

Trong một dự án, mỗi lớp nằm trong tệp riêng, và đường dẫn tệp đi theo namespace. PSR-4 là quy ước cho việc này: một tiền tố namespace ánh xạ tới một thư mục gốc, và phần còn lại của tên trở thành đường dẫn. Một autoloader đăng ký bằng spl_autoload_register() sẽ nạp tệp của lớp vào lần đầu lớp đó được dùng. Khối code này ghi hai tệp lớp ra đĩa rồi autoload chúng:

<?php
// Create src/Models/User.php and src/Services/Mailer.php
is_dir('src/Models') || mkdir('src/Models', 0777, true);
is_dir('src/Services') || mkdir('src/Services', 0777, true);
file_put_contents('src/Models/User.php', '<?php
namespace App\Models;
class User { public function __construct(public string $email) {} }
');
file_put_contents('src/Services/Mailer.php', '<?php
namespace App\Services;
use App\Models\User;
class Mailer { public function welcome(User $u): string { return "Welcome mail to {$u->email}"; } }
');

// A minimal PSR-4 autoloader: App\ maps to src/
spl_autoload_register(function (string $class) {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class\n";
    require $file;
});

$mailer = new App\Services\Mailer();
echo $mailer->welcome(new App\Models\User('ada@example.com')), "\n";

Mỗi tệp lớp chỉ được nạp một lần, đúng lúc lớp đó được cần đến lần đầu. Trong dự án thực tế, bạn không tự viết hàm này: Composer tạo nó từ vài dòng trong composer.json:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Sau composer dump-autoload, chỉ một dòng require __DIR__ . '/vendor/autoload.php'; ở đầu script khởi chạy là nạp được mọi lớp App\... khi cần.

Những quy tắc namespace hay gây lỗi

• namespace phải là câu lệnh đầu tiên trong tệp. Chỉ declare(strict_types=1); và chú thích được đứng trước nó.
• Lệnh import use có hiệu lực theo từng tệp. Import một lớp trong index.php không làm tên ngắn hoạt động bên trong một tệp được include; mỗi tệp cần các dòng use riêng.
• use đặt ở cấp ngoài cùng của tệp hoặc khối namespace. Bên trong thân lớp, use mang nghĩa khác: nó đưa một trait vào lớp.
• Chuỗi không bao giờ được tìm theo namespace: $class = 'User'; new $class(); sẽ tìm User toàn cục. Hãy lưu tên đầy đủ, tốt nhất là bằng User::class.

Quy tắc cuối đáng để kiểm tra nhanh:

<?php
namespace App\Models {
    class User {}
}

namespace App {
    use App\Models\User;

    $short = 'User';
    var_dump(class_exists($short));         // looks for global User
    var_dump(class_exists(User::class));    // App\Models\User

    $class = User::class;
    echo get_class(new $class()), "\n";
}