language/namespaces.xml
1651836ff309efd14a795eff44ee51455f66c7d3
1651836ff309efd14a795eff44ee51455f66c7d3
...
...
@@ -6,10 +6,11 @@
6
6
7
7
<sect1 xml:id="language.namespaces.rationale">
8
8
<title>Namespaces overview</title>
9
+
<titleabbrev>Overview</titleabbrev>
9
10
<?phpdoc print-version-for="namespaces"?>
10
11
<simpara>
11
12
What are namespaces? In the broadest definition namespaces are a way of encapsulating
12
-
items. This can be seen as an abstract concept in many places. For example, in any
13
+
items. This can be seen as an abstract concept in many places. For example, in any
13
14
operating system directories serve to group related files, and act as a namespace for
14
15
the files within them. As a concrete example, the file <literal>foo.txt</literal> can
15
16
exist in both directory <literal>/home/greg</literal> and in <literal>/home/other</literal>,
...
...
@@ -43,7 +44,7 @@
43
44
</para>
44
45
<simpara>
45
46
PHP Namespaces provide a way in which to group related classes, interfaces,
46
-
functions and constants. Here is an example of namespace syntax in PHP:
47
+
functions and constants. Here is an example of namespace syntax in PHP:
47
48
</simpara>
48
49
<example>
49
50
<title>Namespace syntax example</title>
...
...
@@ -86,14 +87,16 @@ echo constant($d); // see "Namespaces and dynamic language features" section
86
87
87
88
<sect1 xml:id="language.namespaces.definition">
88
89
<title>Defining namespaces</title>
90
+
<titleabbrev>Namespaces</titleabbrev>
89
91
<?phpdoc print-version-for="namespaces"?>
90
92
<para>
91
93
Although any valid PHP code can be contained within a namespace, only the following
92
-
types of code are affected by namespaces: classes (including abstracts and traits), interfaces, functions and constants.
94
+
types of code are affected by namespaces: classes (including abstract classes, traits and enums), interfaces,
95
+
functions and constants.
93
96
</para>
94
97
<para>
95
98
Namespaces are declared using the <literal>namespace</literal>
96
-
keyword. A file containing a namespace must declare the namespace
99
+
keyword. A file containing a namespace must declare the namespace
97
100
at the top of the file before any other code - with one exception: the
98
101
<xref linkend="control-structures.declare" /> keyword.
99
102
<example>
...
...
@@ -118,7 +121,7 @@ function connect() { /* ... */ }
118
121
</simpara>
119
122
</note>
120
123
The only code construct allowed before a namespace declaration is the
121
-
<literal>declare</literal> statement, for defining encoding of a source file. In addition,
124
+
<literal>declare</literal> statement, for defining encoding of a source file. In addition,
122
125
no non-PHP code may precede a namespace declaration, including extra whitespace:
123
126
<example>
124
127
<title>Declaring a single namespace</title>
...
...
@@ -139,10 +142,11 @@ namespace MyProject; // fatal error - namespace must be the first statement in t
139
142
</sect1>
140
143
<sect1 xml:id="language.namespaces.nested">
141
144
<title>Declaring sub-namespaces</title>
145
+
<titleabbrev>Sub-namespaces</titleabbrev>
142
146
<?phpdoc print-version-for="namespaces"?>
143
147
<para>
144
148
Much like directories and files, PHP namespaces also contain the ability to specify
145
-
a hierarchy of namespace names. Thus, a namespace name can be defined with
149
+
a hierarchy of namespace names. Thus, a namespace name can be defined with
146
150
sub-levels:
147
151
<example>
148
152
<title>Declaring a single namespace with hierarchy</title>
...
...
@@ -166,9 +170,10 @@ function connect() { /* ... */ }
166
170
</sect1>
167
171
<sect1 xml:id="language.namespaces.definitionmultiple">
168
172
<title>Defining multiple namespaces in the same file</title>
173
+
<titleabbrev>Defining multiple namespaces in the same file</titleabbrev>
169
174
<?phpdoc print-version-for="namespaces"?>
170
175
<para>
171
-
Multiple namespaces may also be declared in the same file. There are two allowed
176
+
Multiple namespaces may also be declared in the same file. There are two allowed
172
177
syntaxes.
173
178
</para>
174
179
<para>
...
...
@@ -223,12 +228,12 @@ function connect() { /* ... */ }
223
228
</para>
224
229
<para>
225
230
It is strongly discouraged as a coding practice to combine multiple namespaces into
226
-
the same file. The primary use case is to combine multiple PHP scripts into the same
231
+
the same file. The primary use case is to combine multiple PHP scripts into the same
227
232
file.
228
233
</para>
229
234
<para>
230
235
To combine global non-namespaced code with namespaced code, only bracketed syntax is
231
-
supported. Global code should be
236
+
supported. Global code should be
232
237
encased in a namespace statement with no namespace name as in:
233
238
<example>
234
239
<title>Declaring multiple namespaces and unnamespaced code</title>
...
...
@@ -281,50 +286,51 @@ echo MyProject\Connection::start();
281
286
</sect1>
282
287
<sect1 xml:id="language.namespaces.basics">
283
288
<title>Using namespaces: Basics</title>
289
+
<titleabbrev>Basics</titleabbrev>
284
290
<?phpdoc print-version-for="namespaces"?>
285
291
<para>
286
292
Before discussing the use of namespaces, it is important to understand how PHP
287
-
knows which namespaced element your code is requesting. A simple analogy can be made
288
-
between PHP namespaces and a filesystem. There are three ways to access a file in a
293
+
knows which namespaced element your code is requesting. A simple analogy can be made
294
+
between PHP namespaces and a filesystem. There are three ways to access a file in a
289
295
file system:
290
296
<orderedlist>
291
297
<listitem>
292
298
<simpara>
293
-
Relative file name like <literal>foo.txt</literal>. This resolves to
294
-
<literal>currentdirectory/foo.txt</literal> where currentdirectory is the
295
-
directory currently occupied. So if the current directory is
299
+
Relative file name like <literal>foo.txt</literal>. This resolves to
300
+
<literal>currentdirectory/foo.txt</literal> where <literal>currentdirectory</literal> is the
301
+
directory currently occupied. So if the current directory is
296
302
<literal>/home/foo</literal>, the name resolves to <literal>/home/foo/foo.txt</literal>.
297
303
</simpara>
298
304
</listitem>
299
305
<listitem>
300
306
<simpara>
301
-
Relative path name like <literal>subdirectory/foo.txt</literal>. This resolves
307
+
Relative path name like <literal>subdirectory/foo.txt</literal>. This resolves
302
308
to <literal>currentdirectory/subdirectory/foo.txt</literal>.
303
309
</simpara>
304
310
</listitem>
305
311
<listitem>
306
312
<simpara>
307
-
Absolute path name like <literal>/main/foo.txt</literal>. This resolves
313
+
Absolute path name like <literal>/main/foo.txt</literal>. This resolves
308
314
to <literal>/main/foo.txt</literal>.
309
315
</simpara>
310
316
</listitem>
311
317
</orderedlist>
312
-
The same principle can be applied to namespaced elements in PHP. For
318
+
The same principle can be applied to namespaced elements in PHP. For
313
319
example, a class name can be referred to in three ways:
314
320
<orderedlist>
315
321
<listitem>
316
322
<simpara>
317
323
Unqualified name, or an unprefixed class name like
318
324
<literal>$a = new foo();</literal> or
319
-
<literal>foo::staticmethod();</literal>. If the current namespace is
325
+
<literal>foo::staticmethod();</literal>. If the current namespace is
320
326
<literal>currentnamespace</literal>, this resolves to
321
-
<literal>currentnamespace\foo</literal>. If
327
+
<literal>currentnamespace\foo</literal>. If
322
328
the code is global, non-namespaced code, this resolves to <literal>foo</literal>.
323
329
</simpara>
324
330
<simpara>
325
331
One caveat: unqualified names for functions and constants will
326
332
resolve to global functions and constants if the namespaced function or constant
327
-
is not defined. See <link linkend="language.namespaces.fallback">Using namespaces:
333
+
is not defined. See <link linkend="language.namespaces.fallback">Using namespaces:
328
334
fallback to global function/constant</link> for details.
329
335
</simpara>
330
336
</listitem>
...
...
@@ -332,9 +338,9 @@ echo MyProject\Connection::start();
332
338
<simpara>
333
339
Qualified name, or a prefixed class name like
334
340
<literal>$a = new subnamespace\foo();</literal> or
335
-
<literal>subnamespace\foo::staticmethod();</literal>. If the current namespace is
341
+
<literal>subnamespace\foo::staticmethod();</literal>. If the current namespace is
336
342
<literal>currentnamespace</literal>, this resolves to
337
-
<literal>currentnamespace\subnamespace\foo</literal>. If
343
+
<literal>currentnamespace\subnamespace\foo</literal>. If
338
344
the code is global, non-namespaced code, this resolves to <literal>subnamespace\foo</literal>.
339
345
</simpara>
340
346
</listitem>
...
...
@@ -342,7 +348,7 @@ echo MyProject\Connection::start();
342
348
<simpara>
343
349
Fully qualified name, or a prefixed name with global prefix operator like
344
350
<literal>$a = new \currentnamespace\foo();</literal> or
345
-
<literal>\currentnamespace\foo::staticmethod();</literal>. This always resolves
351
+
<literal>\currentnamespace\foo::staticmethod();</literal>. This always resolves
346
352
to the literal name specified in the code, <literal>currentnamespace\foo</literal>.
347
353
</simpara>
348
354
</listitem>
...
...
@@ -404,7 +410,7 @@ echo \Foo\Bar\FOO; // resolves to constant Foo\Bar\FOO
404
410
Note that to access any global
405
411
class, function or constant, a fully qualified name can be used, such as
406
412
<function>\strlen</function> or <classname>\Exception</classname> or
407
-
<literal>\INI_ALL</literal>.
413
+
\<constant>INI_ALL</constant>.
408
414
<example>
409
415
<title>Accessing global classes, functions and constants from within a namespace</title>
410
416
<programlisting role="php">
...
...
@@ -427,10 +433,11 @@ $c = new \Exception('error'); // instantiates global class Exception
427
433
</sect1>
428
434
<sect1 xml:id="language.namespaces.dynamic">
429
435
<title>Namespaces and dynamic language features</title>
436
+
<titleabbrev>Namespaces and dynamic language features</titleabbrev>
430
437
<?phpdoc print-version-for="namespaces"?>
431
438
<para>
432
439
PHP's implementation of namespaces is influenced by its dynamic nature as a programming
433
-
language. Thus, to convert code like the following example into namespaced code:
440
+
language. Thus, to convert code like the following example into namespaced code:
434
441
<example>
435
442
<title>Dynamically accessing elements</title>
436
443
<simpara>example1.php:</simpara>
...
...
@@ -504,7 +511,8 @@ echo constant('namespacename\constname'), "\n"; // also prints namespaced
504
511
</para>
505
512
</sect1>
506
513
<sect1 xml:id="language.namespaces.nsconstants">
507
-
<title>namespace keyword and __NAMESPACE__ constant</title>
514
+
<title>The namespace keyword and __NAMESPACE__ magic constant</title>
515
+
<titleabbrev>namespace keyword and __NAMESPACE__</titleabbrev>
508
516
<?phpdoc print-version-for="namespaces"?>
509
517
<para>
510
518
PHP supports two ways of abstractly accessing elements within the current namespace,
...
...
@@ -513,7 +521,7 @@ echo constant('namespacename\constname'), "\n"; // also prints namespaced
513
521
</para>
514
522
<para>
515
523
The value of <constant>__NAMESPACE__</constant> is a string that contains the current
516
-
namespace name. In global, un-namespaced code, it contains an empty string.
524
+
namespace name. In global, un-namespaced code, it contains an empty string.
517
525
<example>
518
526
<title>__NAMESPACE__ example, namespaced code</title>
519
527
<programlisting role="php">
...
...
@@ -558,7 +566,7 @@ function get($classname)
558
566
</para>
559
567
<para>
560
568
The <literal>namespace</literal> keyword can be used to explicitly request
561
-
an element from the current namespace or a sub-namespace. It is the namespace
569
+
an element from the current namespace or a sub-namespace. It is the namespace
562
570
equivalent of the <literal>self</literal> operator for classes.
563
571
<example>
564
572
<title>the namespace operator, inside a namespace</title>
...
...
@@ -601,14 +609,15 @@ $b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
601
609
602
610
<sect1 xml:id="language.namespaces.importing">
603
611
<title>Using namespaces: Aliasing/Importing</title>
612
+
<titleabbrev>Aliasing and Importing</titleabbrev>
604
613
<?phpdoc print-version-for="namespaces"?>
605
614
<para>
606
615
The ability to refer to an external fully qualified name with an alias, or importing,
607
-
is an important feature of namespaces. This is similar to the
616
+
is an important feature of namespaces. This is similar to the
608
617
ability of unix-based filesystems to create symbolic links to a file or to a directory.
609
618
</para>
610
619
<para>
611
-
PHP can alias(/import) constants, functions, classes, interfaces, and namespaces.
620
+
PHP can alias(/import) constants, functions, classes, interfaces, traits, enums and namespaces.
612
621
</para>
613
622
<para>
614
623
Aliasing is accomplished with the <literal>use</literal> operator.
...
...
@@ -689,7 +698,7 @@ $obj = new $a; // instantiates object of class Another
689
698
</example>
690
699
</para>
691
700
<para>
692
-
In addition, importing only affects unqualified and qualified names. Fully qualified
701
+
In addition, importing only affects unqualified and qualified names. Fully qualified
693
702
names are absolute, and unaffected by imports.
694
703
<example>
695
704
<title>Importing and fully qualified names</title>
...
...
@@ -778,6 +787,7 @@ use const some\namespace\{ConstA, ConstB, ConstC};
778
787
</sect1>
779
788
<sect1 xml:id="language.namespaces.global">
780
789
<title>Global space</title>
790
+
<titleabbrev>Global space</titleabbrev>
781
791
<?phpdoc print-version-for="namespaces"?>
782
792
<para>
783
793
Without any namespace definition, all class and function definitions are
...
...
@@ -805,12 +815,13 @@ function fopen() {
805
815
</para>
806
816
</sect1>
807
817
<sect1 xml:id="language.namespaces.fallback">
808
-
<title>Using namespaces: fallback to global function/constant</title>
818
+
<title>Using namespaces: fallback to the global space for functions and constants</title>
819
+
<titleabbrev>Fallback to global space</titleabbrev>
809
820
<?phpdoc print-version-for="namespaces"?>
810
821
<para>
811
822
Inside a namespace, when PHP encounters an unqualified Name in a class name, function or
812
-
constant context, it resolves these with different priorities. Class names always
813
-
resolve to the current namespace name. Thus to access internal or non-namespaced
823
+
constant context, it resolves these with different priorities. Class names always
824
+
resolve to the current namespace name. Thus to access internal or non-namespaced
814
825
user classes, one must refer to them with their fully qualified Name as in:
815
826
<example>
816
827
<title>Accessing global classes inside a namespace</title>
...
...
@@ -863,6 +874,7 @@ if (is_array('hi')) { // prints "is not array"
863
874
864
875
<sect1 xml:id="language.namespaces.rules">
865
876
<title>Name resolution rules</title>
877
+
<titleabbrev>Name resolution rules</titleabbrev>
866
878
<?phpdoc print-version-for="namespaces"?>
867
879
<para>
868
880
For the purposes of these resolution rules, here are some important definitions:
...
...
@@ -945,8 +957,8 @@ if (is_array('hi')) { // prints "is not array"
945
957
class/namespace import table, function names according to the function import table and
946
958
constants according to the constant import table. For example, after
947
959
<literal>use A\B\C;</literal> a usage such as <literal>new C()</literal> resolves to the name
948
-
<literal>A\B\C()</literal>. Similarly, after <literal>use function A\B\fn;</literal> a usage
949
-
such as <literal>fn()</literal> resolves to the name <literal>A\B\fn</literal>.
960
+
<literal>A\B\C()</literal>. Similarly, after <literal>use function A\B\foo;</literal> a usage
961
+
such as <literal>foo()</literal> resolves to the name <literal>A\B\foo</literal>.
950
962
</simpara>
951
963
</listitem>
952
964
<listitem>
...
...
@@ -1049,6 +1061,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1049
1061
</sect1>
1050
1062
<sect1 xml:id="language.namespaces.faq">
1051
1063
<title>FAQ: things you need to know about namespaces</title>
1064
+
<titleabbrev>FAQ</titleabbrev>
1052
1065
<?phpdoc print-version-for="namespaces"?>
1053
1066
<para>
1054
1067
This FAQ is split into two sections: common questions, and some specifics of
...
...
@@ -1135,7 +1148,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1135
1148
<listitem>
1136
1149
<simpara>
1137
1150
<link linkend="language.namespaces.faq.builtinconst">Cannot override special
1138
-
constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD</link>
1151
+
constants &null;, &true; or &false;</link>
1139
1152
</simpara>
1140
1153
</listitem>
1141
1154
</orderedlist>
...
...
@@ -1143,8 +1156,8 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1143
1156
<sect2 xml:id="language.namespaces.faq.shouldicare">
1144
1157
<title>If I don't use namespaces, should I care about any of this?</title>
1145
1158
<para>
1146
-
No. Namespaces do not affect any existing code in any way, or any
1147
-
as-yet-to-be-written code that does not contain namespaces. You can
1159
+
No. Namespaces do not affect any existing code in any way, or any
1160
+
as-yet-to-be-written code that does not contain namespaces. You can
1148
1161
write this code if you wish:
1149
1162
</para>
1150
1163
<para>
...
...
@@ -1412,7 +1425,7 @@ $a = new MyClass; // instantiates class "thing" from namespace another
1412
1425
<para>
1413
1426
There is no name conflict, even though the class <literal>MyClass</literal> exists
1414
1427
within the <literal>my\stuff</literal> namespace, because the MyClass definition is
1415
-
in a separate file. However, the next example causes a fatal error on name conflict
1428
+
in a separate file. However, the next example causes a fatal error on name conflict
1416
1429
because MyClass is defined in the same file as the use statement.
1417
1430
<informalexample>
1418
1431
<programlisting role="php">
...
...
@@ -1464,7 +1477,7 @@ namespace my\stuff\nested {
1464
1477
<title>Dynamic namespace names (quoted identifiers) should escape backslash</title>
1465
1478
<para>
1466
1479
It is very important to realize that because the backslash is used as an escape character
1467
-
within strings, it should always be doubled when used inside a string. Otherwise
1480
+
within strings, it should always be doubled when used inside a string. Otherwise
1468
1481
there is a risk of unintended consequences:
1469
1482
<example>
1470
1483
<title>Dangers of using namespaced names inside a double-quoted string</title>
...
...
@@ -1489,7 +1502,7 @@ $obj = new $a;
1489
1502
<para>
1490
1503
Any undefined constant that is unqualified like <literal>FOO</literal> will
1491
1504
produce a notice explaining that PHP assumed <literal>FOO</literal> was the value
1492
-
of the constant. Any constant, qualified or fully qualified, that contains a
1505
+
of the constant. Any constant, qualified or fully qualified, that contains a
1493
1506
backslash will produce a fatal error if not found.
1494
1507
<example>
1495
1508
<title>Undefined constants</title>
...
...
@@ -1508,7 +1521,7 @@ $a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
1508
1521
</para>
1509
1522
</sect2>
1510
1523
<sect2 xml:id="language.namespaces.faq.builtinconst">
1511
-
<title>Cannot override special constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD</title>
1524
+
<title>Cannot override special constants &null;, &true; or &false;</title>
1512
1525
<para>
1513
1526
Any attempt to define a namespaced constant that is a special, built-in constant
1514
1527
results in a fatal error
1515
1528