Skip to content

HTTPS clone URL

Subversion checkout URL

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