Skip to main content

Namespaces

Chapter Overview​

In this chapter you will learn:

  • What namespaces are
  • Why namespaces exist
  • Namespace syntax
  • Importing classes
  • Aliases
  • Global namespace
  • PSR-4 standards
  • Composer autoloading
  • PocketMine plugin structure
  • Enterprise architecture
  • Best practices

Introduction

Namespaces are one of the most important concepts in modern PHP.

Without namespaces:

Large PHP applications would become impossible to manage.

Frameworks like:

  • Laravel
  • Symfony
  • PocketMine-MP
  • Composer Packages

all heavily rely on namespaces.

What is a Namespace?

A namespace is:

A way to organize classes,
interfaces,
traits,
functions,
and constants.

Think of it like folders on your computer.

Real Life Example

Imagine your PC:

Documents/
Pictures/
Downloads/

Each folder keeps files organized.

Namespaces do the same for PHP code.

The Problem Without Namespaces

Imagine two developers.

Developer 1 creates:

class User {

}

Developer 2 also creates:

class User {

}

Now PHP sees:

User
User

Conflict.

Output:

Fatal Error:
Cannot declare class User.

Solution

Namespaces.

Developer 1:

namespace App\Models;

class User {

}

Developer 2:

namespace Zyro\Auth;

class User {

}

Now:

App\Models\User

Zyro\Auth\User

No conflicts.

Visualization

App
└── Models
      └── User

Zyro
└── Auth
      └── User

Basic Syntax

Example:

namespace App\Models;

class User {

}

This class now becomes:

App\Models\User

Accessing Classes

Fully Qualified Name​

$user =
new App\Models\User();

Importing​

Better:

use App\Models\User;

$user =
new User();

Much cleaner.

Visualization

use
 ↓
Import Class
 ↓
Use Short Name

Nested Namespaces

Namespaces may contain many levels.

Example:

namespace ZyroNetwork\School\Courses\PHP;

Structure:

ZyroNetwork
        ↓
School
        ↓
Courses
        ↓
PHP

Folder Mapping

Usually:

src/
└── School
      └── Courses
            └── PHP

Why Use Namespaces?

Benefits:

✅ No naming conflicts

✅ Better organization

✅ Composer support

✅ PSR-4 support

✅ Large applications become manageable

Global Namespace

Everything without namespace belongs to:

Global Namespace

Example:

class User {

}

This becomes:

\User

Accessing Global Classes

Example:

$date =
new \DateTime();

The \ means:

Start from global namespace.

Example

namespace App;

$date =
new \DateTime();

Without:

\

PHP tries:

App\DateTime

which does not exist.

Namespace Keyword

namespace App\Models;

Must usually appear at top of file.

Importing Classes

Example:

use App\Models\User;

Now:

$user =
new User();

Multiple Imports

use App\Models\User;
use App\Models\Post;
use App\Services\AuthService;

Group Imports

PHP allows:

use App\Models\{
    User,
    Post,
    Comment
};

Aliases

Sometimes class names conflict.

Example:

use PocketMine\Player;
use Zyro\Core\Player;

Conflict.

Solution:

use PocketMine\Player
    as PMPlayer;

use Zyro\Core\Player
    as ZyroPlayer;

Usage:

$player =
new PMPlayer();

Visualization

Original Name
       ↓
      Alias

Importing Functions

Namespaces can also import functions.

Example:

use function strlen;

Importing Constants

Example:

use const PHP_VERSION;

Namespace Resolution

PHP resolves classes like this:

Current Namespace​

namespace App;

Code:

new User();

PHP searches:

App\User

Global Namespace​

new \DateTime();

PHP searches:

\DateTime

Real Example

namespace Zyro;

new Config();

PHP tries:

Zyro\Config

Namespaces and Folder Structure

Modern PHP follows:

One namespace
=
One folder structure

Example

Class:

App\Services\AuthService

Usually stored in:

src/
└── Services
      └── AuthService.php

PSR-4 Standard

One of the most important PHP standards.

PSR-4 says:

Namespace
must match
Folder Structure.

Example

Namespace:

namespace Zyro\School\Courses;

File:

src/School/Courses/

