namespace ב-PHP: namespace, use וכינויים

namespace ב-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";

בתוך ה-namespace, User פירושו App\Models\User. User::class נותן את השם המלא כמחרוזת בלי ליצור שום דבר, וזה שימושי ללוגים ול-autoloaders.

שני namespaces בקובץ אחד

פרויקט אמיתי שם namespace אחד בכל קובץ. בהדגמה עצמאית, קובץ אחד יכול להחזיק כמה namespaces כשכל אחד עטוף בסוגריים מסולסלים. קוד שלא שייך לשום namespace נכנס ל-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 חיות זו לצד זו כי השמות המלאים שלהן שונים. זו בדיוק הבעיה ש-namespaces פותרים ברגע שמתקינים ספריות: ה-Order שלכם, ה-Order של ספריית תשלומים וה-Order של ספריית PDF כבר לא מתנגשים.

ייבוא עם use וכינוי עם as

כתיבה של \Shop\Order בכל מקום רועשת. use בראש קובץ (או בלוק namespace) מייבא שם כך שאפשר להשתמש בצורה הקצרה. כששני ייבואים היו מסתיימים באותו שם קצר, 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

פונקציות וקבועים ב-namespace מיובאים עם 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, שם מחלקה בלי קידומת מתפרש ביחס ל-namespace הזה, ולכן 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

בפרויקט, כל מחלקה חיה בקובץ משלה, ונתיב הקובץ עוקב אחרי ה-namespace. PSR-4 היא המוסכמה: קידומת של namespace ממופה לתיקיית בסיס, ושאר השם הופך לנתיב. autoloader שנרשם עם 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 שגורמים לשגיאות

• namespace חייבת להיות הפקודה הראשונה בקובץ. רק declare(strict_types=1); והערות יכולים לבוא לפניה.
• ייבואי use הם לכל קובץ בנפרד. ייבוא של מחלקה ב-index.php לא גורם לשם הקצר לעבוד בתוך קובץ שנכלל; כל קובץ צריך שורות use משלו.
• use שייכת לרמה העליונה של הקובץ או של בלוק ה-namespace. בתוך גוף של מחלקה, ל-use יש משמעות אחרת: היא מושכת פנימה trait.
• מחרוזות אף פעם לא מתפרשות: $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";
}