As your PHP applications grow, you will start using more classes and file - either written by you or pulled in from third-party packages.

This introduces two major problems:

• Name Collisions - You cannot declare two classes with the exact same name in your application, or PHP will crash. If you write a User class and an external package also has a User class, they will conflict.
• Readability - It becomes harder to tell where a specific class belongs or what its context is.

In PHP, Namespaces solve this. They act like virtual folders for your code, allowing you to isolate and organize your classes so that identical names can coexist peacefully.

Defining a Namespace

To put a class inside a namespace, use the namespace keyword at the very top of your file.

This must be the absolute first line of code in the file, appearing right after the opening <?php tag.

<?php
namespace App\Modules;

class User
{
    public string $name;
}

By declaring namespace App\Modules;, the full, official name of this class is now App\Modules\User. This is known as its Fully Qualified Class Name (FQCN).

Because of this virtual folder path, this class will never conflict with a User class inside a different namespace (like Vendor\Billing\User).

Using Namespaced Code

When you want to instantiate or use a class that lives inside a namespace, PHP needs to know exactly where to find it. You can achieve this in two ways.

You can type out the complete virtual path inline every time you refer to the class:

<?php
require_once __DIR__ . "/Modules/User.php";

// Instantiating using the absolute, full namespace path
$user = new \App\Modules\User();

(Note: Starting the path with a leading backslash \ tells PHP to look from the absolute root namespace).

Importing with the use Keyword (Recommended) Typing long namespace paths over and over can quickly clutter your code.

Instead, you can import the class at the top of your current file using the use keyword. This acts like a shortcut, allowing you to refer to the class by its short name throughout the rest of the file.

<?php
namespace App;

// 1. Import the external class at the top of the file
use App\Modules\User;

require_once __DIR__ . "/Modules/User.php";

// 2. Now you can use the short name safely!
$user = new User();

Resolving Name Conflicts with Aliases (as)

If you import two different classes that share the exact same short name into the same file, you will trigger a name collision error.

You can fix this by using the as keyword to give one (or both) of the classes a unique nickname, known as an alias.

<?php
// Import both classes, but rename the second one to avoid a clash
use App\Modules\User;
use ThirdParty\API\User as ApiUser;

$localUser = new User();    // Refers to App\Modules\User
$externalUser = new ApiUser(); // Refers to ThirdParty\API\User

Summary Checklist

Top of the File Only: The namespace declaration must be at the very top of the file, directly underneath <?php. No other code can come before it.

Virtual, Not Physical: Namespaces don't strictly have to match your computer's actual folder structure to function, but matching them is a universal best practice (and required by modern automatic file loaders).

The Global Namespace: Built-in PHP classes (like Exception or DateTime) live in the root global namespace. If you are inside a custom namespace and want to use a built-in PHP class, prefix it with a backslash (e.g., new \DateTime()) so PHP knows to look in the root instead of inside your custom virtual folder.