language/namespaces.xml
d4d5216e7a965ca194f6b1c9dee84cecab2674e5
d4d5216e7a965ca194f6b1c9dee84cecab2674e5
...
...
@@ -6,6 +6,7 @@
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
...
...
@@ -19,26 +20,7 @@
19
20
name using the directory separator to get <literal>/home/greg/foo.txt</literal>. This
20
21
same principle extends to namespaces in the programming world.
21
22
</simpara>
22
-
<para>
23
-
<informaltable>
24
-
<tgroup cols="2">
25
-
<thead>
26
-
<row>
27
-
<entry>&Version;</entry>
28
-
<entry>&Description;</entry>
29
-
</row>
30
-
</thead>
31
-
<tbody>
32
-
<row>
33
-
<entry>7.0.0</entry>
34
-
<entry>
35
-
Added Group use Declarations.
36
-
</entry>
37
-
</row>
38
-
</tbody>
39
-
</tgroup>
40
-
</informaltable>
41
-
</para>
23
+
42
24
<simpara>
43
25
In the PHP world, namespaces are designed to solve two problems that authors
44
26
of libraries and applications encounter when creating re-usable code elements
...
...
@@ -89,10 +71,15 @@ echo constant($d); // see "Namespaces and dynamic language features" section
89
71
]]>
90
72
</programlisting>
91
73
</example>
74
+
<note>
75
+
<simpara>
76
+
Namespace names are case-insensitive.
77
+
</simpara>
78
+
</note>
92
79
<note>
93
80
<para>
94
-
Namespace names <literal>PHP</literal> and <literal>php</literal>, and compound names starting
95
-
with these names (like <literal>PHP\Classes</literal>) are reserved for internal language use
81
+
The Namespace name <literal>PHP</literal>, and compound names starting
82
+
with this name (like <literal>PHP\Classes</literal>) are reserved for internal language use
96
83
and should not be used in the userspace code.
97
84
</para>
98
85
</note>
...
...
@@ -100,6 +87,7 @@ echo constant($d); // see "Namespaces and dynamic language features" section
100
87
101
88
<sect1 xml:id="language.namespaces.definition">
102
89
<title>Defining namespaces</title>
90
+
<titleabbrev>Namespaces</titleabbrev>
103
91
<?phpdoc print-version-for="namespaces"?>
104
92
<para>
105
93
Although any valid PHP code can be contained within a namespace, only the following
...
...
@@ -125,6 +113,12 @@ function connect() { /* ... */ }
125
113
]]>
126
114
</programlisting>
127
115
</example>
116
+
<note>
117
+
<simpara>
118
+
Fully qualified names (i.e. names starting with a backslash) are not allowed in namespace
119
+
declarations, because such constructs are interpreted as relative namespace expressions.
120
+
</simpara>
121
+
</note>
128
122
The only code construct allowed before a namespace declaration is the
129
123
<literal>declare</literal> statement, for defining encoding of a source file. In addition,
130
124
no non-PHP code may precede a namespace declaration, including extra whitespace:
...
...
@@ -147,6 +141,7 @@ namespace MyProject; // fatal error - namespace must be the first statement in t
147
141
</sect1>
148
142
<sect1 xml:id="language.namespaces.nested">
149
143
<title>Declaring sub-namespaces</title>
144
+
<titleabbrev>Sub-namespaces</titleabbrev>
150
145
<?phpdoc print-version-for="namespaces"?>
151
146
<para>
152
147
Much like directories and files, PHP namespaces also contain the ability to specify
...
...
@@ -174,6 +169,7 @@ function connect() { /* ... */ }
174
169
</sect1>
175
170
<sect1 xml:id="language.namespaces.definitionmultiple">
176
171
<title>Defining multiple namespaces in the same file</title>
172
+
<titleabbrev>Defining multiple namespaces in the same file</titleabbrev>
177
173
<?phpdoc print-version-for="namespaces"?>
178
174
<para>
179
175
Multiple namespaces may also be declared in the same file. There are two allowed
...
...
@@ -289,6 +285,7 @@ echo MyProject\Connection::start();
289
285
</sect1>
290
286
<sect1 xml:id="language.namespaces.basics">
291
287
<title>Using namespaces: Basics</title>
288
+
<titleabbrev>Basics</titleabbrev>
292
289
<?phpdoc print-version-for="namespaces"?>
293
290
<para>
294
291
Before discussing the use of namespaces, it is important to understand how PHP
...
...
@@ -299,7 +296,7 @@ echo MyProject\Connection::start();
299
296
<listitem>
300
297
<simpara>
301
298
Relative file name like <literal>foo.txt</literal>. This resolves to
302
-
<literal>currentdirectory/foo.txt</literal> where currentdirectory is the
299
+
<literal>currentdirectory/foo.txt</literal> where <literal>currentdirectory</literal> is the
303
300
directory currently occupied. So if the current directory is
304
301
<literal>/home/foo</literal>, the name resolves to <literal>/home/foo/foo.txt</literal>.
305
302
</simpara>
...
...
@@ -412,7 +409,7 @@ echo \Foo\Bar\FOO; // resolves to constant Foo\Bar\FOO
412
409
Note that to access any global
413
410
class, function or constant, a fully qualified name can be used, such as
414
411
<function>\strlen</function> or <classname>\Exception</classname> or
415
-
<literal>\INI_ALL</literal>.
412
+
\<constant>INI_ALL</constant>.
416
413
<example>
417
414
<title>Accessing global classes, functions and constants from within a namespace</title>
418
415
<programlisting role="php">
...
...
@@ -435,6 +432,7 @@ $c = new \Exception('error'); // instantiates global class Exception
435
432
</sect1>
436
433
<sect1 xml:id="language.namespaces.dynamic">
437
434
<title>Namespaces and dynamic language features</title>
435
+
<titleabbrev>Namespaces and dynamic language features</titleabbrev>
438
436
<?phpdoc print-version-for="namespaces"?>
439
437
<para>
440
438
PHP's implementation of namespaces is influenced by its dynamic nature as a programming
...
...
@@ -512,7 +510,8 @@ echo constant('namespacename\constname'), "\n"; // also prints namespaced
512
510
</para>
513
511
</sect1>
514
512
<sect1 xml:id="language.namespaces.nsconstants">
515
-
<title>namespace keyword and __NAMESPACE__ constant</title>
513
+
<title>The namespace keyword and __NAMESPACE__ magic constant</title>
514
+
<titleabbrev>namespace keyword and __NAMESPACE__</titleabbrev>
516
515
<?phpdoc print-version-for="namespaces"?>
517
516
<para>
518
517
PHP supports two ways of abstractly accessing elements within the current namespace,
...
...
@@ -606,8 +605,10 @@ $b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
606
605
</example>
607
606
</para>
608
607
</sect1>
608
+
609
609
<sect1 xml:id="language.namespaces.importing">
610
610
<title>Using namespaces: Aliasing/Importing</title>
611
+
<titleabbrev>Aliasing and Importing</titleabbrev>
611
612
<?phpdoc print-version-for="namespaces"?>
612
613
<para>
613
614
The ability to refer to an external fully qualified name with an alias, or importing,
...
...
@@ -615,14 +616,11 @@ $b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
615
616
ability of unix-based filesystems to create symbolic links to a file or to a directory.
616
617
</para>
617
618
<para>
618
-
All versions of PHP that support namespaces support three kinds of aliasing
619
-
or importing: aliasing a class name, aliasing an interface name, and
620
-
aliasing a namespace name. PHP 5.6+ also allows aliasing or importing
621
-
function and constant names.
619
+
PHP can alias(/import) constants, functions, classes, interfaces, traits, enums and namespaces.
622
620
</para>
623
621
<para>
624
-
In PHP, aliasing is accomplished with the <literal>use</literal> operator. Here
625
-
is an example showing all 5 kinds of importing:
622
+
Aliasing is accomplished with the <literal>use</literal> operator.
623
+
Here is an example showing all 5 kinds of importing:
626
624
<example>
627
625
<title>importing/aliasing with the use operator</title>
628
626
<programlisting role="php">
...
...
@@ -637,13 +635,13 @@ use My\Full\NSname;
637
635
// importing a global class
638
636
use ArrayObject;
639
637
640
-
// importing a function (PHP 5.6+)
638
+
// importing a function
641
639
use function My\Full\functionName;
642
640
643
-
// aliasing a function (PHP 5.6+)
641
+
// aliasing a function
644
642
use function My\Full\functionName as func;
645
643
646
-
// importing a constant (PHP 5.6+)
644
+
// importing a constant
647
645
use const My\Full\CONSTANT;
648
646
649
647
$obj = new namespace\Another; // instantiates object of class foo\Another
...
...
@@ -756,7 +754,7 @@ function toGreenlandic()
756
754
<sect2 xml:id="language.namespaces.importing.group">
757
755
<title>Group <literal>use</literal> declarations</title>
758
756
<para>
759
-
From PHP 7.0 onwards, classes, functions and constants being imported from
757
+
Classes, functions and constants being imported from
760
758
the same &namespace; can be grouped together in a single &use.namespace;
761
759
statement.
762
760
</para>
...
...
@@ -765,7 +763,6 @@ function toGreenlandic()
765
763
<![CDATA[
766
764
<?php
767
765
768
-
// Pre PHP 7 code
769
766
use some\namespace\ClassA;
770
767
use some\namespace\ClassB;
771
768
use some\namespace\ClassC as C;
...
...
@@ -778,7 +775,7 @@ use const some\namespace\ConstA;
778
775
use const some\namespace\ConstB;
779
776
use const some\namespace\ConstC;
780
777
781
-
// PHP 7+ code
778
+
// is equivalent to the following groupped use declaration
782
779
use some\namespace\{ClassA, ClassB, ClassC as C};
783
780
use function some\namespace\{fn_a, fn_b, fn_c};
784
781
use const some\namespace\{ConstA, ConstB, ConstC};
...
...
@@ -789,6 +786,7 @@ use const some\namespace\{ConstA, ConstB, ConstC};
789
786
</sect1>
790
787
<sect1 xml:id="language.namespaces.global">
791
788
<title>Global space</title>
789
+
<titleabbrev>Global space</titleabbrev>
792
790
<?phpdoc print-version-for="namespaces"?>
793
791
<para>
794
792
Without any namespace definition, all class and function definitions are
...
...
@@ -816,7 +814,8 @@ function fopen() {
816
814
</para>
817
815
</sect1>
818
816
<sect1 xml:id="language.namespaces.fallback">
819
-
<title>Using namespaces: fallback to global function/constant</title>
817
+
<title>Using namespaces: fallback to the global space for functions and constants</title>
818
+
<titleabbrev>Fallback to global space</titleabbrev>
820
819
<?phpdoc print-version-for="namespaces"?>
821
820
<para>
822
821
Inside a namespace, when PHP encounters an unqualified Name in a class name, function or
...
...
@@ -874,6 +873,7 @@ if (is_array('hi')) { // prints "is not array"
874
873
875
874
<sect1 xml:id="language.namespaces.rules">
876
875
<title>Name resolution rules</title>
876
+
<titleabbrev>Name resolution rules</titleabbrev>
877
877
<?phpdoc print-version-for="namespaces"?>
878
878
<para>
879
879
For the purposes of these resolution rules, here are some important definitions:
...
...
@@ -905,6 +905,15 @@ if (is_array('hi')) { // prints "is not array"
905
905
</para>
906
906
</listitem>
907
907
</varlistentry>
908
+
<varlistentry>
909
+
<term>Relative name</term>
910
+
<listitem>
911
+
<para>
912
+
This is an identifier starting with <literal>namespace</literal>, such as
913
+
<literal>namespace\Foo\Bar</literal>.
914
+
</para>
915
+
</listitem>
916
+
</varlistentry>
908
917
</variablelist>
909
918
</para>
910
919
<para>
...
...
@@ -912,40 +921,58 @@ if (is_array('hi')) { // prints "is not array"
912
921
<orderedlist>
913
922
<listitem>
914
923
<simpara>
915
-
Calls to fully qualified functions, classes or constants are resolved at compile-time.
916
-
For instance <literal>new \A\B</literal> resolves to class <literal>A\B</literal>.
924
+
Fully qualified names always resolve to the name without leading namespace separator.
925
+
For instance <literal>\A\B</literal> resolves to <literal>A\B</literal>.
926
+
</simpara>
927
+
</listitem>
928
+
<listitem>
929
+
<simpara>
930
+
Relative names always resolve to the name with <literal>namespace</literal> replaced by
931
+
the current namespace. If the name occurs in the global namespace, the
932
+
<literal>namespace\</literal> prefix is stripped. For example <literal>namespace\A</literal>
933
+
inside namespace <literal>X\Y</literal> resolves to <literal>X\Y\A</literal>. The same name
934
+
inside the global namespace resolves to <literal>A</literal>.
917
935
</simpara>
918
936
</listitem>
919
937
<listitem>
920
938
<simpara>
921
-
All unqualified and qualified names (not fully qualified names) are translated during
922
-
compilation according to current
923
-
import rules. For example, if the namespace <literal>A\B\C</literal> is imported as
924
-
<literal>C</literal>, a call to
925
-
<literal>C\D\e()</literal> is translated to <literal>A\B\C\D\e()</literal>.
939
+
For qualified names the first segment of the name is translated according to the current
940
+
class/namespace import table. For example, if the namespace <literal>A\B\C</literal> is
941
+
imported as <literal>C</literal>, the name <literal>C\D\E</literal> is translated to
942
+
<literal>A\B\C\D\E</literal>.
926
943
</simpara>
927
944
</listitem>
928
945
<listitem>
929
946
<simpara>
930
-
Inside a namespace, all qualified names not translated according to import
931
-
rules have the current namespace prepended. For example, if a call
932
-
to <literal>C\D\e()</literal> is performed within namespace <literal>A\B</literal>,
933
-
it is translated to <literal>A\B\C\D\e()</literal>.
947
+
For qualified names, if no import rule applies, the current namespace is prepended to the
948
+
name. For example, the name <literal>C\D\E</literal> inside namespace <literal>A\B</literal>,
949
+
resolves to <literal>A\B\C\D\E</literal>.
934
950
</simpara>
935
951
</listitem>
936
952
<listitem>
937
953
<simpara>
938
-
Unqualified class names are translated during compilation according to current
939
-
import rules (full name substituted for short imported name). In example, if
940
-
the namespace <literal>A\B\C</literal> is imported as C, <literal>new C()</literal> is
941
-
translated to <literal>new A\B\C()</literal>.
954
+
For unqualified names, the name is translated according to the current import table for the
955
+
respective symbol type. This means that class-like names are translated according to the
956
+
class/namespace import table, function names according to the function import table and
957
+
constants according to the constant import table. For example, after
958
+
<literal>use A\B\C;</literal> a usage such as <literal>new C()</literal> resolves to the name
959
+
<literal>A\B\C()</literal>. Similarly, after <literal>use function A\B\foo;</literal> a usage
960
+
such as <literal>foo()</literal> resolves to the name <literal>A\B\foo</literal>.
942
961
</simpara>
943
962
</listitem>
944
963
<listitem>
945
964
<simpara>
946
-
Inside namespace (say A\B), calls to unqualified functions are resolved at run-time.
947
-
Here is how a
948
-
call to function <literal>foo()</literal> is resolved:
965
+
For unqualified names, if no import rule applies and the name refers to a class-like symbol,
966
+
the current namespace is prepended. For example <literal>new C()</literal> inside namespace
967
+
<literal>A\B</literal> resolves to name <literal>A\B\C</literal>.
968
+
</simpara>
969
+
</listitem>
970
+
<listitem>
971
+
<simpara>
972
+
For unqualified names, if no import rule applies and the name refers to a function or constant
973
+
and the code is outside the global namespace, the name is resolved at runtime.
974
+
Assuming the code is in namespace <literal>A\B</literal>, here is how a call to function
975
+
<literal>foo()</literal> is resolved:
949
976
</simpara>
950
977
<orderedlist>
951
978
<listitem>
...
...
@@ -962,48 +989,6 @@ if (is_array('hi')) { // prints "is not array"
962
989
</listitem>
963
990
</orderedlist>
964
991
</listitem>
965
-
<listitem>
966
-
<simpara>
967
-
Inside namespace (say <literal>A\B</literal>), calls to unqualified or qualified
968
-
class names (not fully qualified class names)
969
-
are resolved at run-time. Here is how a call to
970
-
<literal>new C()</literal> or <literal>new D\E()</literal> is resolved.
971
-
For <literal> new C()</literal>:
972
-
</simpara>
973
-
<orderedlist>
974
-
<listitem>
975
-
<simpara>
976
-
It looks for a class from the current namespace:
977
-
<literal>A\B\C</literal>.
978
-
</simpara>
979
-
</listitem>
980
-
<listitem>
981
-
<simpara>
982
-
It attempts to autoload <literal>A\B\C</literal>.
983
-
</simpara>
984
-
</listitem>
985
-
</orderedlist>
986
-
<simpara>
987
-
For <literal> new D\E()</literal>:
988
-
</simpara>
989
-
<orderedlist>
990
-
<listitem>
991
-
<simpara>
992
-
It looks for a class by prepending the current namespace:
993
-
<literal>A\B\D\E</literal>.
994
-
</simpara>
995
-
</listitem>
996
-
<listitem>
997
-
<simpara>
998
-
It attempts to autoload <literal>A\B\D\E</literal>.
999
-
</simpara>
1000
-
</listitem>
1001
-
</orderedlist>
1002
-
<simpara>
1003
-
To reference any global class in the global namespace,
1004
-
its fully qualified name <literal>new \C()</literal> must be used.
1005
-
</simpara>
1006
-
</listitem>
1007
992
</orderedlist>
1008
993
</para>
1009
994
<example>
...
...
@@ -1075,6 +1060,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1075
1060
</sect1>
1076
1061
<sect1 xml:id="language.namespaces.faq">
1077
1062
<title>FAQ: things you need to know about namespaces</title>
1063
+
<titleabbrev>FAQ</titleabbrev>
1078
1064
<?phpdoc print-version-for="namespaces"?>
1079
1065
<para>
1080
1066
This FAQ is split into two sections: common questions, and some specifics of
...
...
@@ -1136,7 +1122,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1136
1122
<orderedlist>
1137
1123
<listitem>
1138
1124
<simpara>
1139
-
<link linkend="language.namespaces.faq.conflict">Import names cannot conflict with
1125
+
<link linkend="language.namespaces.faq.conflict">Import names must not conflict with
1140
1126
classes defined in the same file.</link>
1141
1127
</simpara>
1142
1128
</listitem>
...
...
@@ -1148,13 +1134,6 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1148
1134
</listitem>
1149
1135
<listitem>
1150
1136
<simpara>
1151
-
<link linkend="language.namespaces.faq.nofuncconstantuse">Before PHP 5.6 neither functions nor
1152
-
constants can be imported via the <literal>use</literal>
1153
-
statement.</link>
1154
-
</simpara>
1155
-
</listitem>
1156
-
<listitem>
1157
-
<simpara>
1158
1137
<link linkend="language.namespaces.faq.quote">Dynamic namespace names (quoted
1159
1138
identifiers) should escape backslash.</link>
1160
1139
</simpara>
...
...
@@ -1168,7 +1147,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1168
1147
<listitem>
1169
1148
<simpara>
1170
1149
<link linkend="language.namespaces.faq.builtinconst">Cannot override special
1171
-
constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD</link>
1150
+
constants &null;, &true; or &false;</link>
1172
1151
</simpara>
1173
1152
</listitem>
1174
1153
</orderedlist>
...
...
@@ -1219,7 +1198,7 @@ $a = new stdClass;
1219
1198
namespace foo;
1220
1199
$a = new \stdClass;
1221
1200
1222
-
function test(\ArrayObject $typehintexample = null) {}
1201
+
function test(\ArrayObject $parameter_type_example = null) {}
1223
1202
1224
1203
$a = \DirectoryIterator::CURRENT_AS_FILEINFO;
1225
1204
...
...
@@ -1246,10 +1225,10 @@ namespace foo;
1246
1225
1247
1226
class MyClass {}
1248
1227
1249
-
// using a class from the current namespace as a type hint
1250
-
function test(MyClass $typehintexample = null) {}
1251
-
// another way to use a class from the current namespace as a type hint
1252
-
function test(\foo\MyClass $typehintexample = null) {}
1228
+
// using a class from the current namespace as a parameter type
1229
+
function test(MyClass $parameter_type_example = null) {}
1230
+
// another way to use a class from the current namespace as a parameter type
1231
+
function test(\foo\MyClass $parameter_type_example = null) {}
1253
1232
1254
1233
// extending a class from the current namespace
1255
1234
class Extended extends MyClass {}
...
...
@@ -1405,7 +1384,7 @@ $b = INI_ALL; // sets $b to value of global constant "INI_ALL"
1405
1384
</para>
1406
1385
</sect2>
1407
1386
<sect2 xml:id="language.namespaces.faq.conflict">
1408
-
<title>Import names cannot conflict with classes defined in the same file.</title>
1387
+
<title>Import names must not conflict with classes defined in the same file.</title>
1409
1388
<para>
1410
1389
The following script combinations are legal:
1411
1390
<informalexample>
...
...
@@ -1492,29 +1471,7 @@ namespace my\stuff\nested {
1492
1471
</informalexample>
1493
1472
</para>
1494
1473
</sect2>
1495
-
<sect2 xml:id="language.namespaces.faq.nofuncconstantuse">
1496
-
<title>Before PHP 5.6 neither functions nor constants can be imported via the <literal>use</literal>
1497
-
statement.</title>
1498
-
<para>
1499
-
Before PHP 5.6 the only elements that are affected by <literal>use</literal> statements are namespaces
1500
-
and class names. In order to shorten a long constant or function, import its containing
1501
-
namespace.
1502
-
<informalexample>
1503
-
<programlisting role="php">
1504
-
<![CDATA[
1505
-
<?php
1506
-
namespace mine;
1507
-
use ultra\long\ns\name;
1508
1474
1509
-
$a = name\CONSTANT;
1510
-
name\func();
1511
-
?>
1512
-
]]>
1513
-
</programlisting>
1514
-
</informalexample>
1515
-
As of PHP 5.6 aliasing or importing function and constant names is allowed.
1516
-
</para>
1517
-
</sect2>
1518
1475
<sect2 xml:id="language.namespaces.faq.quote">
1519
1476
<title>Dynamic namespace names (quoted identifiers) should escape backslash</title>
1520
1477
<para>
...
...
@@ -1563,7 +1520,7 @@ $a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
1563
1520
</para>
1564
1521
</sect2>
1565
1522
<sect2 xml:id="language.namespaces.faq.builtinconst">
1566
-
<title>Cannot override special constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD</title>
1523
+
<title>Cannot override special constants &null;, &true; or &false;</title>
1567
1524
<para>
1568
1525
Any attempt to define a namespaced constant that is a special, built-in constant
1569
1526
results in a fatal error
1570
1527