EnglishEnglish العربيةالعربية PortuguêsPortuguês Japanese日本語

Espaços de nomes e carregamento automático

Para projetos pequenos, três classes são suficientes. Mas um aplicativo de verdade pode ter 300 classes, além de bibliotecas de terceiros — os namespaces e o Composer são o “sistema de organização” do PHP que evita conflitos de nomes no seu código.

1. Por que precisamos de namespaces?

PHP 
<?php
// Imagine you wrote a Logger class
class Logger {
    public function log(string $msg): void {
        echo "My log: {$msg}<br>";
    }
}

// You want to use a third-party package that also has a Logger class
// Result: PHP Fatal Error: Cannot redeclare class Logger
?>

Os namespaces resolvem esse problema — pense neles como se fossem um “sobrenome” para cada classe:

TEXT 
Without namespace: Logger ← collision!
With namespace:    MyApp\Logger  vs  Vendor\Logger ← no collision!

2. Declarando um namespace

PHP 
<?php
// file: app/Utils/Logger.php
namespace App\Utils;

class Logger {
    public function log(string $msg): void {
        echo "[LOG] {$msg}<br>";
    }
}

// Use the fully qualified name
$log = new \App\Utils\Logger();
$log->log("App started");
?>

Regras de namespace:

3. uso — Importação de classes

PHP 
<?php
namespace App\Controllers;

// After use import, you can use the short class name
use App\Utils\Logger;
use PDO;
use DateTime;

class UserController {
    public function index(): void {
        $log = new Logger();  // No need for the fully qualified name
        $log->log("Viewing user list");
        
        $now = new DateTime();  // PHP built-in classes can also be imported
    }
}
?>

(1) usar ... como — Aliases

PHP 
<?php
// Resolve name conflicts
use App\Models\User as AppUser;
use Vendor\Cms\User as CmsUser;

$u1 = new AppUser();
$u2 = new CmsUser();
?>

4. Composer — Gerenciador de pacotes do PHP

O Composer é para o PHP o que o npm é para o Node.js e o pip é para o Python.

(1) Instalando o Composer

Acesse https://getcomposer.org para fazer o download e a instalação. Em seguida, no diretório do seu projeto:

BASH 
# Initialize the project
cd myphp
composer init

# Install a package (using the popular .env config library as an example)
composer require vlucas/phpdotenv

▶ Exemplo: Configuração do composer.json e carregamento automático

JSON 
{
    "name": "myphp/demo",
    "description": "PHP Learning Project",
    "require": {
        "php": ">=8.0",
        "vlucas/phpdotenv": "^5.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    }
}
▶ Experimente

(2) Como usar o carregamento automático

PHP 
<?php
// You only need to require this one file
require __DIR__ . '/vendor/autoload.php';

// Now you can use all Composer-managed packages and your custom classes
use App\Models\User;

$user = new User();
?>

5. Carregamento automático segundo o PSR-4

O PSR-4 é o padrão de autocarregamento da comunidade PHP — o prefixo do namespace corresponde ao diretório:

Espaço de nomes Diretório Caminho do arquivo de classe
App\ app/ app/ é a raiz
App\Models\User — app/Models/User.php
App\Controllers\Admin\Dashboard — app/Controllers/Admin/Dashboard.php

▶ Exemplo: Estrutura do projeto PSR-4

TEXT 
myphp/
├── app/
│   ├── Models/
│   │   └── User.php          ← namespace App\Models;
│   └── Controllers/
│       └── UserController.php ← namespace App\Controllers;
├── vendor/                   ← Created automatically by Composer
│   └── autoload.php
├── composer.json
└── public/
    └── index.php
▶ Experimente
PHP 
<?php
// app/Models/User.php
namespace App\Models;

class User {
    public function __construct(
        public string $name,
        public string $email
    ) {}
}
PHP 
<?php
// public/index.php
require __DIR__ . '/../vendor/autoload.php';

use App\Models\User;

$user = new User("John", "john@example.com");
echo $user->name;  // John
?>

6. Comandos comuns do Composer

BASH 
# Install all dependencies listed in composer.json
composer install

# Add a new dependency
composer require guzzlehttp/guzzle
composer require --dev phpunit/phpunit  # Dev environment only

# Update all dependencies
composer update

# Update a specific package
composer update guzzlehttp/guzzle

# Generate optimized autoloader (production)
composer dump-autoload -o

7. Classes embutidas x Espaços de nomes

PHP 
<?php
namespace App;

// Inside a namespace, call PHP built-in classes
$date = new \DateTime();          // Root namespace \
$pdo  = new \PDO($dsn, $user, $pass);

// Or use
use DateTime, PDO;

$date = new DateTime();
$pdo  = new PDO($dsn, $user, $pass);
?>
💡 Dica: Dentro de um namespace, as classes embutidas do PHP devem ser precedidas pelo prefixo \ ou importadas com use. Sem isso, o PHP procura no namespace atual (por exemplo, App\DateTime), que não existe.

❓ Perguntas Frequentes

P: Os namespaces precisam corresponder aos caminhos dos arquivos? R: O PSR-4 exige consistência, mas a sintaxe do PHP não a impõe. Você pode nomear os elementos arbitrariamente ao incluir arquivos manualmente. No entanto, seguir o padrão é o que faz com que o carregamento automático do Composer funcione.

P: Onde os pacotes do Composer são instalados? R: No diretório vendor/. Esse diretório geralmente não é incluído no Git (configurado no .gitignore). Os membros da equipe executam o composer install por conta própria.

P: O que significa ^5.0 em composer.json? R: É uma restrição de versionamento semântico (SemVer). ^5.0 significa aceitar versões >=5.0 e <6.0. ~5.0 significa >=5.0 e <5.1.

📖 Resumo

📝 Exercícios

  1. Crie uma estrutura de projeto simples: app/Models/User.php e app/Utils/Validator.php, cada uma com suas próprias declarações de namespace. Importe-as e utilize-as em public/index.php junto com use.
  2. Instale o Composer, use composer init para inicializar um projeto e configure o carregamento automático PSR-4 no arquivo composer.json.
  3. Instale um pacote de terceiros (como o ramsey/uuid para gerar UUIDs) e entenda a função do diretório “vendor” e do arquivo “autoload.php”.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%