How do namespaces work in PHP?

Question

Accepted Answer

**Namespaces** organize PHP code and prevent **naming collisions** between classes, functions, and constants — essential as applications grow and use third-party packages. They work like directories for class names, and integrate with Composer autoloading (PSR-4).

## The problem namespaces solve

```text
Without namespaces, two classes named `User` (yours and a library's) would COLLIDE
("cannot redeclare class"). Namespaces give each a unique fully-qualified name.
```

## Declaring and using namespaces

```php
<?php
// declare a namespace at the top of the file (matches the directory, PSR-4)
namespace App\Models;

class User {            // fully-qualified name: App\Models\User
    // ...
}
```

```php
<?php
namespace App\Controllers;

use App\Models\User;            // IMPORT a class so you can use its short name
use App\Services\Mailer as MailService;   // import with an ALIAS

class UserController {
    public function index() {
        $user = new User();      // short name works thanks to the `use` import
        // or use the fully-qualified name: new \App\Models\User();
    }
}
```

A file declares its `namespace`, and other files `use` (import) classes to refer to them by short name. The fully-qualified name (`\App\Models\User`) is globally unique.

## Namespaces map to directories (PSR-4)

```text
Namespace            File path
App\Models\User   →  src/Models/User.php
App\Services\Mailer → src/Services/Mailer.php
→ PSR-4 autoloading: the namespace structure mirrors the folder structure, so
  Composer can find and load each class automatically (no manual require).
```

## Importing functions, constants, and the global namespace

```php
use function App\Helpers\format;     // import a function
use const App\Config\VERSION;        // import a constant

\strlen("x");    // a leading \ = the GLOBAL namespace (built-in functions)
```

## Why it matters

Namespaces are essential for organizing modern PHP code and are fundamental to how the entire ecosystem works.

Understanding them is important because they solve the critical problem of **naming collisions** — without namespaces, your classes would conflict with each other and with the many third-party packages a real application uses (two `User` classes can't coexist), making large applications and package ecosystems impossible.

Namespaces give every class a unique fully-qualified name, and the **`use` imports** let you reference classes by short names cleanly.

Most importantly, namespaces integrate with **Composer autoloading via PSR-4**, where the namespace structure mirrors the directory structure so classes are loaded automatically on demand — this is the foundation of modern PHP project structure and dependency management.

Since every modern PHP framework, package, and application is organized with namespaces (and you can't use Composer packages without understanding them), knowing how to declare namespaces, import classes with `use`, and how they map to directories for autoloading is fundamental, everyday knowledge for any modern PHP development.

Namespaces, Composer, and PSR-4 autoloading together define how contemporary PHP projects are structured.