¿Cómo funcionan los espacios de nombres en PHP?

Question

Accepted Answer

Los **espacios de nombres** organizan código PHP y previenen **colisiones de nombres** entre clases, funciones y constantes — es esencial conforme las aplicaciones crecen y usan paquetes de terceros. Funcionan como directorios para nombres de clases e se integran con autocarga de Composer (PSR-4).

## El problema que resuelven los espacios de nombres

```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.
```

## Declarando y usando espacios de nombres

```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();
    }
}
```

Un archivo declara su `namespace`, y otros archivos `use` (importan) clases para referirse a ellas con nombre abreviado. El nombre completamente calificado (`\App\Models\User`) es globalmente único.

## Los espacios de nombres se asignan a directorios (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).
```

## Importando funciones, constantes y el espacio de nombres global

```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)
```

## Por qué es importante

Los espacios de nombres son esenciales para organizar código PHP moderno y son fundamentales para cómo funciona todo el ecosistema.

Entenderlos es importante porque resuelven el problema crítico de **colisiones de nombres** — sin espacios de nombres, tus clases entrarían en conflicto entre sí y con los muchos paquetes de terceros que una aplicación real usa (dos clases `User` no pueden coexistir), haciendo que grandes aplicaciones y ecosistemas de paquetes sean imposibles.

Los espacios de nombres dan a cada clase un nombre completamente calificado único, y las **importaciones `use`** te permiten referirte a clases por nombre abreviado de manera limpia.

Más importante aún, los espacios de nombres se integran con **la autocarga de Composer vía PSR-4**, donde la estructura del espacio de nombres refleja la estructura de directorios para que las clases se carguen automáticamente bajo demanda — esta es la base de la estructura moderna de proyectos PHP y la gestión de dependencias.

Ya que cada marco PHP moderno, paquete y aplicación está organizado con espacios de nombres (y no puedes usar paquetes Composer sin entenderlos), saber cómo declarar espacios de nombres, importar clases con `use` y cómo se asignan a directorios para autocarga es conocimiento fundamental, cotidiano para cualquier desarrollo PHP moderno.

Los espacios de nombres, Composer y la autocarga PSR-4 juntos definen cómo se estructuran los proyectos PHP contemporáneos.