PHPの名前空間：namespace、use、エイリアス

PHPの名前空間は、クラス、関数、定数を接頭辞の下に置き、その名前がほかの誰かのものと衝突しないようにします。ファイルの最初の文としてnamespace App\Models;と宣言し、ほかのファイルではそのクラスを\App\Models\Userとして参照するか、use App\Models\User;でインポートして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";

名前空間の中では、UserはApp\Models\Userを意味します。User::classは何も作らずに完全な名前を文字列として返すので、ログやオートローダーに便利です。

1つのファイルに2つの名前空間

本物のプロジェクトでは、1つのファイルに1つの名前空間を置きます。自己完結したデモなら、それぞれを波括弧で包めば1つのファイルに複数の名前空間を書けます。どの名前空間にも属さないコードは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";
}

完全な名前が違うので、Orderという2つのクラスが並んで存在できます。ライブラリをインストールし始めると名前空間が解決してくれるのが、まさにこの問題です。自分のOrder、決済ライブラリのOrder、PDFライブラリのOrderがもう衝突しません。

useでインポートし、asで別名を付ける

どこでも\Shop\Orderと書くのは煩雑です。ファイル（または名前空間のブロック）の先頭のuseは名前をインポートし、短い形で使えるようにします。2つのインポートが同じ短い名前で終わるときは、asで一方に別の名前を付けます。

<?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はファイルの残りの部分のために短い名前を作るだけです。ファイルを読み込んだりコードを実行したりはせず、クラスがまだ存在していてもいなくても同じように動きます。まとめてインポートすることもできます：use Shop\{Order, Invoice};。

use functionとuse const

名前空間の中の関数と定数は、use functionと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";
}

グローバルなクラスにはバックスラッシュが必要

名前空間の中では、修飾のないクラス名はその名前空間からの相対で解決されるので、namespace App;の中のnew DateTime()はApp\DateTimeを探します。関数と定数は違い、App\strlenが存在しなければ、PHPはグローバルなstrlenにフォールバックします。クラスは決してフォールバックしません。

<?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)にバックスラッシュが必要だったのも同じ理由です。付けなければPHPはApp\Errorを探し、本物のエラーには決して一致せず、スクリプトはキャッチされないErrorで止まってしまいます。上のように先頭にバックスラッシュを付けるか、ファイルの先頭にuse DateTime;を書いて直します。同じことが\Exception、\Throwable、そのほかすべての組み込みクラスに当てはまります。それらのキャッチについてはtry catchを参照してください。

オートロードとPSR-4

プロジェクトでは、各クラスが自分のファイルに置かれ、ファイルのパスが名前空間に従います。その規約がPSR-4で、名前空間の接頭辞が基準となるフォルダーに対応し、名前の残りがパスになります。spl_autoload_register()で登録したオートローダーは、クラスが最初に使われたときにそのクラスのファイルを読み込みます。このブロックは2つのクラスのファイルをディスクに書き出し、それらをオートロードします。

<?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";

各クラスのファイルは、そのクラスが最初に必要になった瞬間に1回だけ読み込まれます。本物のプロジェクトではこの関数を自分で書くことはなく、composer.jsonの数行からComposerが生成します。

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

composer dump-autoloadのあとは、エントリーとなるスクリプトの最初にrequire __DIR__ . '/vendor/autoload.php';と1行書くだけで、すべてのApp\...クラスが必要に応じて読み込まれます。

エラーの原因になる名前空間のルール

• namespaceはファイルの最初の文でなければなりません。その前に書けるのはdeclare(strict_types=1);とコメントだけです。
• useのインポートはファイルごとです。index.phpでクラスをインポートしても、includeしたファイルの中では短い名前は使えません。各ファイルに自分のuse行が必要です。
• useはファイルか名前空間のブロックのトップレベルに書きます。クラスの本体の中のuseは別の意味で、トレイトを取り込みます。
• 文字列は決して解決されません。$class = 'User'; new $class();はグローバルなUserを探します。完全な名前を、できればUser::classで保存しましょう。

最後のものは手早く確認しておく価値があります。

<?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";
}