jump to navigation

PHP Namespaces what are they and how to use them October 10, 2010

Posted by Tournas Dimitrios in PHP.
trackback

A earlier post mentioned briefly the “__NAMESPACE__” constant .So let’s get deeper in this subject.

As the size of your PHP code library increases, there is increased risk of accidentally re-defining a function or class name that has been declared before. The problem is exacerbated when you attempt to add third-party components or plugins; what if two or more code sets implement a ‘Database’ or ‘User’ 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 results 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 the global space — like they were before PHP supported namespaces.

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, HTML, or white-space can precede the command, e.g.

< ? p h p
// define this code in the 'MyProject' namespace
namespace MyProject;
// ... code ...

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

< ? p h p
namespace MyProject_xx;
// PHP code for the MyProject_xx namespace
namespace MyProject_yy;
// PHP code for the MyProject_yy namespace
// Alternative syntax
namespace MyProject_zz {
	// PHP code for the MyProject_zz namespace
}
?>

Although this is possible, I would advise against it: retain your sanity by defining a single namespace per file.

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

  • MyProject\SubName
  • MyProject\Database\MySQL
  • CompanyName\MyProject\Library\Common\Widget1

Calling Namespaced Code

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

lib1.php

< ? p h p
// application library 1
namespace App\Lib1;
const MYCONST = 'App\Lib1\MYCONST';
function MyFunction() {
	return __FUNCTION__;
}
class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

We can now include this code in another PHP file, e.g.
myapp.php

< ? p h p
 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 in 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. To call code in lib1.php, we can add a prefix of \App\Lib1 to define fully-qualified names. The following result is output when we load myapp.php:

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

Fully-qualified names can become quite long and there are few obvious benefits over defining long class names such as App-Lib1-MyClass. Therefore,  we will discuss aliasing and take a closer look at how PHP resolves namespace names.

For the purposes of this example, we will define two almost identical code blocks; the only difference is their namespace:

lib1.php:

< ? p h p
// application library 1
namespace App\Lib1;
const MYCONST = 'App\Lib1\MYCONST';
function MyFunction() {
	return __FUNCTION__;
}
class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

lib2.php:

< ? p h p
// application library 2
namespace App\Lib2;
const MYCONST = 'App\Lib2\MYCONST';
function MyFunction() {
	return __FUNCTION__;
}
class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

There is a little PHP terminology to understand before we begin…

Fully-qualified name
Any PHP code can refer to a fully-qualified name — an identifier starting with the namespace backslash separator, e.g. \App\Lib1\MYCONST, \App\Lib2\MyFunction(), etc.

Fully-qualified names have no ambiguity. The initial backslash operates in a similar way to a file path; it signifies the ‘root’ global space. If we implemented a different MyFunction() in our global space, it could be called from lib1.php or lib2.php using “\MyFunction()”.

Fully-qualified names are useful for one-off function calls or object initialization. However, they can become impractical when you are making lots of calls. As we will discover below, PHP offers other options to save us from namespace typing cramps.

Qualified name
An identifier with at least one namespace separator, e.g. Lib1\MyFunction().

Unqualified name
An identifier without a namespace separator, e.g. MyFunction().

Working Within the Same Namespace

Consider the following code:

myapp1.php:

< ? p h p
namespace App\Lib1;
require_once('lib1.php');
require_once('lib2.php');
header('Content-type: text/plain');
echo MYCONST . "\n";
echo MyFunction() . "\n";
echo MyClass::WhoAmI() . "\n";
?>

Although we include both lib1.php and lib2.php, the identifiers MYCONST, MyFunction, and MyClass will only reference code in lib1.php. This occurs because the myapp1.php code is within the same App\Lib1 namespace:

result:

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

Namespace Importing

Namespaces can be imported with the ” use ” operator, e.g.

myapp2.php:

< ? p h p
use App\Lib2;
require_once('lib1.php');
require_once('lib2.php');
header('Content-type: text/plain');
echo Lib2\MYCONST . "\n";
echo Lib2\MyFunction() . "\n";
echo Lib2\MyClass::WhoAmI() . "\n";
?>

Any number of use statements can be defined or you can separate individual namespaces with a comma. In this example we have imported the App\Lib2 namespace. We still cannot refer directly to MYCONST, MyFunction or MyClass because our code is in the global space and PHP will look for them there. However, if we add a prefix of ‘Lib2\’, they become qualified names; PHP will search through the imported namespaces until it finds a match.

result:

App\Lib2\MYCONST
App\Lib2\MyFunction
App\Lib2\MyClass::WhoAmI

Namespace Aliases

Namespace aliases are perhaps the most useful construct. Aliases allow us to reference long namespaces using a shorter name.

myapp3.php:

< ? p h p
use App\Lib1 as L;
use App\Lib2\MyClass as Obj;
header('Content-type: text/plain');
require_once('lib1.php');
require_once('lib2.php');
echo L\MYCONST . "\n";
echo L\MyFunction() . "\n";
echo L\MyClass::WhoAmI() . "\n";
echo Obj::WhoAmI() . "\n";
?>

The first use statement defines App\Lib1 as ‘L’. Any qualified names using ‘L’ will be translated to ‘App\Lib1′ at compile-time. We can therefore refer to L\MYCONST and L\MyFunction rather than the fully-qualified name.

The second use statement is more interesting. It defines ‘Obj’ as an alias for the class ‘MyClass’ within the App\Lib2\ namespace. This is only possible for classes — not constants or functions. We can now use new Obj() or run static methods as shown above.

result:

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

PHP Name Resolution Rules

PHP identifier names are resolved using the following namespace rules. Refer to the PHP manual for more information.

1. Calls to fully-qualified functions, classes or constants are resolved at compile-time.

2. Unqualified and qualified names are translated according to the import rules, e.g. if the namespace A\B\C is imported as C, a call to ” C\D\e() ” is translated to “A\B\C\D\e()”.

3. Inside a namespace, all qualified names not already translated according to import rules have the current namespace prepended, e.g. if a call to “C\D\e()” is performed within namespace A\B, it is translated to “A\B\C\D\e()”.

4. Unqualified class names are translated according to current import rules and the full name is substituted for short imported name, e.g. if class C in namespace A\B is imported as X, “new X()” is translated to “new A\B\C()”.

5. Unqualified function calls within a namespace are resolved at run-time. For example, if MyFunction() is called within namespace A\B, PHP first looks for the function \A\B\MyFunction(). If that is not found, it looks for \MyFunction() in the global space.

6. Calls to unqualified or qualified class names are resolved at run-time. For example, if we call “new C()” within namespace A\B, PHP will look for the class A\B\C. If that is not found, it will attempt to autoload A\B\C.

Advertisements

Comments»

No comments yet — be the first.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s