Understanding PHP Namespaces (with PHPMaker Examples)

PHPMaker User Submitted Tips (PHPMaker)
1

Part 1 - PHP Namespace Basics

By default, PHPMaker uses your project name as the main namespace, for example:

PHPMaker2026\MyProject

Namespaces in PHP work like folders for your functions, classes, and constants.
They prevent name conflicts and keep code organized.

1. Defining a Namespace and Function

For example, if you add a function under Global Code:

<?php
namespace PHPMaker2026\MyProject;

function SayHello(string $name): void {
    echo "Hello, $name!";
}

The full name of this function is:

PHPMaker2026\MyProject\SayHello

2. Calling a Namespaced Function

Option 1 - Use the full function name:

\PHPMaker2026\MyProject\SayHello("World");

Option 2 - Add a use function statement:

use function PHPMaker2026\MyProject\SayHello;

SayHello("World");

3. Calling Built-in Functions

In most cases, you can call built-in PHP functions (such as date(), strlen(), array_merge()) directly inside a namespace — PHP will automatically find the global version.

namespace PHPMaker2026\MyProject;

function ShowDate(): void {
    echo date('Y-m-d'); // no backslash needed in normal cases
}

You only need to add a leading backslash if a local function with the
same name exists and you want to call the global one:

namespace PHPMaker2026\MyProject;

function strlen($s) { return 999; }

echo strlen("abc");   // calls local version
echo \strlen("abc");  // calls global PHP function

4. PHPMaker PSR-4 Autoloading

PHPMaker maps its namespace to multiple base folders:

"autoload": {
    "psr-4": {
        "PHPMaker2026\\MyProject\\": [
            "src/",
            "models/",
            "controllers/"
        ]
    }
}

That means PHP will find files under any of these directories:

Namespace → File Path

PHPMaker2026\MyProject\Helper → src/Helper.php
PHPMaker2026\MyProject\UserTable → models/UserTable.php
PHPMaker2026\MyProject\HomeController → controllers/HomeController.php

Most generated files share the same namespace, so you can call project functions and classes directly — they behave almost like global ones.
However, understanding namespaces is still important when using external libraries or sub-namespaces.

2

Part 2 - Namespaces in Symfony

Symfony uses namespaces extensively to organize its components.
PHPMaker follows the same PSR-4 standard, but keeps most of its code under one shared namespace and uses sub-namespaces for specific parts (for example, Doctrine entities under PHPMaker2026\MyProject\Db\Entity).

Example: Controller

<?php
namespace PHPMaker2026\MyProject;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class HomeController
{
    #[Route('/home')]
    public function index(): Response
    {
        return new Response('Hello Symfony!');
    }
}

Explanation

  • namespace PHPMaker2026\MyProject;
    → Shared by most of your project files (src/, models/,
    controllers/).

  • use Symfony\Component\HttpFoundation\Response;
    → Imports Symfony’s Response class.

  • use Symfony\Component\Routing\Attribute\Route;
    → Imports the Route attribute.

Without the use lines, you need to write:

return new \Symfony\Component\HttpFoundation\Response('Hello Symfony!');

PHPMaker’s Namespace Layout

Since PHPMaker keeps most of its code under one shared namespace, you can directly call pseudo-global functions inside the same main namespace:

SayHello("Symfony");

But when working across namespaces (for example, accessing an entity or a Symfony class), you must use use statements or fully qualified names.
Understanding namespaces is crucial to avoid name collisions and integration issues.

3

Part 3 - Common Mistakes and Best Practices

1. Missing use

$r = new Response(); // Error: Class "PHPMaker2026\MyProject\Response" not found

Fix:

use Symfony\Component\HttpFoundation\Response;

2. Missing Leading Backslash

When you use a class inside a namespace, PHP first looks for it in the same namespace.
If the class actually lives in the global namespace, you must add a backslash:

namespace PHPMaker2026\MyProject;

$a = new DateTime();     // Error: looks for PHPMaker2026\MyProject\DateTime
$a = new \DateTime();    // Correct: global class

Alternatively, import it once:

use DateTime;

$a = new DateTime(); // also correct

Use a backslash or a use statement whenever a class is outside your current namespace.

3. Name Conflicts

Alias duplicate class names:

use PHPMaker2026\MyProject\Helper;
use Vendor\Package\Helper as VendorHelper;

$local = new Helper();
$external = new VendorHelper();

4. Wrong PSR-4 Mapping

If Composer cannot find a class, it usually means the namespace and file path do not match your autoload setting.

Check the following:

  1. The class namespace matches its location

    • Example: namespace PHPMaker2026\MyProject; should be in src/, models/, or controllers/
    • Example: namespace PHPMaker2026\MyProject\Db\Entity; should be in the src/Db/Entity/ subfolder

  2. The filename matches the class name (case-sensitive).

    • Class HomeController → file HomeController.php

  3. Rebuild Composer’s autoloader after making changes:

composer dump-autoload

5. Case Sensitivity

On Linux and macOS, both file names and folder names are case-sensitive.
Make sure they exactly match your namespace and class definitions.

For example:

namespace PHPMaker2026\MyProject;
class HomeController {}

Must be saved as:

controllers/HomeController.php

and not Controllers/homecontroller.php or any other variation.