فضاءات الأسماء في 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 الاسم الكامل نصًا دون إنشاء أي شيء، وهذا مفيد للتسجيل وللمحمّلات التلقائية.

فضاءا أسماء في ملف واحد

يضع المشروع الحقيقي فضاء أسماء واحدًا في كل ملف. ولعرض مستقل، يمكن لملف واحد أن يحمل عدة فضاءات أسماء عندما يُحاط كل منها بأقواس معقوصة. والشيفرة التي لا تنتمي إلى أي فضاء أسماء توضع في 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 جنبًا إلى جنب لأن اسميهما الكاملين مختلفان. وهذه بالضبط المشكلة التي تحلها فضاءات الأسماء حين تثبّت مكتبات: لم يعد Order الخاص بك وOrder في مكتبة الدفع وOrder في مكتبة PDF تتعارض.

الاستيراد بـ use والتسمية البديلة بـ as

كتابة \Shop\Order في كل مكان مزعجة. تستورد use في أعلى الملف (أو كتلة فضاء الأسماء) اسمًا فتستخدم الصيغة القصيرة. وعندما ينتهي استيرادان بالاسم القصير نفسه، تعطي 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";
}

الأصناف العامة تحتاج إلى شرطة مائلة عكسية

داخل فضاء أسماء، يُحل اسم الصنف غير المؤهل نسبةً إلى ذلك الفضاء، فتبحث new DateTime() داخل namespace App; عن 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() ملف الصنف أول مرة يُستخدم فيها الصنف. تكتب هذه الكتلة ملفي صنفين على القرص وتحمّلهما تلقائيًا:

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

يُحمَّل كل ملف صنف مرة واحدة، لحظة الحاجة إلى الصنف أول مرة. وفي المشاريع الحقيقية لا تكتب هذه الدالة بنفسك: يولّدها Composer من بضعة أسطر في composer.json:

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

بعد composer dump-autoload، يحمّل سطر require __DIR__ . '/vendor/autoload.php'; واحد في بداية سكربت الدخول كل صنف App\... عند الطلب.

قواعد فضاءات الأسماء التي تسبب أخطاء

• يجب أن تكون namespace الجملة الأولى في الملف. ولا يجوز أن يسبقها إلا declare(strict_types=1); والتعليقات.
• عبارات use خاصة بكل ملف. استيراد صنف في index.php لا يجعل الاسم القصير يعمل داخل ملف مُضمَّن؛ يحتاج كل ملف إلى أسطر 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";
}