Php/docs/language.namespaces.basics
Using namespaces: Basics
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
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 tocurrentdirectory/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 tocurrentdirectory/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();
orfoo::staticmethod();
. If the current namespace iscurrentnamespace
, this resolves tocurrentnamespace\foo
. If the code is global, non-namespaced code, this resolves tofoo
. 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();
orsubnamespace\foo::staticmethod();
. If the current namespace iscurrentnamespace
, this resolves tocurrentnamespace\subnamespace\foo
. If the code is global, non-namespaced code, this resolves tosubnamespace\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
<?phpnamespace Foo\Bar\subnamespace;const FOO = 1;function foo() {}class foo{ static function staticmethod() {}}?>
file2.php
<?phpnamespace Foo\Bar;include 'file1.php';const FOO = 2;function foo() {}class foo{ static function staticmethod() {}}/* Unqualified name */foo(); // resolves to function Foo\Bar\foofoo::staticmethod(); // resolves to class Foo\Bar\foo, method staticmethodecho FOO; // resolves to constant Foo\Bar\FOO/* Qualified name */subnamespace\foo(); // resolves to function Foo\Bar\subnamespace\foosubnamespace\foo::staticmethod(); // resolves to class Foo\Bar\subnamespace\foo, // method staticmethodecho subnamespace\FOO; // resolves to constant Foo\Bar\subnamespace\FOO /* Fully qualified name */\Foo\Bar\foo(); // resolves to function Foo\Bar\foo\Foo\Bar\foo::staticmethod(); // resolves to class Foo\Bar\foo, method staticmethodecho \Foo\Bar\FOO; // resolves to constant Foo\Bar\FOO?>
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
.
Example #1 Accessing global classes, functions and constants from within a namespace
<?phpnamespace Foo;function strlen() {}const INI_ALL = 3;class Exception {}$a = \strlen('hi'); // calls global function strlen$b = \INI_ALL; // accesses global constant INI_ALL$c = new \Exception('error'); // instantiates global class Exception?>