How to Use PHP Namespaces, Part 1: The Basics

Namespaces are one of the most significant changes in PHP 5.3. They will be familiar to C# and Java developers, and they are likely to change the structure of PHP applications for the better.

Why Do We Need Namespaces?

As the size of your PHP code library increases, the more likely you will accidentally reuse a function or class name that has been declared before. The problem is exacerbated if you attempt to add third-party components or plugins; what if two or more code sets implement a ‘Database’ class?

Until now, the only solution has been long class/function names. For example, WordPress prefixes every name with ‘WP_’. The Zend Framework uses a highly descriptive naming convention that resullts in long-winded class names such as Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive.

Name collision problems can be solved with namespaces. PHP constants, classes, and functions can be grouped into namespaced libraries.

How are Namespaces Defined?

By default, all constant, class and function names are placed in a global space — like they were before namespaces were supported.

Namespaced code is defined using a single namespace keyword at the top of your PHP file. It must be the first command (with the exception of declare) and no non-PHP code or white-space can precede the command, e.g.

<?php
// define this code in the MyProject namespace
namespace MyProject;

The code following this line will belong to the MyProject namespace. It is not possible to nest namespaces or define two or more namespaces for the same code block (only the last will be recognized). However, you can define different namespaced code in the same file, e.g.

<?php
namespace MyProject1;
// PHP code for the MyProject1 namespace

namespace MyProject2;
// PHP code for the MyProject2 namespace

// Alternative syntax
namespace MyProject3 {
	// PHP code for the MyProject3 namespace
}
?>

However, I would strongly advise defining a single namespace per file.

Sub-namespaces
PHP allows you to define a hierarchy of namespace names so libraries can be sub-divided. Sub-namespaces are separated using a backslash (\) character, e.g.

• MyProject\SubName
• MyProject\Database\MySQL
• CompanyName\MyProject\Common\Widget

Calling Namespaced Code

In a file named lib1.php, we will define a constant, function, and class with the App\Lib1 namespace:

lib1.php

<?php
// application library 1
namespace App\Lib1;

const MYCONST = 'App\Lib1\MYCONST';

function MyFunction() {
	return __FUNCTION__;
}

class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

To call this code, we can use PHP code such as:

myapp.php

<?php
header('Content-type: text/plain');
require_once('lib1.php');

echo \App\Lib1\MYCONST . "\n";
echo \App\Lib1\MyFunction() . "\n";
echo \App\Lib1\MyClass::WhoAmI() . "\n";
?>

No namespace is defined for myapp.php so the code exists in the global space. Any direct reference to MYCONST, MyFunction() or MyClass will fail because they exist in the App\Lib1 namespace. We must therefore add a prefix of \App\Lib1 to create a fully-qualified name. The following result is output when we load myapp.php:

App\Lib1\MYCONST
App\Lib1\MyFunction
App\Lib1\MyClass::WhoAmI

Fully-qualified names can obviously become quite long and there are few benefits over defining a class name of App-Lib1-MyClass. However, in the next article, we will discuss aliasing and take a closer look at how PHP resolves namespace names.

See also:

• How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
• How to Use PHP Namespaces, Part 3: Keywords and Autoloading
• How to Install PHP 5.3 on Windows

Frequently Asked Questions (FAQs) about PHP 5.3 Namespaces Basics