How to Use PHP Namespaces, Part 1: The Basics

    Craig Buckler

    PHP 5.3 namespacesNamespaces 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.

    // 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.

    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.

    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:


    // 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:


    header('Content-type: text/plain');
    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:


    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: