Namespace em PHP: namespace, use e aliases

Um namespace PHP coloca classes, funções e constantes sob um prefixo para que os nomes delas não colidam com os de mais ninguém. Você o declara com namespace App\Models; como primeira instrução de um arquivo, e outros arquivos se referem à classe como \App\Models\User, ou a importam com use App\Models\User; e escrevem só 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 do namespace, User significa App\Models\User. User::class dá o nome completo como string sem criar nada, o que é prático para logs e autoloaders.

Dois namespaces num arquivo

Um projeto real coloca um namespace em cada arquivo. Para uma demonstração autocontida, um arquivo pode ter vários namespaces quando cada um fica entre chaves. Código que não pertence a nenhum namespace vai em 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";
}

Duas classes chamadas Order vivem lado a lado porque os nomes completos são diferentes. É exatamente o problema que os namespaces resolvem quando você instala bibliotecas: o seu Order, o Order de uma biblioteca de pagamentos e o Order de uma biblioteca de PDF não colidem mais.

Importar com use e criar alias com as

Escrever \Shop\Order em todo lugar polui o código. use no topo de um arquivo (ou de um bloco de namespace) importa um nome para você usar a forma curta. Quando dois imports terminariam no mesmo nome curto, as dá a um deles outro nome:

<?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 só cria um nome curto para o resto do arquivo. Ele não carrega um arquivo nem executa código, e funciona do mesmo jeito exista a classe ou não. Imports agrupados também são permitidos: use Shop\{Order, Invoice};.

use function e use const

Funções e constantes num namespace são importadas com use function e 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";
}

Classes globais precisam de barra invertida

Dentro de um namespace, um nome de classe sem qualificação é resolvido em relação àquele namespace, então new DateTime() dentro de namespace App; procura App\DateTime. Funções e constantes são diferentes: se App\strlen não existe, o PHP cai no strlen global. Classes nunca caem.

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

O catch (\Error $e) precisou de barra invertida pelo mesmo motivo: sem ela o PHP procuraria App\Error, nunca bateria com o erro real, e o script pararia com um Error não capturado. Corrija com uma barra invertida inicial, como acima, ou com use DateTime; no topo do arquivo. O mesmo vale para \Exception, \Throwable e todas as outras classes nativas; veja try catch para capturá-las.

Autoload e PSR-4

Num projeto, cada classe fica no próprio arquivo, e o caminho do arquivo segue o namespace. O PSR-4 é a convenção: um prefixo de namespace corresponde a uma pasta base, e o resto do nome vira o caminho. Um autoloader registrado com spl_autoload_register() então carrega o arquivo de uma classe na primeira vez que ela é usada. Este bloco escreve dois arquivos de classe no disco e os carrega com 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 arquivo de classe é carregado uma vez, no momento em que a classe é necessária pela primeira vez. Em projetos reais você não escreve essa função: o Composer a gera a partir de algumas linhas no composer.json:

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

Depois de composer dump-autoload, um único require __DIR__ . '/vendor/autoload.php'; no início do seu script de entrada carrega sob demanda todas as classes App\....

Regras de namespace que causam erros

• namespace precisa ser a primeira instrução do arquivo. Só declare(strict_types=1); e comentários podem vir antes.
• Imports com use valem por arquivo. Importar uma classe em index.php não faz o nome curto funcionar dentro de um arquivo incluído; cada arquivo precisa das próprias linhas use.
• use fica no nível superior do arquivo ou do bloco de namespace. Dentro do corpo de uma classe, use significa outra coisa: ele incorpora uma trait.
• Strings nunca são resolvidas: $class = 'User'; new $class(); procura o User global. Guarde o nome completo, de preferência com User::class.

A última merece uma verificação 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";
}