PHP Namespaces — Complete Guide to Organizing PHP Code

In this tutorial, you will learn about PHP Namespaces. We cover key concepts, practical examples, and best practices to help you master this topic.

PHP namespaces organize code into logical groups, preventing name collisions between classes, functions, and constants from different libraries or application modules.

What You'll Learn

By the end of this tutorial, you'll declare and use namespaces, import classes with use statements, alias long namespaces, understand namespace resolution, and comply with PSR-4 autoloading.

Why Namespaces Matter

Without namespaces, two libraries cannot have classes with the same name (e.g., User from two different packages). Namespaces qualify class names with a vendor/package prefix, eliminating collisions.

Real-World Use

An application uses App\Models\User for data models, App\Controllers\User for controllers, and a third-party logger with its own namespace. Each User class coexists without conflict.

Namespaces Learning Path

flowchart LR
  A[Traits] --> B[Namespaces]
  B --> C[Composer]
  C --> D[DI]
  D --> E[MVC]
  A --> F{You Are Here}
  style F fill:#f90,color:#fff

Declaring Namespaces

<?php
// src/Models/User.php
namespace App\Models;
class User {
    public function __construct(public string $name) {}
}

// src/Controllers/UserController.php
namespace App\Controllers;
use App\Models\User;
class UserController {
    public function show(int $id): User {
        return new User("Alice");
    }
}

The use Statement

<?php
namespace App\Services;
// Import classes from other namespaces
use App\Models\User;
use App\Repositories\UserRepository;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
class UserService {
    public function __construct(
        private UserRepository $repo,
        private Logger $logger
    ) {}
}

Aliasing

<?php
namespace App\Controllers;
use App\Models\User as UserModel;
use App\Services\NotificationService;
// When you need to use two classes with the same name
class UserController {
    public function show(int $id): UserModel {
        return new UserModel("Alice");
    }
}

Sub-Namespaces

<?php
namespace App\Http\Middleware;
namespace App\Http\Requests;
namespace App\Exceptions\Validation;

// Directory structure mirrors namespace structure:
// src/
//   Http/
//     Middleware/
//     Requests/
//   Exceptions/
//     Validation/

Global Namespace

<?php
namespace App\Utils;
// Access global classes with leading backslash
$date = new \DateTime();
$exception = new \RuntimeException("Error");
echo \PHP_VERSION;

Common Mistakes

1. Duplicate use Statements

Importing the same class twice is unnecessary but harmless. PHP ignores duplicate use statements.

2. Mixing \ in Strings

Namespace separators are only for code, not strings. "App\Models\User" is a string, not a namespace.

3. Forgetting Leading \ for Global Classes

Without leading , PHP looks in the current namespace. Use \Exception or import with use.

4. Incorrect File Structure

PSR-4 requires file paths to match namespace structure. App\Models\User must be in src/Models/User.php.

5. Using Namespaces Without Autoloading

Namespace declarations without autoloading require manual require statements. Always use Composer autoloading.

Practice Questions

1. What problem do namespaces solve?

They prevent name collisions between classes, functions, and constants from different packages.

2. How do you import a class from another namespace?

Use the use statement: use App\Models\User; Then reference it as User without the full namespace.

3. What is a namespace alias?

A shorthand for long namespaces: use App\Very\Long\Namespace\ClassName as ShortName;

4. How do namespaces relate to file structure?

PSR-4 maps namespace segments to directory paths. App\Models\User is in src/Models/User.php.

5. Challenge: Create a namespace structure for an MVC application.

<?php
// src/Controllers/ProductController.php
namespace App\Controllers;
use App\Models\Product;
use App\Http\Response;
class ProductController {
    public function index(): Response {
        $products = Product::all();
        return new Response(200, json_encode($products));
    }
}

FAQ

Mini Project: PSR-4 Project Structure

Create a PHP project following PSR-4 namespace conventions.

<?php
// composer.json
{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}
// src/Models/Post.php
namespace App\Models;
class Post {
    public function __construct(
        public int $id,
        public string $title,
        public string $content
    ) {}
}
// src/Repositories/PostRepository.php
namespace App\Repositories;
use App\Models\Post;
class PostRepository {
    public function find(int $id): ?Post {
        return new Post($id, "Hello", "World");
    }
}

What's Next

PHP Composer Autoload PHP Dependency Injection PHP MVC Pattern