Skip to content

Commit a7051c4

Browse files
julioncjulionc
committed
fix: sync oop docs
1 parent f44371a commit a7051c4

File tree

5 files changed

+1107
-45
lines changed

5 files changed

+1107
-45
lines changed

‎language/constants.xml

Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
4+
<title>Constants</title>
5+
6+
<simpara>
7+
A constant is an identifier (name) for a simple value. As the name
8+
suggests, that value cannot change during the execution of the
9+
script (except for <link linkend="language.constants.magic">
10+
magic constants</link>, which aren't actually constants).
11+
Constants are case-sensitive. By convention, constant
12+
identifiers are always uppercase.
13+
</simpara>
14+
15+
<note>
16+
<para>
17+
Prior to PHP 8.0.0, constants defined using the <function>define</function>
18+
function may be case-insensitive.
19+
</para>
20+
</note>
21+
22+
<para>
23+
The name of a constant follows the same rules as any label in PHP. A
24+
valid constant name starts with a letter or underscore, followed
25+
by any number of letters, numbers, or underscores. As a regular
26+
expression, it would be expressed thusly:
27+
<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
28+
</para>
29+
<para>
30+
It is possible to <function>define</function> constants with reserved or even
31+
invalid names, whose value can only be retrieved with the
32+
<function>constant</function> function. However, doing so is not recommended.
33+
</para>
34+
&tip.userlandnaming;
35+
<para>
36+
<!-- TODO Move into syntax section? -->
37+
<example>
38+
<title>Valid and invalid constant names</title>
39+
<programlisting role="php">
40+
<![CDATA[
41+
<?php
42+
43+
// Valid constant names
44+
define("FOO", "something");
45+
define("FOO2", "something else");
46+
define("FOO_BAR", "something more");
47+
48+
// Invalid constant names
49+
define("2FOO", "something");
50+
51+
// This is valid, but should be avoided:
52+
// PHP may one day provide a magical constant
53+
// that will break your script
54+
define("__FOO__", "something");
55+
56+
?>
57+
]]>
58+
</programlisting>
59+
</example>
60+
</para>
61+
<note>
62+
<simpara>
63+
For our purposes here, a letter is a-z, A-Z, and the ASCII
64+
characters from 128 through 255 (0x80-0xff).
65+
</simpara>
66+
</note>
67+
68+
<simpara>
69+
Like &link.superglobals;, the scope of a constant is global.
70+
Constants can be accessed from anywhere in a script without regard to scope.
71+
For more information on scope, read the manual section on
72+
<link linkend="language.variables.scope">variable scope</link>.
73+
</simpara>
74+
75+
<note>
76+
<simpara>
77+
As of PHP 7.1.0, class constant may declare a visibility of protected
78+
or private, making them only available in the hierarchical scope of the
79+
class in which it is defined.
80+
</simpara>
81+
</note>
82+
83+
<sect1 xml:id="language.constants.syntax">
84+
<title>Syntax</title>
85+
<simpara>
86+
Constants can be defined using the <literal>const</literal> keyword,
87+
or by using the <function>define</function>-function.
88+
While <function>define</function> allows a constant to be
89+
defined to an arbitrary expression, the <literal>const</literal> keyword has
90+
restrictions as outlined in the next paragraph.
91+
Once a constant is defined, it can never be
92+
changed or undefined.
93+
</simpara>
94+
<simpara>
95+
When using the <literal>const</literal> keyword,
96+
only scalar (<type>bool</type>, <type>int</type>,
97+
<type>float</type> and <type>string</type>) expressions and constant
98+
<type>array</type>s containing only scalar expressions are accepted.
99+
It is possible to define constants as a <type>resource</type>,
100+
but it should be avoided, as it can cause unexpected results.
101+
</simpara>
102+
<simpara>
103+
The value of a constant is accessed simply by specifying its name.
104+
Unlike variables, a constant is <emphasis>not</emphasis> prepended
105+
with a <literal>$</literal>.
106+
It is also possible to use the <function>constant</function> function to
107+
read a constant's value if the constant's name is obtained dynamically.
108+
Use <function>get_defined_constants</function> to get a list of
109+
all defined constants.
110+
</simpara>
111+
112+
<note>
113+
<simpara>
114+
Constants and (global) variables are in a different namespace.
115+
This implies that for example &true; and
116+
<varname>$TRUE</varname> are generally different.
117+
</simpara>
118+
</note>
119+
120+
<simpara>
121+
If an undefined constant is used an <classname>Error</classname> is thrown.
122+
Prior to PHP 8.0.0, undefined constants would be interpreted as a bare
123+
word <type>string</type>, i.e. (CONSTANT vs "CONSTANT").
124+
This fallback is deprecated as of PHP 7.2.0, and an error of level
125+
<constant>E_WARNING</constant> is issued when it happens.
126+
Prior to PHP 7.2.0, an error of level
127+
<link linkend="ref.errorfunc">E_NOTICE</link> has been issued instead.
128+
See also the manual entry on why
129+
<link linkend="language.types.array.foo-bar">$foo[bar]</link> is
130+
wrong (unless <literal>bar</literal> is a constant).
131+
This does not apply to <link
132+
linkend="language.namespaces.rules">(fully) qualified constants</link>,
133+
which will always raise a <classname>Error</classname> if undefined.
134+
</simpara>
135+
136+
<note>
137+
<simpara>
138+
To check if a constant is set, use the <function>defined</function> function.
139+
</simpara>
140+
</note>
141+
142+
<para>
143+
These are the differences between constants and variables:
144+
<itemizedlist>
145+
<listitem>
146+
<simpara>
147+
Constants do not have a dollar sign (<literal>$</literal>)
148+
before them;
149+
</simpara>
150+
</listitem>
151+
<listitem>
152+
<simpara>
153+
Constants may be defined and accessed anywhere without regard
154+
to variable scoping rules;
155+
</simpara>
156+
</listitem>
157+
<listitem>
158+
<simpara>
159+
Constants may not be redefined or undefined once they have been
160+
set; and
161+
</simpara>
162+
</listitem>
163+
<listitem>
164+
<simpara>
165+
Constants may only evaluate to scalar values or arrays.
166+
</simpara>
167+
</listitem>
168+
</itemizedlist>
169+
</para>
170+
171+
<para>
172+
<example>
173+
<title>Defining Constants</title>
174+
<programlisting role="php">
175+
<![CDATA[
176+
<?php
177+
define("CONSTANT", "Hello world.");
178+
echo CONSTANT; // outputs "Hello world."
179+
echo Constant; // Emits an Error: Undefined constant "Constant"
180+
// Prior to PHP 8.0.0, outputs "Constant" and issues a warning.
181+
?>
182+
]]>
183+
</programlisting>
184+
</example>
185+
</para>
186+
187+
<para>
188+
<example>
189+
<title>Defining Constants using the <literal>const</literal> keyword</title>
190+
<programlisting role="php">
191+
<![CDATA[
192+
<?php
193+
// Simple scalar value
194+
const CONSTANT = 'Hello World';
195+
196+
echo CONSTANT;
197+
198+
// Scalar expression
199+
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
200+
echo ANOTHER_CONST;
201+
202+
const ANIMALS = array('dog', 'cat', 'bird');
203+
echo ANIMALS[1]; // outputs "cat"
204+
205+
// Constant arrays
206+
define('ANIMALS', array(
207+
'dog',
208+
'cat',
209+
'bird'
210+
));
211+
echo ANIMALS[1]; // outputs "cat"
212+
?>
213+
]]>
214+
</programlisting>
215+
</example>
216+
</para>
217+
218+
<note>
219+
<para>
220+
As opposed to defining constants using <function>define</function>,
221+
constants defined using the <literal>const</literal> keyword must be
222+
declared at the top-level scope because they are defined at compile-time.
223+
This means that they cannot be declared inside functions, loops,
224+
<literal>if</literal> statements or
225+
<literal>try</literal>/<literal>catch</literal> blocks.
226+
</para>
227+
</note>
228+
229+
<sect2 role="seealso">
230+
&reftitle.seealso;
231+
<para>
232+
<simplelist>
233+
<member><link linkend="language.oop5.constants">Class Constants</link></member>
234+
</simplelist>
235+
</para>
236+
</sect2>
237+
</sect1>
238+
239+
<sect1 xml:id="language.constants.predefined">
240+
<title>Predefined constants</title>
241+
242+
<simpara>
243+
PHP provides a large number of <link
244+
linkend="reserved.constants">predefined constants</link> to any script
245+
which it runs. Many of these constants, however, are created by
246+
various extensions, and will only be present when those extensions
247+
are available, either via dynamic loading or because they have
248+
been compiled in.
249+
</simpara>
250+
</sect1>
251+
252+
<sect1 xml:id="language.constants.magic">
253+
<title>Magic constants</title>
254+
<para>
255+
There are nine magical constants that change depending on
256+
where they are used. For example, the value of
257+
<constant>__LINE__</constant> depends on the line that it's
258+
used on in your script. All these "magical" constants are resolved
259+
at compile time, unlike regular constants, which are resolved at runtime.
260+
These special constants are case-insensitive and are as follows:
261+
</para>
262+
<para>
263+
<table>
264+
<title>PHP's magic constants</title>
265+
<tgroup cols="2">
266+
<thead>
267+
<row>
268+
<entry>&Name;</entry>
269+
<entry>&Description;</entry>
270+
</row>
271+
</thead>
272+
<tbody>
273+
<row xml:id="constant.line">
274+
<entry><constant>__LINE__</constant></entry>
275+
<entry>
276+
The current line number of the file.
277+
</entry>
278+
</row>
279+
<row xml:id="constant.file">
280+
<entry><constant>__FILE__</constant></entry>
281+
<entry>
282+
The full path and filename of the file with symlinks resolved. If used inside an include,
283+
the name of the included file is returned.
284+
</entry>
285+
</row>
286+
<row xml:id="constant.dir">
287+
<entry><constant>__DIR__</constant></entry>
288+
<entry>
289+
The directory of the file. If used inside an include,
290+
the directory of the included file is returned. This is equivalent
291+
to <literal>dirname(__FILE__)</literal>. This directory name
292+
does not have a trailing slash unless it is the root directory.
293+
</entry>
294+
</row>
295+
<row xml:id="constant.function">
296+
<entry><constant>__FUNCTION__</constant></entry>
297+
<entry>
298+
The function name, or <literal>{closure}</literal> for anonymous functions.
299+
</entry>
300+
</row>
301+
<row xml:id="constant.class">
302+
<entry><constant>__CLASS__</constant></entry>
303+
<entry>
304+
The class name. The class name includes the namespace
305+
it was declared in (e.g. <literal>Foo\Bar</literal>).
306+
When used
307+
in a trait method, __CLASS__ is the name of the class the trait
308+
is used in.
309+
</entry>
310+
</row>
311+
<row xml:id="constant.trait">
312+
<entry><constant>__TRAIT__</constant></entry>
313+
<entry>
314+
The trait name. The trait name includes the namespace
315+
it was declared in (e.g. <literal>Foo\Bar</literal>).
316+
</entry>
317+
</row>
318+
<row xml:id="constant.method">
319+
<entry><constant>__METHOD__</constant></entry>
320+
<entry>
321+
The class method name.
322+
</entry>
323+
</row>
324+
<row xml:id="constant.property">
325+
<entry><constant>__PROPERTY__</constant></entry>
326+
<entry>
327+
Only valid inside a <link linkend="language.oop5.property-hooks">property hook</link>. It is equal to the name of the property.
328+
</entry>
329+
</row>
330+
<row xml:id="constant.namespace">
331+
<entry><constant>__NAMESPACE__</constant></entry>
332+
<entry>
333+
The name of the current namespace.
334+
</entry>
335+
</row>
336+
<row xml:id="constant.coloncolonclass">
337+
<entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
338+
<entry>
339+
The fully qualified class name.
340+
</entry>
341+
</row>
342+
</tbody>
343+
</tgroup>
344+
</table>
345+
</para>
346+
347+
<sect2 role="seealso">
348+
&reftitle.seealso;
349+
<para>
350+
<simplelist>
351+
<member><link linkend="language.oop5.basic.class.class">::class</link></member>
352+
<member><function>get_class</function></member>
353+
<member><function>get_object_vars</function></member>
354+
<member><function>file_exists</function></member>
355+
<member><function>function_exists</function></member>
356+
</simplelist>
357+
</para>
358+
</sect2>
359+
360+
</sect1>
361+
</chapter>
362+
363+
<!-- Keep this comment at the end of the file
364+
Local variables:
365+
mode: sgml
366+
sgml-omittag:t
367+
sgml-shorttag:t
368+
sgml-minimize-attributes:nil
369+
sgml-always-quote-attributes:t
370+
sgml-indent-step:1
371+
sgml-indent-data:t
372+
indent-tabs-mode:nil
373+
sgml-parent-document:nil
374+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
375+
sgml-exposed-tags:nil
376+
sgml-local-catalogs:nil
377+
sgml-local-ecat-files:nil
378+
End:
379+
vim600: syn=xml fen fdm=syntax fdl=2 si
380+
vim: et tw=78 syn=sgml
381+
vi: ts=1 sw=1
382+
-->

‎language/oop5.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626

2727
&language.oop5.basic;
2828
&language.oop5.properties;
29+
&language.oop5.property-hooks;
2930
&language.oop5.constants;
3031
&language.oop5.autoload;
3132
&language.oop5.decon;

0 commit comments

Comments
 (0)