xref: /PHP-5.4/README.namespaces (revision 56c9e22c)
1Design
2======
3
4Main assumption of the model is that the problem that we are to solve is the
5problem of the very long class names in PHP libraries. We would not attempt
6to take autoloader's job or create packaging model - only make names
7manageable.
8
9Namespaces are defined the following way:
10
11Zend/DB/Connection.php:
12<?php
13namespace Zend\DB;
14
15class Connection {
16}
17
18function connect() {
19}
20?>
21
22Namespace definition does the following:
23All class and function names inside are automatically prefixed with
24namespace name. Inside namespace, local name always takes precedence over
25global name. Several files may be using the same namespace.
26The namespace declaration statement must be the very first statement in
27the file. The only exception is "declare" statement that can be used before.
28
29Every class and function in a namespace can be referred to by the full name
30- e.g. Zend\DB\Connection or Zend\DB\connect - at any time.
31
32<?php
33require 'Zend/Db/Connection.php';
34$x = new Zend\DB\Connection;
35Zend\DB\connect();
36?>
37
38Namespace or class name can be imported:
39
40<?php
41require 'Zend/Db/Connection.php';
42use Zend\DB;
43use Zend\DB\Connection as DbConnection;
44
45$x = new Zend\DB\Connection();
46$y = new DB\connection();
47$z = new DbConnection();
48DB\connect();
49?>
50
51The use statement only defines name aliasing. It may create name alias for
52namespace or class. The simple form of statement "use A\B\C\D;" is
53equivalent to "use A\B\C\D as D;". The use statement can be used at any
54time in the global scope (not inside function/class) and takes effect from
55the point of definition down to the end of file. It is recommended however to
56place the use statements at the beginning of the file. The use statements have
57effect only on the file where they appear.
58
59The special "empty" namespace (\ prefix) is useful as explicit global
60namespace qualification. All class and function names started from \
61interpreted as global.
62
63<?php
64namespace A\B\C;
65
66$con = \mysql_connect(...);
67?>
68
69A special constant __NAMESPACE__ contains the name of the current namespace.
70It can be used to construct fully-qualified names to pass them as callbacks.
71
72<?php
73namespace A\B\C;
74
75function foo() {
76}
77
78set_error_handler(__NAMESPACE__ . "\foo");
79?>
80
81In global namespace __NAMESPACE__ constant has the value of empty string.
82
83Names inside namespace are resolved according to the following rules:
84
851) all qualified names are translated during compilation according to
86current import rules. So if we have "use A\B\C" and then "C\D\e()"
87it is translated to "A\B\C\D\e()".
882) unqualified class names translated during compilation according to
89current import rules. So if we have "use A\B\C" and then "new C()" it
90is translated to "new A\B\C()".
913) inside namespace, calls to unqualified functions that are defined in
92current namespace (and are known at the time the call is parsed) are
93interpreted as calls to these namespace functions.
944) inside namespace, calls to unqualified functions that are not defined
95in current namespace are resolved at run-time. The call to function foo()
96inside namespace (A\B) first tries to find and call function from current
97namespace A\B\foo() and if it doesn't exist PHP tries to call internal
98function foo(). Note that using foo() inside namespace you can call only
99internal PHP functions, however using \foo() you are able to call any
100function from the global namespace.
1015) unqualified class names are resolved at run-time. E.q. "new Exception()"
102first tries to use (and autoload) class from current namespace and in case
103of failure uses internal PHP class. Note that using "new A" in namespace
104you can only create class from this namespace or internal PHP class, however
105using "new \A" you are able to create any class from the global namespace.
1066) Calls to qualified functions are resolved at run-time. Call to
107A\B\foo() first tries to call function foo() from namespace A\B, then
108it tries to find class A\B (__autoload() it if necessary) and call its
109static method foo()
1107) qualified class names are interpreted as class from corresponding
111namespace. So "new A\B\C()" refers to class C from namespace A\B.
112
113Examples
114--------
115<?php
116namespace A;
117foo();   // first tries to call "foo" defined in namespace "A"
118         // then calls internal function "foo"
119\foo(); // calls function "foo" defined in global scope
120?>
121
122<?php
123namespace A;
124new B();   // first tries to create object of class "B" defined in namespace "A"
125           // then creates object of internal class "B"
126new \B(); // creates object of class "B" defined in global scope
127?>
128
129<?php
130namespace A;
131new A(); // first tries to create object of class "A" from namespace "A" (A\A)
132         // then creates object of internal class "A"
133?>
134
135<?php
136namespace A;
137B\foo();   // first tries to call function "foo" from namespace "A\B"
138            // then calls method "foo" of internal class "B"
139\B\foo(); // first tries to call function "foo" from namespace "B"
140            // then calls method "foo" of class "B" from global scope
141?>
142
143The worst case if class name conflicts with namespace name
144<?php
145namespace A;
146A\foo();   // first tries to call function "foo" from namespace "A\A"
147            // then tries to call method "foo" of class "A" from namespace "A"
148            // then tries to call function "foo" from namespace "A"
149            // then calls method "foo" of internal class "A"
150\A\foo(); // first tries to call function "foo" from namespace "A"
151            // then calls method "foo" of class "A" from global scope
152?>
153
154TODO
155====
156
157* Support for namespace constants?
158
159* performance problems
160  - calls to internal functions in namespaces are slower, because PHP first
161    looks for such function in current namespace
162  - calls to static methods are slower, because PHP first tries to look
163    for corresponding function in namespace
164
165* Extend the Reflection API?
166  * Add ReflectionNamespace class
167    + getName()
168    + getClasses()
169    + getFunctions()
170    + getFiles()
171  * Add getNamespace() methods to ReflectionClass and ReflectionFunction
172
173* Rename namespaces to packages?
174
175