xref: /PHP-7.1/Zend/RFCs/002.txt (revision 7f6387b5)
1Title:           Zend 2.0 Namespaces
2Version:         $Id: aaef2827c11ef1b0f4c4e4e2916c1ebfd47f0509 $
3Status:          declined
4Maintainer:      Stig S. Bakken <ssb@php.net>
5Created:         2001-09-08
6Modified:        2001-09-08
7
8
91. Background/Need
10==================
11
12PHP and Zend 1.0 have come to a point where a lot of reusable code is
13being written; from simple functions and classes to entire application
14frameworks.  It is becoming increasingly difficult to avoid symbol
15name collisions with the current scoping methods.
16
17The symbol scopes available in Zend 1.0 are the global scope, the
18class scope and the function scope.  All scopes but classes may
19contain variables, only the class and global scopes may contain
20functions, while only the global scope may contain constants and
21classes.  This means that all of Zend 1.0's scoping methods are
22inherently limited for solving symbol name collision problems.
23
24
252. Overview
26===========
27
28Namespaces in Zend 2.0 provide a way to manage the symbol collision
29problem by making it possible to define multiple symbol tables able to
30contain all types of symbols.  Zend will get the notion of a current
31namespace, defaulting to the current global one.  The current name
32space may be changed on a file-by-file basis.  Symbols in other name
33spaces than the current one may be referenced using a new namespace
34operator.  It will be possible to "import" symbols from one namespace
35into another.
36
37
383. Functionality
39================
40
413.1. Namespace Syntax
42=====================
43
44The namespace operator ":" is used to refer to symbols in other
45namespaces than the current one:
46
47Class:          Namespace:class
48Function:       Namespace:function
49Static method:  Namespace:class::method
50Variable:       $Namespace:variable
51Constant:       Namespace:CONSTANT
52Class variable: $Namespace:class::variable
53
54To refer to symbols in the global namespace, symbols are prefixed with
55only the namespace operator:
56
57Class:          :class
58Function:       :function
59Static method:  :class::method
60Variable:       $:variable
61Constant:       :CONSTANT
62Class variable: $:class::variable
63
64Note: $:variable will effectively be just another syntax for
65$GLOBALS['variable'].
66
67A namespace may have a name containing a ":", it is always the last
68":" character in the symbol qualifier that is the actual namespace
69operator:
70
71Class:          Name:Space:class
72Function:       Name:Space:function
73Static method:  Name:Space:class::method
74Variable:       $Name:Space:variable
75Constant:       Name:Space:CONSTANT
76Class variable: $Name:Space:class::variable
77
78(Here, the ":" between "Name" and "Space" is part of the name, it is
79the one after "Space" that is the namespace operator.)
80
81
823.2. Defining Namespaces
83========================
84
85Individual files may define a namespace that will apply to the entire
86file.  If no "namespace" operator occurs in the file, it will be in
87the global namespace:
88
89 1 namespace HTML;
90 2
91 3 class Form {
92 4     function Form() {
93 5         // constructor
94 6     }
95 7     // ...
96 8 }
97
98Or with the "nested" name syntax:
99
100 1 namespace HTML:Form;
101 2
102 3 class Image {
103 4     var $src;
104 5     function Image($src) {
105 6         $this->src = $src;
106 7     }
107 8     // ...
108 9 }
109
110Code executed within the "HTML" namespace may refer to the Form class
111as just "Form".  Code executed from within other namespaces has to
112refer to it as "HTML:Form".  The "namespace" statement must occur
113before any other statements in the file.
114
115# [ssb 2001-09-08]:
116# Should it be possible to "add" symbols to a namespace by including a
117# second file with the same namespace statement?
118
119
1203.3. Importing Symbols
121======================
122
123It is possible to import symbols from another namespace into the
124current one with the "import" statement:
125
126  import * from HTML;          // all symbols
127
128  import Form from HTML;       // single symbols
129
130  import Form,Table from HTML; // multiple symbols
131
132There is a potential for name clashes between symols of different
133types that have the same qualifier syntax.  These are resolved in this
134order: class, function, constant.
135
136Optionally, the symbol type may be explicitly given to import (as
137"class", "function", "variable" or "constant"):
138
139  import class Form from HTML;
140
141And finally, you may import all symbols of a given type:
142
143  import constant * from HTML:Table;
144
145The namespace with its symbols must already be defined before using
146"import".
147
148
1494. Compatibility Notes
150======================
151
152Old code that does not take advantage of namespaces will run without
153modifications.
154
155
1565. Dependencies
157===============
158
159The class variable syntax depends on this class variables being
160implemented in the new ZE2 object model.
161
162
1636. Acknowledgements
164===================
165
166Andi Gutmans <andi@zend.com> and Zeev Suraski <zeev@zend.com> for
167initial ZE2 namespaces proposal
168
169Dean Hall <php@apt7.com> for the initial symbol qualification syntax
170