Skip to content

Commit

Permalink
fix: sync oop docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@julionc
julionc committed Nov 23, 2024
1 parent f44371a commit a7051c4
Show file tree
Hide file tree
Showing 5 changed files with 1,107 additions and 45 deletions.
382 changes: 382 additions & 0 deletions language/constants.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,382 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
<title>Constants</title>

<simpara>
A constant is an identifier (name) for a simple value. As the name
suggests, that value cannot change during the execution of the
script (except for <link linkend="language.constants.magic">
magic constants</link>, which aren't actually constants).
Constants are case-sensitive. By convention, constant
identifiers are always uppercase.
</simpara>

<note>
<para>
Prior to PHP 8.0.0, constants defined using the <function>define</function>
function may be case-insensitive.
</para>
</note>

<para>
The name of a constant follows the same rules as any label in PHP. A
valid constant name starts with a letter or underscore, followed
by any number of letters, numbers, or underscores. As a regular
expression, it would be expressed thusly:
<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
</para>
<para>
It is possible to <function>define</function> constants with reserved or even
invalid names, whose value can only be retrieved with the
<function>constant</function> function. However, doing so is not recommended.
</para>
&tip.userlandnaming;
<para>
<!-- TODO Move into syntax section? -->
<example>
<title>Valid and invalid constant names</title>
<programlisting role="php">
<![CDATA[
<?php
// Valid constant names
define("FOO", "something");
define("FOO2", "something else");
define("FOO_BAR", "something more");
// Invalid constant names
define("2FOO", "something");
// This is valid, but should be avoided:
// PHP may one day provide a magical constant
// that will break your script
define("__FOO__", "something");
?>
]]>
</programlisting>
</example>
</para>
<note>
<simpara>
For our purposes here, a letter is a-z, A-Z, and the ASCII
characters from 128 through 255 (0x80-0xff).
</simpara>
</note>

<simpara>
Like &link.superglobals;, the scope of a constant is global.
Constants can be accessed from anywhere in a script without regard to scope.
For more information on scope, read the manual section on
<link linkend="language.variables.scope">variable scope</link>.
</simpara>

<note>
<simpara>
As of PHP 7.1.0, class constant may declare a visibility of protected
or private, making them only available in the hierarchical scope of the
class in which it is defined.
</simpara>
</note>

<sect1 xml:id="language.constants.syntax">
<title>Syntax</title>
<simpara>
Constants can be defined using the <literal>const</literal> keyword,
or by using the <function>define</function>-function.
While <function>define</function> allows a constant to be
defined to an arbitrary expression, the <literal>const</literal> keyword has
restrictions as outlined in the next paragraph.
Once a constant is defined, it can never be
changed or undefined.
</simpara>
<simpara>
When using the <literal>const</literal> keyword,
only scalar (<type>bool</type>, <type>int</type>,
<type>float</type> and <type>string</type>) expressions and constant
<type>array</type>s containing only scalar expressions are accepted.
It is possible to define constants as a <type>resource</type>,
but it should be avoided, as it can cause unexpected results.
</simpara>
<simpara>
The value of a constant is accessed simply by specifying its name.
Unlike variables, a constant is <emphasis>not</emphasis> prepended
with a <literal>$</literal>.
It is also possible to use the <function>constant</function> function to
read a constant's value if the constant's name is obtained dynamically.
Use <function>get_defined_constants</function> to get a list of
all defined constants.
</simpara>

<note>
<simpara>
Constants and (global) variables are in a different namespace.
This implies that for example &true; and
<varname>$TRUE</varname> are generally different.
</simpara>
</note>

<simpara>
If an undefined constant is used an <classname>Error</classname> is thrown.
Prior to PHP 8.0.0, undefined constants would be interpreted as a bare
word <type>string</type>, i.e. (CONSTANT vs "CONSTANT").
This fallback is deprecated as of PHP 7.2.0, and an error of level
<constant>E_WARNING</constant> is issued when it happens.
Prior to PHP 7.2.0, an error of level
<link linkend="ref.errorfunc">E_NOTICE</link> has been issued instead.
See also the manual entry on why
<link linkend="language.types.array.foo-bar">$foo[bar]</link> is
wrong (unless <literal>bar</literal> is a constant).
This does not apply to <link
linkend="language.namespaces.rules">(fully) qualified constants</link>,
which will always raise a <classname>Error</classname> if undefined.
</simpara>

<note>
<simpara>
To check if a constant is set, use the <function>defined</function> function.
</simpara>
</note>

<para>
These are the differences between constants and variables:
<itemizedlist>
<listitem>
<simpara>
Constants do not have a dollar sign (<literal>$</literal>)
before them;
</simpara>
</listitem>
<listitem>
<simpara>
Constants may be defined and accessed anywhere without regard
to variable scoping rules;
</simpara>
</listitem>
<listitem>
<simpara>
Constants may not be redefined or undefined once they have been
set; and
</simpara>
</listitem>
<listitem>
<simpara>
Constants may only evaluate to scalar values or arrays.
</simpara>
</listitem>
</itemizedlist>
</para>

<para>
<example>
<title>Defining Constants</title>
<programlisting role="php">
<![CDATA[
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // outputs "Hello world."
echo Constant; // Emits an Error: Undefined constant "Constant"
// Prior to PHP 8.0.0, outputs "Constant" and issues a warning.
?>
]]>
</programlisting>
</example>
</para>

<para>
<example>
<title>Defining Constants using the <literal>const</literal> keyword</title>
<programlisting role="php">
<![CDATA[
<?php
// Simple scalar value
const CONSTANT = 'Hello World';
echo CONSTANT;
// Scalar expression
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;
const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // outputs "cat"
// Constant arrays
define('ANIMALS', array(
'dog',
'cat',
'bird'
));
echo ANIMALS[1]; // outputs "cat"
?>
]]>
</programlisting>
</example>
</para>

<note>
<para>
As opposed to defining constants using <function>define</function>,
constants defined using the <literal>const</literal> keyword must be
declared at the top-level scope because they are defined at compile-time.
This means that they cannot be declared inside functions, loops,
<literal>if</literal> statements or
<literal>try</literal>/<literal>catch</literal> blocks.
</para>
</note>

<sect2 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="language.oop5.constants">Class Constants</link></member>
</simplelist>
</para>
</sect2>
</sect1>

<sect1 xml:id="language.constants.predefined">
<title>Predefined constants</title>

<simpara>
PHP provides a large number of <link
linkend="reserved.constants">predefined constants</link> to any script
which it runs. Many of these constants, however, are created by
various extensions, and will only be present when those extensions
are available, either via dynamic loading or because they have
been compiled in.
</simpara>
</sect1>

<sect1 xml:id="language.constants.magic">
<title>Magic constants</title>
<para>
There are nine magical constants that change depending on
where they are used. For example, the value of
<constant>__LINE__</constant> depends on the line that it's
used on in your script. All these "magical" constants are resolved
at compile time, unlike regular constants, which are resolved at runtime.
These special constants are case-insensitive and are as follows:
</para>
<para>
<table>
<title>PHP's magic constants</title>
<tgroup cols="2">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row xml:id="constant.line">
<entry><constant>__LINE__</constant></entry>
<entry>
The current line number of the file.
</entry>
</row>
<row xml:id="constant.file">
<entry><constant>__FILE__</constant></entry>
<entry>
The full path and filename of the file with symlinks resolved. If used inside an include,
the name of the included file is returned.
</entry>
</row>
<row xml:id="constant.dir">
<entry><constant>__DIR__</constant></entry>
<entry>
The directory of the file. If used inside an include,
the directory of the included file is returned. This is equivalent
to <literal>dirname(__FILE__)</literal>. This directory name
does not have a trailing slash unless it is the root directory.
</entry>
</row>
<row xml:id="constant.function">
<entry><constant>__FUNCTION__</constant></entry>
<entry>
The function name, or <literal>{closure}</literal> for anonymous functions.
</entry>
</row>
<row xml:id="constant.class">
<entry><constant>__CLASS__</constant></entry>
<entry>
The class name. The class name includes the namespace
it was declared in (e.g. <literal>Foo\Bar</literal>).
When used
in a trait method, __CLASS__ is the name of the class the trait
is used in.
</entry>
</row>
<row xml:id="constant.trait">
<entry><constant>__TRAIT__</constant></entry>
<entry>
The trait name. The trait name includes the namespace
it was declared in (e.g. <literal>Foo\Bar</literal>).
</entry>
</row>
<row xml:id="constant.method">
<entry><constant>__METHOD__</constant></entry>
<entry>
The class method name.
</entry>
</row>
<row xml:id="constant.property">
<entry><constant>__PROPERTY__</constant></entry>
<entry>
Only valid inside a <link linkend="language.oop5.property-hooks">property hook</link>. It is equal to the name of the property.
</entry>
</row>
<row xml:id="constant.namespace">
<entry><constant>__NAMESPACE__</constant></entry>
<entry>
The name of the current namespace.
</entry>
</row>
<row xml:id="constant.coloncolonclass">
<entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
<entry>
The fully qualified class name.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>

<sect2 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><link linkend="language.oop5.basic.class.class">::class</link></member>
<member><function>get_class</function></member>
<member><function>get_object_vars</function></member>
<member><function>file_exists</function></member>
<member><function>function_exists</function></member>
</simplelist>
</para>
</sect2>

</sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
1 change: 1 addition & 0 deletions language/oop5.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@

&language.oop5.basic;
&language.oop5.properties;
&language.oop5.property-hooks;
&language.oop5.constants;
&language.oop5.autoload;
&language.oop5.decon;
Expand Down
Loading

0 comments on commit a7051c4

Please sign in to comment.