PHP Namespace (İsim Alanı): namespace, use ve Takma Adlar

Bir PHP isim alanı sınıfları, fonksiyonları ve sabitleri bir önek altına koyar, böylece adları başkasınınkiyle çakışamaz. Onu bir dosyanın ilk deyimi olarak namespace App\Models; ile tanımlarsınız ve diğer dosyalar sınıfa \App\Models\User olarak başvurur ya da onu use App\Models\User; ile içe aktarıp yalnızca User yazar.

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

İsim alanının içinde User App\Models\User demektir. User::class hiçbir şey oluşturmadan tam adı bir dizge olarak verir; bu, loglama ve otomatik yükleyiciler için kullanışlıdır.

Bir dosyada iki isim alanı

Gerçek bir proje her dosyaya bir isim alanı koyar. Kendi içinde bütün bir demo için, her biri süslü parantezle sarıldığında bir dosya birkaç isim alanı tutabilir. Hiçbir isim alanına ait olmayan kod namespace { } içine girer:

<?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 adlı iki sınıf yan yana yaşar, çünkü tam adları farklıdır. Kütüphaneler kurduğunuzda isim alanlarının çözdüğü sorun tam olarak budur: sizin Order sınıfınız, bir ödeme kütüphanesinin Order sınıfı ve bir PDF kütüphanesinin Order sınıfı artık çakışmaz.

use ile içe aktarma ve as ile takma ad

Her yerde \Shop\Order yazmak kalabalık yaratır. Bir dosyanın (veya isim alanı bloğunun) başındaki use bir adı içe aktarır, böylece kısa biçimi kullanabilirsiniz. İki içe aktarma aynı kısa adla bitecekse as onlardan birine farklı bir ad verir:

<?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 yalnızca dosyanın geri kalanı için kısa bir ad oluşturur. Bir dosya yüklemez veya kod çalıştırmaz ve sınıf henüz var olsun ya da olmasın aynı şekilde çalışır. Gruplanmış içe aktarmalara da izin verilir: use Shop\{Order, Invoice};.

use function ve use const

Bir isim alanındaki fonksiyonlar ve sabitler use function ve use const ile içe aktarılır:

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

Global sınıflar ters eğik çizgi ister

Bir isim alanının içinde nitelenmemiş bir sınıf adı o isim alanına göre çözümlenir, bu yüzden namespace App; içindeki new DateTime() App\DateTime arar. Fonksiyonlar ve sabitler farklıdır: App\strlen yoksa PHP global strlen fonksiyonuna geri döner. Sınıflar asla geri dönmez.

<?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) aynı nedenle bir ters eğik çizgi gerektirdi: o olmadan PHP App\Error arar, gerçek hatayla asla eşleşmez ve betik yakalanmamış bir Error ile dururdu. Bunu ya yukarıdaki gibi baştaki bir ters eğik çizgiyle ya da dosyanın başına use DateTime; ekleyerek düzeltin. Aynısı \Exception, \Throwable ve diğer her yerleşik sınıf için de geçerlidir; onları yakalamak için try catch sayfasına bakın.

Otomatik yükleme ve PSR-4

Bir projede her sınıf kendi dosyasında yaşar ve dosya yolu isim alanını takip eder. PSR-4 bu kuraldır: bir isim alanı öneki bir temel klasöre eşlenir ve adın geri kalanı yol olur. spl_autoload_register() ile kaydedilen bir otomatik yükleyici, sınıf ilk kullanıldığında sınıf dosyasını yükler. Bu blok diske iki sınıf dosyası yazar ve onları otomatik yükler:

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

Her sınıf dosyası, sınıfa ilk ihtiyaç duyulduğu anda bir kez yüklenir. Gerçek projelerde bu fonksiyonu kendiniz yazmazsınız: Composer onu composer.json içindeki birkaç satırdan üretir:

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

composer dump-autoload sonrasında giriş betiğinizin başındaki tek bir require __DIR__ . '/vendor/autoload.php'; her App\... sınıfını ihtiyaç anında yükler.

Hatalara yol açan isim alanı kuralları

• namespace dosyadaki ilk deyim olmalıdır. Ondan önce yalnızca declare(strict_types=1); ve yorumlar gelebilir.
• use içe aktarmaları dosya başınadır. Bir sınıfı index.php içinde içe aktarmak kısa adın dahil edilen bir dosyanın içinde çalışmasını sağlamaz; her dosyanın kendi use satırları olmalıdır.
• use dosyanın veya isim alanı bloğunun en üst seviyesine aittir. Bir sınıf gövdesinin içinde use başka bir şey demektir: bir trait içeri alır.
• Dizgeler asla çözümlenmez: $class = 'User'; new $class(); global User sınıfını arar. Tam adı, tercihen User::class ile saklayın.

Sonuncusu hızlı bir kontrolü hak ediyor:

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