[PHP 8.1] Document final class constants. (#1041)

* Document final class constant.

* use singular form.

* Update language/oop5/constants.xml

Co-authored-by: Máté Kocsis <kocsismate@woohoolabs.com>

* Update language/oop5/constants.xml

Co-authored-by: Máté Kocsis <kocsismate@woohoolabs.com>

Co-authored-by: Máté Kocsis <kocsismate@woohoolabs.com>

appendices/migration81/new-features.xml

@@ -145,6 +145,7 @@
 
    <para>
     Added support for the <modifier>final</modifier> modifier for class constants.
+    Also, interface constants become overridable by default.
     <!-- RFC: https://wiki.php.net/rfc/final_class_const -->
    </para>
   </sect3>

language/oop5/basic.xml

@@ -364,12 +364,17 @@ echo ($obj->bar)(), PHP_EOL;
    <para>
     The inherited constants, methods, and properties can be overridden by
     redeclaring them with the same name defined in the parent
-    class. However, if the parent class has defined a method
-    as <link linkend="language.oop5.final">final</link>, that method
-    may not be overridden.  It is possible to access the overridden
+    class. However, if the parent class has defined a method or constant
+    as <link linkend="language.oop5.final">final</link>,
+    they may not be overridden.  It is possible to access the overridden
     methods or static properties by referencing them
     with <link linkend="language.oop5.paamayim-nekudotayim">parent::</link>.
    </para>
+   <note>
+    <simpara>
+     As of PHP 8.1.0, constants may be declared as final.
+    </simpara>
+   </note>
    <example>
     <title>Simple Class Inheritance</title>
     <programlisting role="php">

language/oop5/changelog.xml

@@ -16,6 +16,12 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.1.0</entry>
+      <entry>
+       Added: Support for the <modifier>final</modifier> modifier for class constants. Also, interface constants become overridable by default.
+      </entry>
+     </row>
      <row>
       <entry>7.4.0</entry>
       <entry>

language/oop5/constants.xml

@@ -10,6 +10,8 @@
  <note>
   <para>
    Class constants can be redefined by a child class.
+   As of PHP 8.1.0, class constants cannot be redefined by a child class
+   if it is defined as <link linkend="language.oop5.final">final</link>.
   </para>
  </note>
  <para>

language/oop5/final.xml

@@ -3,7 +3,7 @@
  <sect1 xml:id="language.oop5.final" xmlns="http://docbook.org/ns/docbook">
   <title>Final Keyword</title>
   <para>
-   The final keyword prevents child classes from overriding a method by
+   The final keyword prevents child classes from overriding a method or constant by
    prefixing the definition with <literal>final</literal>. If the class
    itself is being defined final then it cannot be extended.
   </para>
@@ -59,10 +59,32 @@ class ChildClass extends BaseClass {
     </programlisting>
    </example>
   </para>
+  <para>
+   <example>
+    <title>Final constants example as of PHP 8.1.0</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+class Foo
+{
+    final public const X = "foo";
+}
+
+class Bar extends Foo
+{
+    public const X = "bar";
+}
+
+// Fatal error: Bar::X cannot override final constant Foo::X
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+
   <note>
    <simpara>
-    Properties and constants cannot be declared final, only classes and methods 
-    may be declared as final.
+    Properties cannot be declared final: only classes, methods, and constants (as of PHP 8.1.0) may be declared as final.
    </simpara>
    <simpara>
     As of PHP 8.0.0, private methods may not be declared final except for the constructor.

language/oop5/interfaces.xml

@@ -88,8 +88,8 @@
    <title><literal>Constants</literal></title>
    <para>
     It's possible for interfaces to have constants. Interface constants work exactly 
-    like <link linkend="language.oop5.constants">class constants</link> except
-    they cannot be overridden by a class/interface that inherits them.
+    like <link linkend="language.oop5.constants">class constants</link>.
+    Prior to PHP 8.1.0, they cannot be overridden by a class/interface that inherits them.
    </para>
   </sect2>
   <sect2 xml:id="language.oop5.interfaces.examples">
@@ -238,12 +238,15 @@ interface A
 echo A::B;
 
 
-// This will however not work because it's not allowed to 
-// override constants.
 class B implements A
 {
     const B = 'Class constant';
 }
+
+// Prints: Class constant
+// Prior to PHP 8.1.0, this will however not work because it was not
+// allowed to override constants.
+echo B::B;
 ?>
 ]]>
      </programlisting>

reference/reflection/reflectionclassconstant/isfinal.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="reflectionclassconstant.isfinal" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>ReflectionClassConstant::isFinal</refname>
+  <refpurpose>Checks if class constant is final</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>bool</type><methodname>ReflectionClassConstant::isFinal</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+   Checks if the class constant is final.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &true; if the class constant is final, otherwise &false;
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>ReflectionClassConstant::isPublic</methodname></member>
+    <member><methodname>ReflectionClassConstant::isPrivate</methodname></member>
+    <member><methodname>ReflectionClassConstant::isProtected</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- 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
+-->

reference/reflection/reflectionclassconstant/isprivate.xml

@@ -34,6 +34,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><methodname>ReflectionClassConstant::isFinal</methodname></member>
     <member><methodname>ReflectionClassConstant::isPublic</methodname></member>
     <member><methodname>ReflectionClassConstant::isProtected</methodname></member>
    </simplelist>

reference/reflection/reflectionclassconstant/isprotected.xml

@@ -34,6 +34,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><methodname>ReflectionClassConstant::isFinal</methodname></member>
     <member><methodname>ReflectionClassConstant::isPublic</methodname></member>
     <member><methodname>ReflectionClassConstant::isPrivate</methodname></member>
    </simplelist>

reference/reflection/reflectionclassconstant/ispublic.xml

@@ -34,6 +34,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><methodname>ReflectionClassConstant::isFinal</methodname></member>
     <member><methodname>ReflectionClassConstant::isPrivate</methodname></member>
     <member><methodname>ReflectionClassConstant::isProtected</methodname></member>
    </simplelist>

reference/reflection/versions.xml

@@ -261,6 +261,7 @@
  <function name="reflectionclassconstant::__tostring" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
  <function name="reflectionclassconstant::export" from="PHP 7 &gt;= 7.1.0" deprecated="PHP 7.4.0" removed="PHP 8"/>
  <function name="reflectionclassconstant::getname" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
+ <function name="reflectionclassconstant::isfinal" from="PHP 8 &gt;= 8.1.0"/>
  <function name="reflectionclassconstant::ispublic" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
  <function name="reflectionclassconstant::isprivate" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
  <function name="reflectionclassconstant::isprotected" from="PHP 7 &gt;= 7.1.0, PHP 8"/>