PHP: Name resolution rules

FAQ: things you need to know about namespaces

Using namespaces: fallback to global function/constant

Last updated: Fri, 09 Jan 2009

Name resolution rules

For the purposes of these resolution rules, here are some important definitions:

Unqualified name: This is an identifier without a namespace separator, such as Foo
Qualified name: This is an identifier with a namespace separator, such as Foo\Bar
Fully qualified name: This is an identifier with a namespace separator that begins with a namespace separator, such as \Foo\Bar. namespace\Foo is also a fully qualified name.

Names are resolved following these resolution rules:

Calls to fully qualified functions, classes or constants are resolved at compile-time. For instance new \A\B resolves to class A\B.
All unqualified and qualified names (not fully qualified names) are translated during compilation according to current import rules. For example, if the namespace A\B\C is imported as C, a call to C\D\e() is translated to A\B\C\D\e().
Inside a namespace, all qualified names not translated according to import rules have the current namespace prepended. For example, if a call to C\D\e() is performed within namespace A\B, it is translated to A\B\C\D\e().
Unqualified class names are translated during compilation according to current import rules (full name substituted for short imported name). In example, if the namespace A\B\C is imported as C, new C() is translated to new A\B\C().
Inside namespace (say A\B), calls to unqualified functions are resolved at run-time. Here is how a call to function foo() is resolved:
1. It looks for a function from the current namespace: A\B\foo().
2. It tries to find and call the global function foo().
Inside namespace (say A\B), calls to unqualified or qualified class names (not fully qualified class names) are resolved at run-time. Here is how a call to new C() or new D\E() is resolved. For new C():
1. It looks for a class from the current namespace: A\B\C.
2. It attemts to autoload A\B\C.
For new D\E():
1. It looks for a class by prepending the current namespace: A\B\D\E.
2. It attemts to autoload A\B\D\E.
To reference any global class in the global namespace, its fully qualified name new \C() must be used.

Example #1 Name resolutions illustrated


<?php
namespace A;
use B\D, C\E as F;

// function calls

foo();      // first tries to call "foo" defined in namespace "A"
            // then calls global function "foo"

\foo();     // calls function "foo" defined in global scope

my\foo();   // calls function "foo" defined in namespace "A\my"

F();        // first tries to call "F" defined in namespace "A"
            // then calls global function "F"

// class references

new B();    // creates object of class "B" defined in namespace "A"
            // if not found, it tries to autoload class "A\B"

new D();    // using import rules, creates object of class "D" defined in namespace "B"
            // if not found, it tries to autoload class "B\D"

new F();    // using import rules, creates object of class "E" defined in namespace "C"
            // if not found, it tries to autoload class "C\E"

new \B();   // creates object of class "B" defined in global scope
            // if not found, it tries to autoload class "B"

new \D();   // creates object of class "D" defined in global scope
            // if not found, it tries to autoload class "D"

new \F();   // creates object of class "F" defined in global scope
            // if not found, it tries to autoload class "F"

// static methods/namespace functions from another namespace

B\foo();    // calls function "foo" from namespace "A\B"

B::foo();   // calls method "foo" of class "B" defined in namespace "A"
            // if class "A\B" not found, it tries to autoload class "A\B"

D::foo();   // using import rules, calls method "foo" of class "D" defined in namespace "B"
            // if class "B\D" not found, it tries to autoload class "B\D"

\B\foo();   // calls function "foo" from namespace "B"

\B::foo();  // calls method "foo" of class "B" from global scope
            // if class "B" not found, it tries to autoload class "B"

// static methods/namespace functions of current namespace

A\B::foo();   // calls method "foo" of class "B" from namespace "A\A"
              // if class "A\A\B" not found, it tries to autoload class "A\A\B"

\A\B::foo();  // calls method "foo" of class "B" from namespace "A\B"
              // if class "A\B" not found, it tries to autoload class "A\B"
?>

add a note User Contributed Notes
Name resolution rules

sean dot mccleary at gmail dot com
08-Oct-2008 06:28


Watch out if you're using class auto-loading.



If you are working in namespace "A", and want to auto-load the class "Person" which is defined in the global namespace, it won't work because the __autoload function will be passed "A::Person" as a parameter.



You must specify you want to use the class ::Person.

Will
20-Feb-2008 10:08


Agreed.  Dennis is right on with this.  To add on, requiring each file that includes a namespace also defeats the purpose of namespacing.  It makes more sense if you have a repository for namespaces and just use those.



Example:



/some/path/to/namespaces/



<?php



use Some::Namespace;



// Test is withing Namespace.

$t = new Test();

// Test2 is not, so it checks includes, etc.

$t = new Test2();



?>

add a note

FAQ: things you need to know about namespaces

Using namespaces: fallback to global function/constant

Last updated: Fri, 09 Jan 2009