Namespaces en PHP: namespace, use y alias

Un namespace de PHP pone clases, funciones y constantes bajo un prefijo para que sus nombres no choquen con los de otros. Lo declaras con namespace App\Models; como primera sentencia de un archivo, y los demás archivos se refieren a la clase como \App\Models\User, o la importan con use App\Models\User; y escriben solo 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";

Dentro del namespace, User significa App\Models\User. User::class da el nombre completo como cadena sin crear nada, algo útil para los logs y para los autoloaders.

Dos namespaces en un archivo

Un proyecto real pone un namespace en cada archivo. Para una demo autocontenida, un archivo puede tener varios namespaces si cada uno va entre llaves. El código que no pertenece a ningún namespace va en 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";
}

Dos clases llamadas Order conviven porque sus nombres completos son distintos. Es justo el problema que resuelven los namespaces en cuanto instalas librerías: tu Order, el Order de una librería de pagos y el Order de una librería de PDF ya no chocan.

Importar con use y crear alias con as

Escribir \Shop\Order en todas partes es ruidoso. use al principio de un archivo (o de un bloque de namespace) importa un nombre para que puedas usar la forma corta. Cuando dos importaciones acabarían en el mismo nombre corto, as le da a una de ellas otro nombre:

<?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 solo crea un nombre corto para el resto del archivo. No carga ningún archivo ni ejecuta código, y funciona igual exista ya la clase o no. También se permiten las importaciones agrupadas: use Shop\{Order, Invoice};.

use function y use const

Las funciones y las constantes de un namespace se importan con use function y 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";
}

Las clases globales necesitan una barra invertida

Dentro de un namespace, un nombre de clase sin cualificar se resuelve en relación con ese namespace, así que new DateTime() dentro de namespace App; busca App\DateTime. Las funciones y las constantes son distintas: si App\strlen no existe, PHP recurre al strlen global. Las clases nunca recurren al global.

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

El catch (\Error $e) necesitaba una barra invertida por el mismo motivo: sin ella PHP buscaría App\Error, nunca coincidiría con el error real y el script se detendría con un Error no capturado. Corrígelo con una barra invertida inicial, como arriba, o con use DateTime; al principio del archivo. Lo mismo se aplica a \Exception, \Throwable y cualquier otra clase nativa; consulta try catch para capturarlas.

Autoloading y PSR-4

En un proyecto, cada clase vive en su propio archivo, y la ruta del archivo sigue al namespace. PSR-4 es la convención: un prefijo de namespace se asigna a una carpeta base, y el resto del nombre se convierte en la ruta. Un autoloader registrado con spl_autoload_register() carga entonces el archivo de una clase la primera vez que se usa la clase. Este bloque escribe dos archivos de clase en disco y los carga con autoload:

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

Cada archivo de clase se carga una vez, en el momento en que la clase se necesita por primera vez. En los proyectos reales no escribes tú esta función: Composer la genera a partir de unas pocas líneas en composer.json:

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

Después de composer dump-autoload, un único require __DIR__ . '/vendor/autoload.php'; al principio de tu script de entrada carga bajo demanda todas las clases App\....

Reglas de los namespaces que provocan errores

• namespace debe ser la primera sentencia del archivo. Solo pueden ir antes declare(strict_types=1); y los comentarios.
• Las importaciones con use son por archivo. Importar una clase en index.php no hace que el nombre corto funcione dentro de un archivo incluido; cada archivo necesita sus propias líneas use.
• use va en el nivel superior del archivo o del bloque de namespace. Dentro del cuerpo de una clase, use significa otra cosa: incorpora un trait.
• Las cadenas nunca se resuelven: $class = 'User'; new $class(); busca el User global. Guarda el nombre completo, idealmente con User::class.

La última merece una comprobación rápida:

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