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,6 +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>
23
+
22
24
<simpara>
23
25
In the PHP world, namespaces are designed to solve two problems that authors
24
26
of libraries and applications encounter when creating re-usable code elements
...
...
@@ -69,10 +71,15 @@ echo constant($d); // see "Namespaces and dynamic language features" section
69
71
]]>
70
72
</programlisting>
71
73
</example>
74
+
<note>
75
+
<simpara>
76
+
Namespace names are case-insensitive.
77
+
</simpara>
78
+
</note>
72
79
<note>
73
80
<para>
74
-
Namespace names <literal>PHP</literal> and <literal>php</literal>, and compound names starting
75
-
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
76
83
and should not be used in the userspace code.
77
84
</para>
78
85
</note>
...
...
@@ -80,6 +87,7 @@ echo constant($d); // see "Namespaces and dynamic language features" section
80
87
81
88
<sect1 xml:id="language.namespaces.definition">
82
89
<title>Defining namespaces</title>
90
+
<titleabbrev>Namespaces</titleabbrev>
83
91
<?phpdoc print-version-for="namespaces"?>
84
92
<para>
85
93
Although any valid PHP code can be contained within a namespace, only the following
...
...
@@ -99,12 +107,18 @@ namespace MyProject;
99
107
100
108
const CONNECT_OK = 1;
101
109
class Connection { /* ... */ }
102
-
function connect() { /* ... */ }
110
+
function connect() { /* ... */ }
103
111
104
112
?>
105
113
]]>
106
114
</programlisting>
107
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>
108
122
The only code construct allowed before a namespace declaration is the
109
123
<literal>declare</literal> statement, for defining encoding of a source file. In addition,
110
124
no non-PHP code may precede a namespace declaration, including extra whitespace:
...
...
@@ -127,6 +141,7 @@ namespace MyProject; // fatal error - namespace must be the first statement in t
127
141
</sect1>
128
142
<sect1 xml:id="language.namespaces.nested">
129
143
<title>Declaring sub-namespaces</title>
144
+
<titleabbrev>Sub-namespaces</titleabbrev>
130
145
<?phpdoc print-version-for="namespaces"?>
131
146
<para>
132
147
Much like directories and files, PHP namespaces also contain the ability to specify
...
...
@@ -154,6 +169,7 @@ function connect() { /* ... */ }
154
169
</sect1>
155
170
<sect1 xml:id="language.namespaces.definitionmultiple">
156
171
<title>Defining multiple namespaces in the same file</title>
172
+
<titleabbrev>Defining multiple namespaces in the same file</titleabbrev>
157
173
<?phpdoc print-version-for="namespaces"?>
158
174
<para>
159
175
Multiple namespaces may also be declared in the same file. There are two allowed
...
...
@@ -269,6 +285,7 @@ echo MyProject\Connection::start();
269
285
</sect1>
270
286
<sect1 xml:id="language.namespaces.basics">
271
287
<title>Using namespaces: Basics</title>
288
+
<titleabbrev>Basics</titleabbrev>
272
289
<?phpdoc print-version-for="namespaces"?>
273
290
<para>
274
291
Before discussing the use of namespaces, it is important to understand how PHP
...
...
@@ -279,7 +296,7 @@ echo MyProject\Connection::start();
279
296
<listitem>
280
297
<simpara>
281
298
Relative file name like <literal>foo.txt</literal>. This resolves to
282
-
<literal>currentdirectory/foo.txt</literal> where currentdirectory is the
299
+
<literal>currentdirectory/foo.txt</literal> where <literal>currentdirectory</literal> is the
283
300
directory currently occupied. So if the current directory is
284
301
<literal>/home/foo</literal>, the name resolves to <literal>/home/foo/foo.txt</literal>.
285
302
</simpara>
...
...
@@ -392,7 +409,7 @@ echo \Foo\Bar\FOO; // resolves to constant Foo\Bar\FOO
392
409
Note that to access any global
393
410
class, function or constant, a fully qualified name can be used, such as
394
411
<function>\strlen</function> or <classname>\Exception</classname> or
395
-
<literal>\INI_ALL</literal>.
412
+
\<constant>INI_ALL</constant>.
396
413
<example>
397
414
<title>Accessing global classes, functions and constants from within a namespace</title>
398
415
<programlisting role="php">
...
...
@@ -415,6 +432,7 @@ $c = new \Exception('error'); // instantiates global class Exception
415
432
</sect1>
416
433
<sect1 xml:id="language.namespaces.dynamic">
417
434
<title>Namespaces and dynamic language features</title>
435
+
<titleabbrev>Namespaces and dynamic language features</titleabbrev>
418
436
<?phpdoc print-version-for="namespaces"?>
419
437
<para>
420
438
PHP's implementation of namespaces is influenced by its dynamic nature as a programming
...
...
@@ -470,14 +488,6 @@ function funcname()
470
488
}
471
489
const constname = "namespaced";
472
490
473
-
include 'example1.php';
474
-
475
-
$a = 'classname';
476
-
$obj = new $a; // prints classname::__construct
477
-
$b = 'funcname';
478
-
$b(); // prints funcname
479
-
echo constant('constname'), "\n"; // prints global
480
-
481
491
/* note that if using double quotes, "\\namespacename\\classname" must be used */
482
492
$a = '\namespacename\classname';
483
493
$obj = new $a; // prints namespacename\classname::__construct
...
...
@@ -500,7 +510,8 @@ echo constant('namespacename\constname'), "\n"; // also prints namespaced
500
510
</para>
501
511
</sect1>
502
512
<sect1 xml:id="language.namespaces.nsconstants">
503
-
<title>namespace keyword and __NAMESPACE__ constant</title>
513
+
<title>The namespace keyword and __NAMESPACE__ magic constant</title>
514
+
<titleabbrev>namespace keyword and __NAMESPACE__</titleabbrev>
504
515
<?phpdoc print-version-for="namespaces"?>
505
516
<para>
506
517
PHP supports two ways of abstractly accessing elements within the current namespace,
...
...
@@ -594,8 +605,10 @@ $b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
594
605
</example>
595
606
</para>
596
607
</sect1>
608
+
597
609
<sect1 xml:id="language.namespaces.importing">
598
610
<title>Using namespaces: Aliasing/Importing</title>
611
+
<titleabbrev>Aliasing and Importing</titleabbrev>
599
612
<?phpdoc print-version-for="namespaces"?>
600
613
<para>
601
614
The ability to refer to an external fully qualified name with an alias, or importing,
...
...
@@ -603,14 +616,11 @@ $b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
603
616
ability of unix-based filesystems to create symbolic links to a file or to a directory.
604
617
</para>
605
618
<para>
606
-
All versions of PHP that support namespaces support three kinds of aliasing
607
-
or importing: aliasing a class name, aliasing an interface name, and
608
-
aliasing a namespace name. PHP 5.6+ also allows aliasing or importing
609
-
function and constant names.
619
+
PHP can alias(/import) constants, functions, classes, interfaces, traits, enums and namespaces.
610
620
</para>
611
621
<para>
612
-
In PHP, aliasing is accomplished with the <literal>use</literal> operator. Here
613
-
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:
614
624
<example>
615
625
<title>importing/aliasing with the use operator</title>
616
626
<programlisting role="php">
...
...
@@ -625,13 +635,13 @@ use My\Full\NSname;
625
635
// importing a global class
626
636
use ArrayObject;
627
637
628
-
// importing a function (PHP 5.6+)
638
+
// importing a function
629
639
use function My\Full\functionName;
630
640
631
-
// aliasing a function (PHP 5.6+)
641
+
// aliasing a function
632
642
use function My\Full\functionName as func;
633
643
634
-
// importing a constant (PHP 5.6+)
644
+
// importing a constant
635
645
use const My\Full\CONSTANT;
636
646
637
647
$obj = new namespace\Another; // instantiates object of class foo\Another
...
...
@@ -723,11 +733,11 @@ $obj = new \Another\thing; // instantiates object of class Another\thing
723
733
<?php
724
734
namespace Languages;
725
735
726
-
class Greenlandic
736
+
function toGreenlandic()
727
737
{
728
738
use Languages\Danish;
729
739
730
-
...
740
+
// ...
731
741
}
732
742
?>
733
743
]]>
...
...
@@ -741,9 +751,42 @@ class Greenlandic
741
751
</para>
742
752
</note>
743
753
</sect2>
754
+
<sect2 xml:id="language.namespaces.importing.group">
755
+
<title>Group <literal>use</literal> declarations</title>
756
+
<para>
757
+
Classes, functions and constants being imported from
758
+
the same &namespace; can be grouped together in a single &use.namespace;
759
+
statement.
760
+
</para>
761
+
<informalexample>
762
+
<programlisting role="php">
763
+
<![CDATA[
764
+
<?php
765
+
766
+
use some\namespace\ClassA;
767
+
use some\namespace\ClassB;
768
+
use some\namespace\ClassC as C;
769
+
770
+
use function some\namespace\fn_a;
771
+
use function some\namespace\fn_b;
772
+
use function some\namespace\fn_c;
773
+
774
+
use const some\namespace\ConstA;
775
+
use const some\namespace\ConstB;
776
+
use const some\namespace\ConstC;
777
+
778
+
// is equivalent to the following groupped use declaration
779
+
use some\namespace\{ClassA, ClassB, ClassC as C};
780
+
use function some\namespace\{fn_a, fn_b, fn_c};
781
+
use const some\namespace\{ConstA, ConstB, ConstC};
782
+
]]>
783
+
</programlisting>
784
+
</informalexample>
785
+
</sect2>
744
786
</sect1>
745
787
<sect1 xml:id="language.namespaces.global">
746
788
<title>Global space</title>
789
+
<titleabbrev>Global space</titleabbrev>
747
790
<?phpdoc print-version-for="namespaces"?>
748
791
<para>
749
792
Without any namespace definition, all class and function definitions are
...
...
@@ -771,7 +814,8 @@ function fopen() {
771
814
</para>
772
815
</sect1>
773
816
<sect1 xml:id="language.namespaces.fallback">
774
-
<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>
775
819
<?phpdoc print-version-for="namespaces"?>
776
820
<para>
777
821
Inside a namespace, when PHP encounters an unqualified Name in a class name, function or
...
...
@@ -829,6 +873,7 @@ if (is_array('hi')) { // prints "is not array"
829
873
830
874
<sect1 xml:id="language.namespaces.rules">
831
875
<title>Name resolution rules</title>
876
+
<titleabbrev>Name resolution rules</titleabbrev>
832
877
<?phpdoc print-version-for="namespaces"?>
833
878
<para>
834
879
For the purposes of these resolution rules, here are some important definitions:
...
...
@@ -860,6 +905,15 @@ if (is_array('hi')) { // prints "is not array"
860
905
</para>
861
906
</listitem>
862
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>
863
917
</variablelist>
864
918
</para>
865
919
<para>
...
...
@@ -867,40 +921,58 @@ if (is_array('hi')) { // prints "is not array"
867
921
<orderedlist>
868
922
<listitem>
869
923
<simpara>
870
-
Calls to fully qualified functions, classes or constants are resolved at compile-time.
871
-
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>.
935
+
</simpara>
936
+
</listitem>
937
+
<listitem>
938
+
<simpara>
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>.
872
943
</simpara>
873
944
</listitem>
874
945
<listitem>
875
946
<simpara>
876
-
All unqualified and qualified names (not fully qualified names) are translated during
877
-
compilation according to current
878
-
import rules. For example, if the namespace <literal>A\B\C</literal> is imported as
879
-
<literal>C</literal>, a call to
880
-
<literal>C\D\e()</literal> 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>.
881
950
</simpara>
882
951
</listitem>
883
952
<listitem>
884
953
<simpara>
885
-
Inside a namespace, all qualified names not translated according to import
886
-
rules have the current namespace prepended. For example, if a call
887
-
to <literal>C\D\e()</literal> is performed within namespace <literal>A\B</literal>,
888
-
it is translated to <literal>A\B\C\D\e()</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>.
889
961
</simpara>
890
962
</listitem>
891
963
<listitem>
892
964
<simpara>
893
-
Unqualified class names are translated during compilation according to current
894
-
import rules (full name substituted for short imported name). In example, if
895
-
the namespace <literal>A\B\C</literal> is imported as C, <literal>new C()</literal> is
896
-
translated to <literal>new A\B\C()</literal>.
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>.
897
968
</simpara>
898
969
</listitem>
899
970
<listitem>
900
971
<simpara>
901
-
Inside namespace (say A\B), calls to unqualified functions are resolved at run-time.
902
-
Here is how a
903
-
call to function <literal>foo()</literal> is resolved:
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:
904
976
</simpara>
905
977
<orderedlist>
906
978
<listitem>
...
...
@@ -917,48 +989,6 @@ if (is_array('hi')) { // prints "is not array"
917
989
</listitem>
918
990
</orderedlist>
919
991
</listitem>
920
-
<listitem>
921
-
<simpara>
922
-
Inside namespace (say <literal>A\B</literal>), calls to unqualified or qualified
923
-
class names (not fully qualified class names)
924
-
are resolved at run-time. Here is how a call to
925
-
<literal>new C()</literal> or <literal>new D\E()</literal> is resolved.
926
-
For <literal> new C()</literal>:
927
-
</simpara>
928
-
<orderedlist>
929
-
<listitem>
930
-
<simpara>
931
-
It looks for a class from the current namespace:
932
-
<literal>A\B\C</literal>.
933
-
</simpara>
934
-
</listitem>
935
-
<listitem>
936
-
<simpara>
937
-
It attempts to autoload <literal>A\B\C</literal>.
938
-
</simpara>
939
-
</listitem>
940
-
</orderedlist>
941
-
<simpara>
942
-
For <literal> new D\E()</literal>:
943
-
</simpara>
944
-
<orderedlist>
945
-
<listitem>
946
-
<simpara>
947
-
It looks for a class by prepending the current namespace:
948
-
<literal>A\B\D\E</literal>.
949
-
</simpara>
950
-
</listitem>
951
-
<listitem>
952
-
<simpara>
953
-
It attempts to autoload <literal>A\B\D\E</literal>.
954
-
</simpara>
955
-
</listitem>
956
-
</orderedlist>
957
-
<simpara>
958
-
To reference any global class in the global namespace,
959
-
its fully qualified name <literal>new \C()</literal> must be used.
960
-
</simpara>
961
-
</listitem>
962
992
</orderedlist>
963
993
</para>
964
994
<example>
...
...
@@ -1030,6 +1060,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1030
1060
</sect1>
1031
1061
<sect1 xml:id="language.namespaces.faq">
1032
1062
<title>FAQ: things you need to know about namespaces</title>
1063
+
<titleabbrev>FAQ</titleabbrev>
1033
1064
<?phpdoc print-version-for="namespaces"?>
1034
1065
<para>
1035
1066
This FAQ is split into two sections: common questions, and some specifics of
...
...
@@ -1091,7 +1122,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1091
1122
<orderedlist>
1092
1123
<listitem>
1093
1124
<simpara>
1094
-
<link linkend="language.namespaces.faq.conflict">Import names cannot conflict with
1125
+
<link linkend="language.namespaces.faq.conflict">Import names must not conflict with
1095
1126
classes defined in the same file.</link>
1096
1127
</simpara>
1097
1128
</listitem>
...
...
@@ -1103,13 +1134,6 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1103
1134
</listitem>
1104
1135
<listitem>
1105
1136
<simpara>
1106
-
<link linkend="language.namespaces.faq.nofuncconstantuse">Neither functions nor
1107
-
constants can be imported via the <literal>use</literal>
1108
-
statement.</link>
1109
-
</simpara>
1110
-
</listitem>
1111
-
<listitem>
1112
-
<simpara>
1113
1137
<link linkend="language.namespaces.faq.quote">Dynamic namespace names (quoted
1114
1138
identifiers) should escape backslash.</link>
1115
1139
</simpara>
...
...
@@ -1123,7 +1147,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1123
1147
<listitem>
1124
1148
<simpara>
1125
1149
<link linkend="language.namespaces.faq.builtinconst">Cannot override special
1126
-
constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD</link>
1150
+
constants &null;, &true; or &false;</link>
1127
1151
</simpara>
1128
1152
</listitem>
1129
1153
</orderedlist>
...
...
@@ -1174,7 +1198,7 @@ $a = new stdClass;
1174
1198
namespace foo;
1175
1199
$a = new \stdClass;
1176
1200
1177
-
function test(\ArrayObject $typehintexample = null) {}
1201
+
function test(\ArrayObject $parameter_type_example = null) {}
1178
1202
1179
1203
$a = \DirectoryIterator::CURRENT_AS_FILEINFO;
1180
1204
...
...
@@ -1201,10 +1225,10 @@ namespace foo;
1201
1225
1202
1226
class MyClass {}
1203
1227
1204
-
// using a class from the current namespace as a type hint
1205
-
function test(MyClass $typehintexample = null) {}
1206
-
// another way to use a class from the current namespace as a type hint
1207
-
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) {}
1208
1232
1209
1233
// extending a class from the current namespace
1210
1234
class Extended extends MyClass {}
...
...
@@ -1360,7 +1384,7 @@ $b = INI_ALL; // sets $b to value of global constant "INI_ALL"
1360
1384
</para>
1361
1385
</sect2>
1362
1386
<sect2 xml:id="language.namespaces.faq.conflict">
1363
-
<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>
1364
1388
<para>
1365
1389
The following script combinations are legal:
1366
1390
<informalexample>
...
...
@@ -1447,28 +1471,7 @@ namespace my\stuff\nested {
1447
1471
</informalexample>
1448
1472
</para>
1449
1473
</sect2>
1450
-
<sect2 xml:id="language.namespaces.faq.nofuncconstantuse">
1451
-
<title>Neither functions nor constants can be imported via the <literal>use</literal>
1452
-
statement.</title>
1453
-
<para>
1454
-
The only elements that are affected by <literal>use</literal> statements are namespaces
1455
-
and class names. In order to shorten a long constant or function, import its containing
1456
-
namespace
1457
-
<informalexample>
1458
-
<programlisting role="php">
1459
-
<![CDATA[
1460
-
<?php
1461
-
namespace mine;
1462
-
use ultra\long\ns\name;
1463
1474
1464
-
$a = name\CONSTANT;
1465
-
name\func();
1466
-
?>
1467
-
]]>
1468
-
</programlisting>
1469
-
</informalexample>
1470
-
</para>
1471
-
</sect2>
1472
1475
<sect2 xml:id="language.namespaces.faq.quote">
1473
1476
<title>Dynamic namespace names (quoted identifiers) should escape backslash</title>
1474
1477
<para>
...
...
@@ -1517,7 +1520,7 @@ $a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
1517
1520
</para>
1518
1521
</sect2>
1519
1522
<sect2 xml:id="language.namespaces.faq.builtinconst">
1520
-
<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>
1521
1524
<para>
1522
1525
Any attempt to define a namespaced constant that is a special, built-in constant
1523
1526
results in a fatal error
1524
1527