Visualization

Namespace
      ↓
Folder
      ↓
File

Why PSR-4 Exists

Before PSR-4:

Huge projects became messy.

PSR-4 allows:

✅ Automatic loading

✅ Standardized structures

✅ Composer support

Composer Example

{
  "autoload": {

    "psr-4": {

      "Zyro\\": "src/"

    }

  }
}

Meaning:

Namespace: Zyro\
Folder: src/

Example

Class:

namespace Zyro\Services;

class AuthService {

}

File:

src/
└── Services
      └── AuthService.php

Composer Automatically Loads It

No need:

require_once

Old PHP Way

Before namespaces:

require_once "User.php";
require_once "Post.php";
require_once "Database.php";

Terrible.

Modern PHP:

use App\Models\User;

Done.

PocketMine Namespace Structure

PocketMine uses namespaces everywhere.

Example:

use pocketmine\player\Player;

Actual file:

src/
└── player
      └── Player.php

Another example:

use pocketmine\world\World;

File:

src/
└── world
      └── World.php

Plugin Example

Your plugin:

src/
└── zyro/
      └── Main.php

Main.php:

namespace zyro;

class Main {

}

Better Structure

src/
└── zyro/
      ├── Main.php
      ├── commands/
      ├── listeners/
      ├── managers/
      ├── forms/
      └── utils/

Namespaces:

namespace zyro\commands;
namespace zyro\listeners;
namespace zyro\utils;

ZyroNetwork Example

Structure:

src/
└── zyro/
      ├── api/
      ├── network/
      ├── ranks/
      ├── commands/
      ├── database/
      ├── utils/
      └── forms/

Namespaces:

zyro\api
zyro\network
zyro\ranks
zyro\database

Enterprise Example

Large applications:

src/
│
├── Controllers
├── Services
├── Repositories
├── Models
├── DTO
├── Events
├── Listeners
├── Exceptions
└── Contracts

Namespaces:

App\Controllers
App\Services
App\Repositories

Why?

Because projects may contain:

1000+
Classes

Without namespaces:

Impossible to manage.

Common Beginner Mistakes

Wrong Folder Structure​

Bad:

Namespace:
App\Services

File:
src/Test/Auth.php

PSR-4 breaks.

Wrong Capitalization​

Windows may work.

Linux may fail.

Always keep:

Namespace
=
Folder Structure

Using Global Namespace Everywhere​

Bad:

new \App\Models\User();

Use imports instead.

Best Practices

✅ Follow PSR-4.

✅ Use meaningful namespaces.

✅ Keep folder structures clean.

✅ Avoid extremely deep namespaces.

Good Example

App\Services\AuthService

Bad Example

App\Core\Services\Auth\Authentication\Services\AuthServiceManager

Too deep.

Namespace Architecture Example

App
│
├── Controllers
├── Services
├── Models
├── DTO
├── Contracts
├── Events
└── Exceptions

Exercises

Exercise 1​

Create:

App\Models\User

Exercise 2​

Create:

Zyro\Ranks\RankManager

Exercise 3​

Create:

Zyro\Network\PacketManager

Mini Project

Create structure:

src/
│
├── API
├── Commands
├── Forms
├── Listeners
├── Managers
├── Network
├── Utils
└── Database

Namespaces:

Zyro\API
Zyro\Commands
Zyro\Forms
Zyro\Managers

Interview Questions

What is a namespace?​

A way to organize classes and avoid naming conflicts.

Why are namespaces important?​

Because large projects may contain thousands of classes.

What does use do?​

Imports a class into current file.

What is PSR-4?​

A standard that maps namespaces to folders.

Why does Composer need namespaces?​

For automatic class loading.

Summary

Namespaces provide:

✅ Organization

✅ No Class Conflicts

✅ Composer Support

✅ PSR-4 Compatibility

✅ Enterprise Architecture

✅ Framework Development

Modern PHP development is impossible without namespaces.

References

https://www.php.net/manual/en/language.namespaces.php

https://www.php-fig.org/psr/psr-4/

Next Chapter

➡ Autoloading

➡ Dependency Injection

➡ SOLID Principles

➡ Design Patterns