Skip to content

Commit 161dde4

Browse files
Girgiascmb69
Girgias
and
cmb69
authored
Rewrite type section (#1726)
This commit rewrites the whole type section to (hopefully) be better structured and future proof for further additions to the type system. * Each type now gets their individual page instead of being shoved in the type declaration page. * A type system page is added which describes PHP's type system, regardless if it is possible to declare the type in userland or not. Therefore, the type declaration page only has information related to writing type declarations in userland. * The description of strict_type and the type coercion is moved into the type juggling page. * Remove outdated information in string implementation section * Add paragraph about using non string in string context can throw Co-authored-by: Christoph M. Becker <[email protected]>
1 parent b6f7d2d commit 161dde4

17 files changed

+1023
-837
lines changed

‎appendices/migration81/new-features.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,12 +105,12 @@ $arr2 = [...$arr1, 'c' => 'd']; //[1, 'a' => 'b', 'c' => 'd']
105105
<title>Intersection Types</title>
106106

107107
<para>
108-
Support for <link linkend="language.types.declarations.composite.intersection">intersection types</link> has been added.
108+
Support for <link linkend="language.types.type-system.composite.intersection">intersection types</link> has been added.
109109
<!-- RFC: https://wiki.php.net/rfc/pure-intersection-types -->
110110
</para>
111111
<caution>
112112
<simpara>
113-
<link linkend="language.types.declarations.composite.intersection">
113+
<link linkend="language.types.type-system.composite.intersection">
114114
Intersection types</link> cannot be used together with
115115
<link linkend="language.types.declarations.composite.union">
116116
union types</link>

‎language/oop5/properties.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -222,7 +222,7 @@ $test->prop = "foobar";
222222
<note>
223223
<para>
224224
The readonly modifier can only be applied to <link linkend="language.oop5.properties.typed-properties">typed properties</link>.
225-
A readonly property without type constraints can be created using the <xref linkend="language.types.declarations.mixed" /> type.
225+
A readonly property without type constraints can be created using the <xref linkend="language.types.mixed"/> type.
226226
</para>
227227
</note>
228228
<note>

‎language/oop5/variance.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@
1919
<listitem>
2020
<simpara>
2121
A type is removed from a
22-
<link linkend="language.types.declarations.composite.union">union type</link>
22+
<link linkend="language.types.type-system.composite.union">union type</link>
2323
</simpara>
2424
</listitem>
2525
<listitem>
2626
<simpara>
2727
A type is added to an
28-
<link linkend="language.types.declarations.composite.intersection">intersection type</link>
28+
<link linkend="language.types.type-system.composite.intersection">intersection type</link>
2929
</simpara>
3030
</listitem>
3131
<listitem>

‎language/types.xml

Lines changed: 80 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -5,177 +5,136 @@
55

66
<sect1 xml:id="language.types.intro">
77
<title>Introduction</title>
8-
9-
<simpara>
10-
PHP supports ten primitive types.
11-
</simpara>
12-
8+
139
<para>
14-
Four scalar types:
10+
Every single expression in PHP has one of the following
11+
built-in types depending on its value:
12+
<itemizedlist>
13+
<listitem><simpara><type>null</type></simpara></listitem>
14+
<listitem><simpara><type>bool</type></simpara></listitem>
15+
<listitem><simpara><type>int</type></simpara></listitem>
16+
<listitem><simpara><type>float</type> (floating-point number)</simpara></listitem>
17+
<listitem><simpara><type>string</type></simpara></listitem>
18+
<listitem><simpara><type>array</type></simpara></listitem>
19+
<listitem><simpara><type>object</type></simpara></listitem>
20+
<listitem><simpara><type>callable</type></simpara></listitem>
21+
<listitem><simpara><type>resource</type></simpara></listitem>
22+
</itemizedlist>
1523
</para>
1624

17-
<itemizedlist>
18-
19-
<listitem>
20-
<simpara>
21-
<type>bool</type>
22-
</simpara>
23-
</listitem>
24-
25-
<listitem>
26-
<simpara>
27-
<type>int</type>
28-
</simpara>
29-
</listitem>
30-
31-
<listitem>
32-
<simpara>
33-
<type>float</type> (floating-point number)
34-
</simpara>
35-
</listitem>
36-
37-
<listitem>
38-
<simpara>
39-
<type>string</type>
40-
</simpara>
41-
</listitem>
42-
43-
</itemizedlist>
44-
4525
<para>
46-
Four compound types:
26+
PHP is a dynamically typed language, which means that by default there is
27+
no need to specify the type of a variable, as this will be determined at
28+
runtime. However, it is possible to statically type some aspect of the
29+
language via the use of
30+
<link linkend="language.types.declarations">type declarations</link>.
4731
</para>
4832

49-
<itemizedlist>
50-
51-
<listitem>
52-
<simpara>
53-
<type>array</type>
54-
</simpara>
55-
</listitem>
56-
57-
<listitem>
58-
<simpara>
59-
<type>object</type>
60-
</simpara>
61-
</listitem>
62-
63-
<listitem>
64-
<simpara>
65-
<type>callable</type>
66-
</simpara>
67-
</listitem>
68-
69-
<listitem>
70-
<simpara>
71-
<type>iterable</type>
72-
</simpara>
73-
</listitem>
74-
75-
</itemizedlist>
76-
7733
<para>
78-
And finally two special types:
34+
Types restrict the kind of operations that can be performed on them.
35+
However, if an expression/variable is used in an operation which
36+
its type does not support, PHP will attempt to
37+
<link linkend="language.types.type-juggling">type juggle</link>
38+
the value into a type that supports the operation.
39+
This process depends on the context in which the value is used.
40+
For more information, see the section on
41+
<link linkend="language.types.type-juggling">Type Juggling</link>.
7942
</para>
8043

81-
<itemizedlist>
82-
83-
<listitem>
84-
<simpara>
85-
<type>resource</type>
86-
</simpara>
87-
</listitem>
88-
89-
<listitem>
90-
<simpara>
91-
<type>NULL</type>
92-
</simpara>
93-
</listitem>
94-
95-
</itemizedlist>
44+
<tip>
45+
<simpara>
46+
<link linkend="types.comparisons">The type comparison tables</link>
47+
may also be useful, as various examples of comparison between values of
48+
different types are present.
49+
</simpara>
50+
</tip>
9651

97-
<simpara>
98-
The type of a variable is not usually set by the programmer; rather, it is
99-
decided at runtime by PHP depending on the context in which that variable is
100-
used.
101-
</simpara>
102-
10352
<note>
10453
<simpara>
105-
To check the type and value of an
106-
<link linkend="language.expressions">expression</link>, use the
107-
<function>var_dump</function> function.
54+
It is possible to force an expression to be evaluated to a certain type by
55+
using a <link linkend="language.types.typecasting">type cast</link>.
56+
A variable can also be type cast in-place by using the
57+
<function>settype</function> function on it.
10858
</simpara>
59+
</note>
60+
61+
<para>
62+
To check the value and type of an
63+
<link linkend="language.expressions">expression</link>,
64+
use the <function>var_dump</function> function.
65+
To retrieve the type of an
66+
<link linkend="language.expressions">expression</link>,
67+
use the <function>get_debug_type</function> function.
68+
However, to check if an expression is of a certain type use the
69+
<!-- TODO When PhD support is there: <function>is_<replaceable>type</replaceable></function> -->
70+
<literal>is_<replaceable>type</replaceable></literal> functions instead.
10971

110-
<para>
111-
To get a human-readable representation of a type for debugging, use the
112-
<function>gettype</function> function. To check for a certain type, do
113-
<emphasis>not</emphasis> use <function>gettype</function>, but rather the
114-
<literal>is_<replaceable>type</replaceable></literal> functions. Some
115-
examples:
116-
</para>
117-
11872
<informalexample>
11973
<programlisting role="php">
12074
<![CDATA[
12175
<?php
122-
$a_bool = TRUE; // a boolean
76+
$a_bool = true; // a bool
12377
$a_str = "foo"; // a string
12478
$a_str2 = 'foo'; // a string
125-
$an_int = 12; // an integer
79+
$an_int = 12; // an int
12680
127-
echo gettype($a_bool); // prints out: boolean
128-
echo gettype($a_str); // prints out: string
81+
echo get_debug_type($a_bool), "\n";
82+
echo get_debug_type($a_str), "\n";
12983
13084
// If this is an integer, increment it by four
13185
if (is_int($an_int)) {
13286
$an_int += 4;
13387
}
88+
var_dump($an_int);
13489
13590
// If $a_bool is a string, print it out
136-
// (does not print out anything)
13791
if (is_string($a_bool)) {
13892
echo "String: $a_bool";
13993
}
14094
?>
14195
]]>
14296
</programlisting>
97+
&example.outputs.8;
98+
<screen>
99+
<![CDATA[
100+
bool
101+
string
102+
int(16)
103+
]]>
104+
</screen>
143105
</informalexample>
106+
</para>
107+
<note>
108+
<simpara>
109+
Prior to PHP 8.0.0, where the <function>get_debug_type</function> is not
110+
available, the <function>gettype</function> function can be used instead.
111+
However, it doesn't use the canonical type names.
112+
</simpara>
144113
</note>
145-
146-
<simpara>
147-
To forcibly convert a variable to a certain type, either
148-
<link linkend="language.types.typecasting">cast</link> the variable or use
149-
the <function>settype</function> function on it.
150-
</simpara>
151-
152-
<simpara>
153-
Note that a variable may be evaluated with different values in certain
154-
situations, depending on what type it is at the time. For more information,
155-
see the section on <link linkend="language.types.type-juggling">Type
156-
Juggling</link>. <link linkend="types.comparisons">The type comparison
157-
tables</link> may also be useful, as they show examples of various
158-
type-related comparisons.
159-
</simpara>
160114
</sect1>
161-
115+
116+
&language.types.type-system;
117+
&language.types.null;
162118
&language.types.boolean;
163119
&language.types.integer;
164120
&language.types.float;
165121
&language.types.string;
166122
&language.types.numeric-strings;
167123
&language.types.array;
168-
&language.types.iterable;
169124
&language.types.object;
170125
&language.types.enumerations;
171126
&language.types.resource;
172-
&language.types.null;
173127
&language.types.callable;
128+
&language.types.mixed;
129+
&language.types.void;
130+
&language.types.never;
131+
&language.types.relative-class-types;
132+
&language.types.literal;
133+
&language.types.iterable;
174134
&language.types.declarations;
175135
&language.types.type-juggling;
176-
136+
177137
</chapter>
178-
179138
<!-- Keep this comment at the end of the file
180139
Local variables:
181140
mode: sgml

‎language/types/boolean.xml

Lines changed: 19 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
<title>Booleans</title>
55

66
<simpara>
7-
This is the simplest type. A <type>bool</type> expresses a truth value. It
8-
can be either &true; or &false;.
7+
The <type>bool</type> type only has two values, and is used to express
8+
a truth value. It can be either &true; or &false;.
99
</simpara>
1010

1111
<sect2 xml:id="language.types.boolean.syntax">
@@ -61,14 +61,10 @@ if ($show_separators) {
6161

6262
<simpara>
6363
To explicitly convert a value to <type>bool</type>, use the
64-
<literal>(bool)</literal> or <literal>(boolean)</literal> casts. However, in
65-
most cases the cast is unnecessary, since a value will be automatically
66-
converted if an operator, function or control structure requires a
67-
<type>bool</type> argument.
68-
</simpara>
69-
70-
<simpara>
71-
See also <link linkend="language.types.type-juggling">Type Juggling</link>.
64+
<literal>(bool)</literal> cast. Generally this is not necessary because when
65+
a value is used in a logical context it will be automatically interpreted
66+
as a value of type <type>bool</type>. For more information see the
67+
<link linkend="language.types.type-juggling">Type Juggling</link> page.
7268
</simpara>
7369

7470
<para>
@@ -84,18 +80,20 @@ if ($show_separators) {
8480
</listitem>
8581
<listitem>
8682
<simpara>
87-
the <link linkend="language.types.integer">integer</link> 0 (zero)
83+
the <link linkend="language.types.integer">integer</link>
84+
<literal>0</literal> (zero)
8885
</simpara>
8986
</listitem>
9087
<listitem>
9188
<simpara>
92-
the <link linkend="language.types.float">float</link>s 0.0 and -0.0 (zero)
89+
the <link linkend="language.types.float">float</link>s
90+
<literal>0.0</literal> and <literal>-0.0</literal> (zero)
9391
</simpara>
9492
</listitem>
9593
<listitem>
9694
<simpara>
97-
the empty <link linkend="language.types.string">string</link>, and the
98-
<link linkend="language.types.string">string</link> "0"
95+
the empty <link linkend="language.types.string">string</link> <literal>""</literal>,
96+
and the <link linkend="language.types.string">string</link> <literal>"0"</literal>
9997
</simpara>
10098
</listitem>
10199
<listitem>
@@ -105,21 +103,23 @@ if ($show_separators) {
105103
</listitem>
106104
<listitem>
107105
<simpara>
108-
the special type <link linkend="language.types.null">NULL</link> (including
106+
the unit type <link linkend="language.types.null">NULL</link> (including
109107
unset variables)
110108
</simpara>
111109
</listitem>
112110
<listitem>
113111
<simpara>
114-
<link linkend="ref.simplexml">SimpleXML</link> objects created from attributeless
115-
empty elements, i.e. elements which have neither children nor attributes.
112+
Internal objects that overload their casting behaviour to bool.
113+
For example: <link linkend="ref.simplexml">SimpleXML</link> objects
114+
created from empty elements without attributes.
116115
</simpara>
117116
</listitem>
118117
</itemizedlist>
119118

120119
<para>
121-
Every other value is considered &true; (including any
122-
<link linkend="language.types.resource">resource</link> and <constant>NAN</constant>).
120+
Every other value is considered &true;
121+
(including <link linkend="language.types.resource">resource</link>
122+
and <constant>NAN</constant>).
123123
</para>
124124

125125
<warning>
@@ -149,7 +149,6 @@ var_dump((bool) "false"); // bool(true)
149149

150150
</sect2>
151151
</sect1>
152-
153152
<!-- Keep this comment at the end of the file
154153
Local variables:
155154
mode: sgml

0 commit comments

Comments
 (0)