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>,
...
...
@@ -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
...
...
@@ -42,7 +44,7 @@
42
44
</para>
43
45
<simpara>
44
46
PHP Namespaces provide a way in which to group related classes, interfaces,
45
-
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:
46
48
</simpara>
47
49
<example>
48
50
<title>Namespace syntax example</title>
...
...
@@ -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,14 +87,16 @@ 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
86
-
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.
87
96
</para>
88
97
<para>
89
98
Namespaces are declared using the <literal>namespace</literal>
90
-
keyword. A file containing a namespace must declare the namespace
99
+
keyword. A file containing a namespace must declare the namespace
91
100
at the top of the file before any other code - with one exception: the
92
101
<xref linkend="control-structures.declare" /> keyword.
93
102
<example>
...
...
@@ -99,14 +108,20 @@ namespace MyProject;
99
108
100
109
const CONNECT_OK = 1;
101
110
class Connection { /* ... */ }
102
-
function connect() { /* ... */ }
111
+
function connect() { /* ... */ }
103
112
104
113
?>
105
114
]]>
106
115
</programlisting>
107
116
</example>
117
+
<note>
118
+
<simpara>
119
+
Fully qualified names (i.e. names starting with a backslash) are not allowed in namespace
120
+
declarations, because such constructs are interpreted as relative namespace expressions.
121
+
</simpara>
122
+
</note>
108
123
The only code construct allowed before a namespace declaration is the
109
-
<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,
110
125
no non-PHP code may precede a namespace declaration, including extra whitespace:
111
126
<example>
112
127
<title>Declaring a single namespace</title>
...
...
@@ -127,10 +142,11 @@ namespace MyProject; // fatal error - namespace must be the first statement in t
127
142
</sect1>
128
143
<sect1 xml:id="language.namespaces.nested">
129
144
<title>Declaring sub-namespaces</title>
145
+
<titleabbrev>Sub-namespaces</titleabbrev>
130
146
<?phpdoc print-version-for="namespaces"?>
131
147
<para>
132
148
Much like directories and files, PHP namespaces also contain the ability to specify
133
-
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
134
150
sub-levels:
135
151
<example>
136
152
<title>Declaring a single namespace with hierarchy</title>
...
...
@@ -154,9 +170,10 @@ function connect() { /* ... */ }
154
170
</sect1>
155
171
<sect1 xml:id="language.namespaces.definitionmultiple">
156
172
<title>Defining multiple namespaces in the same file</title>
173
+
<titleabbrev>Defining multiple namespaces in the same file</titleabbrev>
157
174
<?phpdoc print-version-for="namespaces"?>
158
175
<para>
159
-
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
160
177
syntaxes.
161
178
</para>
162
179
<para>
...
...
@@ -211,12 +228,12 @@ function connect() { /* ... */ }
211
228
</para>
212
229
<para>
213
230
It is strongly discouraged as a coding practice to combine multiple namespaces into
214
-
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
215
232
file.
216
233
</para>
217
234
<para>
218
235
To combine global non-namespaced code with namespaced code, only bracketed syntax is
219
-
supported. Global code should be
236
+
supported. Global code should be
220
237
encased in a namespace statement with no namespace name as in:
221
238
<example>
222
239
<title>Declaring multiple namespaces and unnamespaced code</title>
...
...
@@ -269,50 +286,51 @@ echo MyProject\Connection::start();
269
286
</sect1>
270
287
<sect1 xml:id="language.namespaces.basics">
271
288
<title>Using namespaces: Basics</title>
289
+
<titleabbrev>Basics</titleabbrev>
272
290
<?phpdoc print-version-for="namespaces"?>
273
291
<para>
274
292
Before discussing the use of namespaces, it is important to understand how PHP
275
-
knows which namespaced element your code is requesting. A simple analogy can be made
276
-
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
277
295
file system:
278
296
<orderedlist>
279
297
<listitem>
280
298
<simpara>
281
-
Relative file name like <literal>foo.txt</literal>. This resolves to
282
-
<literal>currentdirectory/foo.txt</literal> where currentdirectory is the
283
-
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
284
302
<literal>/home/foo</literal>, the name resolves to <literal>/home/foo/foo.txt</literal>.
285
303
</simpara>
286
304
</listitem>
287
305
<listitem>
288
306
<simpara>
289
-
Relative path name like <literal>subdirectory/foo.txt</literal>. This resolves
307
+
Relative path name like <literal>subdirectory/foo.txt</literal>. This resolves
290
308
to <literal>currentdirectory/subdirectory/foo.txt</literal>.
291
309
</simpara>
292
310
</listitem>
293
311
<listitem>
294
312
<simpara>
295
-
Absolute path name like <literal>/main/foo.txt</literal>. This resolves
313
+
Absolute path name like <literal>/main/foo.txt</literal>. This resolves
296
314
to <literal>/main/foo.txt</literal>.
297
315
</simpara>
298
316
</listitem>
299
317
</orderedlist>
300
-
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
301
319
example, a class name can be referred to in three ways:
302
320
<orderedlist>
303
321
<listitem>
304
322
<simpara>
305
323
Unqualified name, or an unprefixed class name like
306
324
<literal>$a = new foo();</literal> or
307
-
<literal>foo::staticmethod();</literal>. If the current namespace is
325
+
<literal>foo::staticmethod();</literal>. If the current namespace is
308
326
<literal>currentnamespace</literal>, this resolves to
309
-
<literal>currentnamespace\foo</literal>. If
327
+
<literal>currentnamespace\foo</literal>. If
310
328
the code is global, non-namespaced code, this resolves to <literal>foo</literal>.
311
329
</simpara>
312
330
<simpara>
313
331
One caveat: unqualified names for functions and constants will
314
332
resolve to global functions and constants if the namespaced function or constant
315
-
is not defined. See <link linkend="language.namespaces.fallback">Using namespaces:
333
+
is not defined. See <link linkend="language.namespaces.fallback">Using namespaces:
316
334
fallback to global function/constant</link> for details.
317
335
</simpara>
318
336
</listitem>
...
...
@@ -320,9 +338,9 @@ echo MyProject\Connection::start();
320
338
<simpara>
321
339
Qualified name, or a prefixed class name like
322
340
<literal>$a = new subnamespace\foo();</literal> or
323
-
<literal>subnamespace\foo::staticmethod();</literal>. If the current namespace is
341
+
<literal>subnamespace\foo::staticmethod();</literal>. If the current namespace is
324
342
<literal>currentnamespace</literal>, this resolves to
325
-
<literal>currentnamespace\subnamespace\foo</literal>. If
343
+
<literal>currentnamespace\subnamespace\foo</literal>. If
326
344
the code is global, non-namespaced code, this resolves to <literal>subnamespace\foo</literal>.
327
345
</simpara>
328
346
</listitem>
...
...
@@ -330,7 +348,7 @@ echo MyProject\Connection::start();
330
348
<simpara>
331
349
Fully qualified name, or a prefixed name with global prefix operator like
332
350
<literal>$a = new \currentnamespace\foo();</literal> or
333
-
<literal>\currentnamespace\foo::staticmethod();</literal>. This always resolves
351
+
<literal>\currentnamespace\foo::staticmethod();</literal>. This always resolves
334
352
to the literal name specified in the code, <literal>currentnamespace\foo</literal>.
335
353
</simpara>
336
354
</listitem>
...
...
@@ -392,7 +410,7 @@ echo \Foo\Bar\FOO; // resolves to constant Foo\Bar\FOO
392
410
Note that to access any global
393
411
class, function or constant, a fully qualified name can be used, such as
394
412
<function>\strlen</function> or <classname>\Exception</classname> or
395
-
<literal>\INI_ALL</literal>.
413
+
\<constant>INI_ALL</constant>.
396
414
<example>
397
415
<title>Accessing global classes, functions and constants from within a namespace</title>
398
416
<programlisting role="php">
...
...
@@ -415,10 +433,11 @@ $c = new \Exception('error'); // instantiates global class Exception
415
433
</sect1>
416
434
<sect1 xml:id="language.namespaces.dynamic">
417
435
<title>Namespaces and dynamic language features</title>
436
+
<titleabbrev>Namespaces and dynamic language features</titleabbrev>
418
437
<?phpdoc print-version-for="namespaces"?>
419
438
<para>
420
439
PHP's implementation of namespaces is influenced by its dynamic nature as a programming
421
-
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:
422
441
<example>
423
442
<title>Dynamically accessing elements</title>
424
443
<simpara>example1.php:</simpara>
...
...
@@ -470,14 +489,6 @@ function funcname()
470
489
}
471
490
const constname = "namespaced";
472
491
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
492
/* note that if using double quotes, "\\namespacename\\classname" must be used */
482
493
$a = '\namespacename\classname';
483
494
$obj = new $a; // prints namespacename\classname::__construct
...
...
@@ -500,7 +511,8 @@ echo constant('namespacename\constname'), "\n"; // also prints namespaced
500
511
</para>
501
512
</sect1>
502
513
<sect1 xml:id="language.namespaces.nsconstants">
503
-
<title>namespace keyword and __NAMESPACE__ constant</title>
514
+
<title>The namespace keyword and __NAMESPACE__ magic constant</title>
515
+
<titleabbrev>namespace keyword and __NAMESPACE__</titleabbrev>
504
516
<?phpdoc print-version-for="namespaces"?>
505
517
<para>
506
518
PHP supports two ways of abstractly accessing elements within the current namespace,
...
...
@@ -509,7 +521,7 @@ echo constant('namespacename\constname'), "\n"; // also prints namespaced
509
521
</para>
510
522
<para>
511
523
The value of <constant>__NAMESPACE__</constant> is a string that contains the current
512
-
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.
513
525
<example>
514
526
<title>__NAMESPACE__ example, namespaced code</title>
515
527
<programlisting role="php">
...
...
@@ -554,7 +566,7 @@ function get($classname)
554
566
</para>
555
567
<para>
556
568
The <literal>namespace</literal> keyword can be used to explicitly request
557
-
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
558
570
equivalent of the <literal>self</literal> operator for classes.
559
571
<example>
560
572
<title>the namespace operator, inside a namespace</title>
...
...
@@ -594,23 +606,22 @@ $b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
594
606
</example>
595
607
</para>
596
608
</sect1>
609
+
597
610
<sect1 xml:id="language.namespaces.importing">
598
611
<title>Using namespaces: Aliasing/Importing</title>
612
+
<titleabbrev>Aliasing and Importing</titleabbrev>
599
613
<?phpdoc print-version-for="namespaces"?>
600
614
<para>
601
615
The ability to refer to an external fully qualified name with an alias, or importing,
602
-
is an important feature of namespaces. This is similar to the
616
+
is an important feature of namespaces. This is similar to the
603
617
ability of unix-based filesystems to create symbolic links to a file or to a directory.
604
618
</para>
605
619
<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.
620
+
PHP can alias(/import) constants, functions, classes, interfaces, traits, enums and namespaces.
610
621
</para>
611
622
<para>
612
-
In PHP, aliasing is accomplished with the <literal>use</literal> operator. Here
613
-
is an example showing all 5 kinds of importing:
623
+
Aliasing is accomplished with the <literal>use</literal> operator.
624
+
Here is an example showing all 5 kinds of importing:
614
625
<example>
615
626
<title>importing/aliasing with the use operator</title>
616
627
<programlisting role="php">
...
...
@@ -625,13 +636,13 @@ use My\Full\NSname;
625
636
// importing a global class
626
637
use ArrayObject;
627
638
628
-
// importing a function (PHP 5.6+)
639
+
// importing a function
629
640
use function My\Full\functionName;
630
641
631
-
// aliasing a function (PHP 5.6+)
642
+
// aliasing a function
632
643
use function My\Full\functionName as func;
633
644
634
-
// importing a constant (PHP 5.6+)
645
+
// importing a constant
635
646
use const My\Full\CONSTANT;
636
647
637
648
$obj = new namespace\Another; // instantiates object of class foo\Another
...
...
@@ -687,7 +698,7 @@ $obj = new $a; // instantiates object of class Another
687
698
</example>
688
699
</para>
689
700
<para>
690
-
In addition, importing only affects unqualified and qualified names. Fully qualified
701
+
In addition, importing only affects unqualified and qualified names. Fully qualified
691
702
names are absolute, and unaffected by imports.
692
703
<example>
693
704
<title>Importing and fully qualified names</title>
...
...
@@ -723,11 +734,11 @@ $obj = new \Another\thing; // instantiates object of class Another\thing
723
734
<?php
724
735
namespace Languages;
725
736
726
-
class Greenlandic
737
+
function toGreenlandic()
727
738
{
728
739
use Languages\Danish;
729
740
730
-
...
741
+
// ...
731
742
}
732
743
?>
733
744
]]>
...
...
@@ -741,9 +752,42 @@ class Greenlandic
741
752
</para>
742
753
</note>
743
754
</sect2>
755
+
<sect2 xml:id="language.namespaces.importing.group">
756
+
<title>Group <literal>use</literal> declarations</title>
757
+
<para>
758
+
Classes, functions and constants being imported from
759
+
the same &namespace; can be grouped together in a single &use.namespace;
760
+
statement.
761
+
</para>
762
+
<informalexample>
763
+
<programlisting role="php">
764
+
<![CDATA[
765
+
<?php
766
+
767
+
use some\namespace\ClassA;
768
+
use some\namespace\ClassB;
769
+
use some\namespace\ClassC as C;
770
+
771
+
use function some\namespace\fn_a;
772
+
use function some\namespace\fn_b;
773
+
use function some\namespace\fn_c;
774
+
775
+
use const some\namespace\ConstA;
776
+
use const some\namespace\ConstB;
777
+
use const some\namespace\ConstC;
778
+
779
+
// is equivalent to the following groupped use declaration
780
+
use some\namespace\{ClassA, ClassB, ClassC as C};
781
+
use function some\namespace\{fn_a, fn_b, fn_c};
782
+
use const some\namespace\{ConstA, ConstB, ConstC};
783
+
]]>
784
+
</programlisting>
785
+
</informalexample>
786
+
</sect2>
744
787
</sect1>
745
788
<sect1 xml:id="language.namespaces.global">
746
789
<title>Global space</title>
790
+
<titleabbrev>Global space</titleabbrev>
747
791
<?phpdoc print-version-for="namespaces"?>
748
792
<para>
749
793
Without any namespace definition, all class and function definitions are
...
...
@@ -771,12 +815,13 @@ function fopen() {
771
815
</para>
772
816
</sect1>
773
817
<sect1 xml:id="language.namespaces.fallback">
774
-
<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>
775
820
<?phpdoc print-version-for="namespaces"?>
776
821
<para>
777
822
Inside a namespace, when PHP encounters an unqualified Name in a class name, function or
778
-
constant context, it resolves these with different priorities. Class names always
779
-
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
780
825
user classes, one must refer to them with their fully qualified Name as in:
781
826
<example>
782
827
<title>Accessing global classes inside a namespace</title>
...
...
@@ -829,6 +874,7 @@ if (is_array('hi')) { // prints "is not array"
829
874
830
875
<sect1 xml:id="language.namespaces.rules">
831
876
<title>Name resolution rules</title>
877
+
<titleabbrev>Name resolution rules</titleabbrev>
832
878
<?phpdoc print-version-for="namespaces"?>
833
879
<para>
834
880
For the purposes of these resolution rules, here are some important definitions:
...
...
@@ -860,6 +906,15 @@ if (is_array('hi')) { // prints "is not array"
860
906
</para>
861
907
</listitem>
862
908
</varlistentry>
909
+
<varlistentry>
910
+
<term>Relative name</term>
911
+
<listitem>
912
+
<para>
913
+
This is an identifier starting with <literal>namespace</literal>, such as
914
+
<literal>namespace\Foo\Bar</literal>.
915
+
</para>
916
+
</listitem>
917
+
</varlistentry>
863
918
</variablelist>
864
919
</para>
865
920
<para>
...
...
@@ -867,40 +922,58 @@ if (is_array('hi')) { // prints "is not array"
867
922
<orderedlist>
868
923
<listitem>
869
924
<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>.
925
+
Fully qualified names always resolve to the name without leading namespace separator.
926
+
For instance <literal>\A\B</literal> resolves to <literal>A\B</literal>.
927
+
</simpara>
928
+
</listitem>
929
+
<listitem>
930
+
<simpara>
931
+
Relative names always resolve to the name with <literal>namespace</literal> replaced by
932
+
the current namespace. If the name occurs in the global namespace, the
933
+
<literal>namespace\</literal> prefix is stripped. For example <literal>namespace\A</literal>
934
+
inside namespace <literal>X\Y</literal> resolves to <literal>X\Y\A</literal>. The same name
935
+
inside the global namespace resolves to <literal>A</literal>.
936
+
</simpara>
937
+
</listitem>
938
+
<listitem>
939
+
<simpara>
940
+
For qualified names the first segment of the name is translated according to the current
941
+
class/namespace import table. For example, if the namespace <literal>A\B\C</literal> is
942
+
imported as <literal>C</literal>, the name <literal>C\D\E</literal> is translated to
943
+
<literal>A\B\C\D\E</literal>.
872
944
</simpara>
873
945
</listitem>
874
946
<listitem>
875
947
<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>.
948
+
For qualified names, if no import rule applies, the current namespace is prepended to the
949
+
name. For example, the name <literal>C\D\E</literal> inside namespace <literal>A\B</literal>,
950
+
resolves to <literal>A\B\C\D\E</literal>.
881
951
</simpara>
882
952
</listitem>
883
953
<listitem>
884
954
<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>.
955
+
For unqualified names, the name is translated according to the current import table for the
956
+
respective symbol type. This means that class-like names are translated according to the
957
+
class/namespace import table, function names according to the function import table and
958
+
constants according to the constant import table. For example, after
959
+
<literal>use A\B\C;</literal> a usage such as <literal>new C()</literal> resolves to the name
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>.
889
962
</simpara>
890
963
</listitem>
891
964
<listitem>
892
965
<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>.
966
+
For unqualified names, if no import rule applies and the name refers to a class-like symbol,
967
+
the current namespace is prepended. For example <literal>new C()</literal> inside namespace
968
+
<literal>A\B</literal> resolves to name <literal>A\B\C</literal>.
897
969
</simpara>
898
970
</listitem>
899
971
<listitem>
900
972
<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:
973
+
For unqualified names, if no import rule applies and the name refers to a function or constant
974
+
and the code is outside the global namespace, the name is resolved at runtime.
975
+
Assuming the code is in namespace <literal>A\B</literal>, here is how a call to function
976
+
<literal>foo()</literal> is resolved:
904
977
</simpara>
905
978
<orderedlist>
906
979
<listitem>
...
...
@@ -917,48 +990,6 @@ if (is_array('hi')) { // prints "is not array"
917
990
</listitem>
918
991
</orderedlist>
919
992
</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
993
</orderedlist>
963
994
</para>
964
995
<example>
...
...
@@ -1030,6 +1061,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1030
1061
</sect1>
1031
1062
<sect1 xml:id="language.namespaces.faq">
1032
1063
<title>FAQ: things you need to know about namespaces</title>
1064
+
<titleabbrev>FAQ</titleabbrev>
1033
1065
<?phpdoc print-version-for="namespaces"?>
1034
1066
<para>
1035
1067
This FAQ is split into two sections: common questions, and some specifics of
...
...
@@ -1091,7 +1123,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1091
1123
<orderedlist>
1092
1124
<listitem>
1093
1125
<simpara>
1094
-
<link linkend="language.namespaces.faq.conflict">Import names cannot conflict with
1126
+
<link linkend="language.namespaces.faq.conflict">Import names must not conflict with
1095
1127
classes defined in the same file.</link>
1096
1128
</simpara>
1097
1129
</listitem>
...
...
@@ -1101,13 +1133,6 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1101
1133
</link>
1102
1134
</simpara>
1103
1135
</listitem>
1104
-
<listitem>
1105
-
<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
1136
<listitem>
1112
1137
<simpara>
1113
1138
<link linkend="language.namespaces.faq.quote">Dynamic namespace names (quoted
...
...
@@ -1123,7 +1148,7 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1123
1148
<listitem>
1124
1149
<simpara>
1125
1150
<link linkend="language.namespaces.faq.builtinconst">Cannot override special
1126
-
constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD</link>
1151
+
constants &null;, &true; or &false;</link>
1127
1152
</simpara>
1128
1153
</listitem>
1129
1154
</orderedlist>
...
...
@@ -1131,8 +1156,8 @@ A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
1131
1156
<sect2 xml:id="language.namespaces.faq.shouldicare">
1132
1157
<title>If I don't use namespaces, should I care about any of this?</title>
1133
1158
<para>
1134
-
No. Namespaces do not affect any existing code in any way, or any
1135
-
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
1136
1161
write this code if you wish:
1137
1162
</para>
1138
1163
<para>
...
...
@@ -1174,7 +1199,7 @@ $a = new stdClass;
1174
1199
namespace foo;
1175
1200
$a = new \stdClass;
1176
1201
1177
-
function test(\ArrayObject $typehintexample = null) {}
1202
+
function test(\ArrayObject $parameter_type_example = null) {}
1178
1203
1179
1204
$a = \DirectoryIterator::CURRENT_AS_FILEINFO;
1180
1205
...
...
@@ -1201,10 +1226,10 @@ namespace foo;
1201
1226
1202
1227
class MyClass {}
1203
1228
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) {}
1229
+
// using a class from the current namespace as a parameter type
1230
+
function test(MyClass $parameter_type_example = null) {}
1231
+
// another way to use a class from the current namespace as a parameter type
1232
+
function test(\foo\MyClass $parameter_type_example = null) {}
1208
1233
1209
1234
// extending a class from the current namespace
1210
1235
class Extended extends MyClass {}
...
...
@@ -1360,7 +1385,7 @@ $b = INI_ALL; // sets $b to value of global constant "INI_ALL"
1360
1385
</para>
1361
1386
</sect2>
1362
1387
<sect2 xml:id="language.namespaces.faq.conflict">
1363
-
<title>Import names cannot conflict with classes defined in the same file.</title>
1388
+
<title>Import names must not conflict with classes defined in the same file.</title>
1364
1389
<para>
1365
1390
The following script combinations are legal:
1366
1391
<informalexample>
...
...
@@ -1400,7 +1425,7 @@ $a = new MyClass; // instantiates class "thing" from namespace another
1400
1425
<para>
1401
1426
There is no name conflict, even though the class <literal>MyClass</literal> exists
1402
1427
within the <literal>my\stuff</literal> namespace, because the MyClass definition is
1403
-
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
1404
1429
because MyClass is defined in the same file as the use statement.
1405
1430
<informalexample>
1406
1431
<programlisting role="php">
...
...
@@ -1447,33 +1472,12 @@ namespace my\stuff\nested {
1447
1472
</informalexample>
1448
1473
</para>
1449
1474
</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
1475
1464
-
$a = name\CONSTANT;
1465
-
name\func();
1466
-
?>
1467
-
]]>
1468
-
</programlisting>
1469
-
</informalexample>
1470
-
</para>
1471
-
</sect2>
1472
1476
<sect2 xml:id="language.namespaces.faq.quote">
1473
1477
<title>Dynamic namespace names (quoted identifiers) should escape backslash</title>
1474
1478
<para>
1475
1479
It is very important to realize that because the backslash is used as an escape character
1476
-
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
1477
1481
there is a risk of unintended consequences:
1478
1482
<example>
1479
1483
<title>Dangers of using namespaced names inside a double-quoted string</title>
...
...
@@ -1498,7 +1502,7 @@ $obj = new $a;
1498
1502
<para>
1499
1503
Any undefined constant that is unqualified like <literal>FOO</literal> will
1500
1504
produce a notice explaining that PHP assumed <literal>FOO</literal> was the value
1501
-
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
1502
1506
backslash will produce a fatal error if not found.
1503
1507
<example>
1504
1508
<title>Undefined constants</title>
...
...
@@ -1517,7 +1521,7 @@ $a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
1517
1521
</para>
1518
1522
</sect2>
1519
1523
<sect2 xml:id="language.namespaces.faq.builtinconst">
1520
-
<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>
1521
1525
<para>
1522
1526
Any attempt to define a namespaced constant that is a special, built-in constant
1523
1527
results in a fatal error
1524
1528