What are namespaces? In the broadest definition namespaces are a way of encapsulating items. This can be seen as an abstract concept in many places. For example, in any operating system directories serve to group related files, and act as a namespace for the files within them. As a concrete example, the file foo.txt can exist in both directory /home/greg and in /home/other, but two copies of foo.txt cannot co-exist in the same directory. In addition, to access the foo.txt file outside of the /home/greg directory, we must prepend the directory name to the file name using the directory separator to get /home/greg/foo.txt. This same principle extends to namespaces in the programming world. In the PHP world, namespaces are designed to solve two problems that authors of libraries and applications encounter when creating re-usable code elements such as classes or functions: Name collisions between code you create, and internal PHP classes/functions/constants or third-party classes/functions/constants. Ability to alias (or shorten) Extra_Long_Names designed to alleviate the first problem, improving readability of source code. PHP Namespaces provide a way in which to group related classes, interfaces, functions and constants. Here is an example of namespace syntax in PHP: ]]> Namespace names PHP and php, and compound names starting with these names (like PHP\Classes) are reserved for internal language use and should not be used in the userspace code. Although any valid PHP code can be contained within a namespace, only four types of code are affected by namespaces: classes, interfaces, functions and constants. Namespaces are declared using the namespace keyword. A file containing a namespace must declare the namespace at the top of the file before any other code - with one exception: the keyword. ]]> The only code construct allowed before a namespace declaration is the declare statement, for defining encoding of a source file. In addition, no non-PHP code may precede a namespace declaration, including extra whitespace: ]]> In addition, unlike any other PHP construct, the same namespace may be defined in multiple files, allowing splitting up of a namespace's contents across the filesystem. Much like directories and files, PHP namespaces also contain the ability to specify a hierarchy of namespace names. Thus, a namespace name can be defined with sub-levels: ]]> The above example creates constant MyProject\Sub\Level\CONNECT_OK, class MyProject\Sub\Level\Connection and function MyProject\Sub\Level\connect. Multiple namespaces may also be declared in the same file. There are two allowed syntaxes. ]]> This syntax is not recommended for combining namespaces into a single file. Instead it is recommended to use the alternate bracketed syntax. ]]> It is strongly discouraged as a coding practice to combine multiple namespaces into the same file. The primary use case is to combine multiple PHP scripts into the same file. To combine global non-namespaced code with namespaced code, only bracketed syntax is supported. Global code should be encased in a namespace statement with no namespace name as in: ]]> No PHP code may exist outside of the namespace brackets except for an opening declare statement. ]]> Before discussing the use of namespaces, it is important to understand how PHP knows which namespaced element your code is requesting. A simple analogy can be made between PHP namespaces and a filesystem. There are three ways to access a file in a file system: Relative file name like foo.txt. This resolves to currentdirectory/foo.txt where currentdirectory is the directory currently occupied. So if the current directory is /home/foo, the name resolves to /home/foo/foo.txt. Relative path name like subdirectory/foo.txt. This resolves to currentdirectory/subdirectory/foo.txt. Absolute path name like /main/foo.txt. This resolves to /main/foo.txt. The same principle can be applied to namespaced elements in PHP. For example, a class name can be referred to in three ways: Unqualified name, or an unprefixed class name like $a = new foo(); or foo::staticmethod();. If the current namespace is currentnamespace, this resolves to currentnamespace\foo. If the code is global, non-namespaced code, this resolves to foo. One caveat: unqualified names for functions and constants will resolve to global functions and constants if the namespaced function or constant is not defined. See Using namespaces: fallback to global function/constant for details. Qualified name, or a prefixed class name like $a = new subnamespace\foo(); or subnamespace\foo::staticmethod();. If the current namespace is currentnamespace, this resolves to currentnamespace\subnamespace\foo. If the code is global, non-namespaced code, this resolves to subnamespace\foo. Fully qualified name, or a prefixed name with global prefix operator like $a = new \currentnamespace\foo(); or \currentnamespace\foo::staticmethod();. This always resolves to the literal name specified in the code, currentnamespace\foo. Here is an example of the three kinds of syntax in actual code: file1.php ]]> file2.php ]]> Note that to access any global class, function or constant, a fully qualified name can be used, such as \strlen or \Exception or \INI_ALL. ]]> PHP's implementation of namespaces is influenced by its dynamic nature as a programming language. Thus, to convert code like the following example into namespaced code: example1.php: ]]> One must use the fully qualified name (class name with namespace prefix). Note that because there is no difference between a qualified and a fully qualified Name inside a dynamic class name, function name, or constant name, the leading backslash is not necessary. ]]> Be sure to read the note about escaping namespace names in strings. PHP supports two ways of abstractly accessing elements within the current namespace, the __NAMESPACE__ magic constant, and the namespace keyword. The value of __NAMESPACE__ is a string that contains the current namespace name. In global, un-namespaced code, it contains an empty string. ]]> ]]> The __NAMESPACE__ constant is useful for dynamically constructing names, for instance: ]]> The namespace keyword can be used to explicitly request an element from the current namespace or a sub-namespace. It is the namespace equivalent of the self operator for classes. ]]> ]]> The ability to refer to an external fully qualified name with an alias, or importing, is an important feature of namespaces. This is similar to the ability of unix-based filesystems to create symbolic links to a file or to a directory. PHP namespaces support three kinds of aliasing or importing: aliasing a class name, aliasing an interface name, and aliasing a namespace name. Note that importing a function or constant is not supported. In PHP, aliasing is accomplished with the use operator. Here is an example showing all 3 kinds of importing: ]]> Note that for namespaced names (fully qualified namespace names containing namespace separator, such as Foo\Bar as opposed to global names that do not, such as FooBar), the leading backslash is unnecessary and not recommended, as import names must be fully qualified, and are not processed relative to the current namespace. PHP additionally supports a convenience shortcut to place multiple use statements on the same line ]]> Importing is performed at compile-time, and so does not affect dynamic class, function or constant names. ]]> In addition, importing only affects unqualified and qualified names. Fully qualified names are absolute, and unaffected by imports. ]]> The use keyword must be declared in the outermost scope of a file (the global scope) or inside namespace declarations. This is because the importing is done at compile time and not runtime, so it cannot be block scoped. The following example will show an illegal use of the use keyword: ]]> Importing rules are per file basis, meaning included files will NOT inherit the parent file's importing rules. Without any namespace definition, all class and function definitions are placed into the global space - as it was in PHP before namespaces were supported. Prefixing a name with \ will specify that the name is required from the global space even in the context of the namespace. ]]> Inside a namespace, when PHP encounters an unqualified Name in a class name, function or constant context, it resolves these with different priorities. Class names always resolve to the current namespace name. Thus to access internal or non-namespaced user classes, one must refer to them with their fully qualified Name as in: ]]> For functions and constants, PHP will fall back to global functions or constants if a namespaced function or constant does not exist. ]]> 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. The 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: It looks for a function from the current namespace: A\B\foo(). 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(): It looks for a class from the current namespace: A\B\C. It attempts to autoload A\B\C. For new D\E(): It looks for a class by prepending the current namespace: A\B\D\E. It attempts to autoload A\B\D\E. To reference any global class in the global namespace, its fully qualified name new \C() must be used. ]]> This FAQ is split into two sections: common questions, and some specifics of implementation that are helpful to understand fully. First, the common questions. If I don't use namespaces, should I care about any of this? How do I use internal or global classes in a namespace? How do I use namespaces classes functions, or constants in their own namespace? How does a name like \my\name or \name resolve? How does a name like my\name resolve? How does an unqualified class name like name resolve? How does an unqualified function name or unqualified constant name like name resolve? There are a few implementation details of the namespace implementations that are helpful to understand. Import names cannot conflict with classes defined in the same file. Nested namespaces are not allowed. Neither functions nor constants can be imported via the use statement. Dynamic namespace names (quoted identifiers) should escape backslash. Undefined Constants referenced using any backslash die with fatal error Cannot override special constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD No. Namespaces do not affect any existing code in any way, or any as-yet-to-be-written code that does not contain namespaces. You can write this code if you wish: ]]> This is functionally equivalent to: ]]> ]]> ]]> Names that begin with a \ always resolve to what they look like, so \my\name is in fact my\name, and \Exception is Exception. ]]> Names that contain a backslash but do not begin with a backslash like my\name can be resolved in 2 different ways. If there is an import statement that aliases another name to my, then the import alias is applied to the my in my\name. Otherwise, the current namespace name is prepended to my\name. ]]> Class names that do not contain a backslash like name can be resolved in 2 different ways. If there is an import statement that aliases another name to name, then the import alias is applied. Otherwise, the current namespace name is prepended to name. ]]> Function or constant names that do not contain a backslash like name can be resolved in 2 different ways. First, the current namespace name is prepended to name. Finally, if the constant or function name does not exist in the current namespace, a global constant or function name is used if it exists. ]]> The following script combinations are legal: file1.php ]]> another.php ]]> file2.php ]]> There is no name conflict, even though the class MyClass exists within the my\stuff namespace, because the MyClass definition is in a separate file. However, the next example causes a fatal error on name conflict because MyClass is defined in the same file as the use statement. ]]> PHP does not allow nesting namespaces ]]> However, it is easy to simulate nested namespaces like so: ]]> The only elements that are affected by use statements are namespaces and class names. In order to shorten a long constant or function, import its containing namespace ]]> It is very important to realize that because the backslash is used as an escape character within strings, it should always be doubled when used inside a string. Otherwise there is a risk of unintended consequences: ]]> Inside a single-quoted string, the backslash escape sequence is much safer to use, but it is still recommended practice to escape backslashes in all strings as a best practice. Any undefined constant that is unqualified like FOO will produce a notice explaining that PHP assumed FOO was the value of the constant. Any constant, qualified or fully qualified, that contains a backslash will produce a fatal error if not found. ]]> Any attempt to define a namespaced constant that is a special, built-in constant results in a fatal error ]]>