PHP Namespaces

Also Known As

TL;DR

Explanation

PHP namespaces (5.3+) encapsulate classes, interfaces, traits, functions, and constants into named scopes using namespace App\Controller. The fully qualified class name (FQCN) like App\Controller\HomeController maps directly to a file path under PSR-4. Use statements (use App\Service\UserService) alias FCQNs for cleaner code. The global namespace is accessed with a leading backslash (\Exception). Namespaces are essential for composer autoloading and preventing collisions between third-party packages.

Common Misconception

Why It Matters

Common Mistakes

• Mixing namespaced and non-namespaced code in the same project — it creates unpredictable autoloading behaviour.
• Forgetting that the global namespace requires a leading backslash inside a namespace (\Exception, not Exception).
• Using deeply nested namespaces (App\Modules\Orders\Domain\Entities\OrderLine) when shallower ones suffice.
• Not aliasing long namespace imports with use — leads to unreadable fully-qualified class names inline.

Code Examples

// No namespace — class name collisions in large projects:
class Logger {} // Conflicts with any other Logger class
class Request {} // Conflicts with framework's Request class

// With namespaces — no collision:
namespace App\Logging;
class Logger {} // App\Logging\Logger

namespace Vendor\Http;
class Request {} // Vendor\Http\Request — distinct

<?php
// File: src/Domain/Order/OrderService.php
declare(strict_types=1);

namespace App\Domain\Order;

use App\Domain\User\User;          // import from another namespace
use App\Infrastructure\Mailer;
use DateTimeImmutable;              // global namespace class
use InvalidArgumentException as InvalidArg; // alias

class OrderService {
    public function place(User $user, array $items): Order {
        if (empty($items)) {
            throw new InvalidArg('Items cannot be empty');
        }
        return new Order($user, $items, new DateTimeImmutable());
    }
}

References

• ↗ https://www.php.net/manual/en/language.namespaces.php

Tags

Related Terms