Reflection deprecation (#578)

* Clarify what a built-in type is.
* Add PHP 8 equivalent of ReflectionParameter::isArray().
* Leave note on ReflectionParameter::getClass() for what to use instead.
* Clarify order of the array in getParameters().
* Add example to aid working with union types.
* Add updated equivalent of isCallable().

Author: Crell

reference/reflection/reflectionfunctionabstract/getparameters.xml

@@ -14,7 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-   Get the parameters as an array of <type>ReflectionParameter</type>.
+   Get the parameters as an array of <type>ReflectionParameter</type>,
+   in the order in which they are defined in the source.
   </para>
 
   &warn.undocumented.func;

reference/reflection/reflectionnamedtype/isbuiltin.xml

@@ -14,7 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-   Checks if the type is a built-in type in PHP.
+   Checks if the type is a built-in type in PHP. A built-in type is any type that
+   is not a class, interface, or trait.
   </para>
  </refsect1>
 

reference/reflection/reflectionparameter/getclass.xml

@@ -19,6 +19,11 @@
   <para>
    Gets the class type hinted for the parameter as a <classname>ReflectionClass</classname> object.
   </para>
+  <para>
+   As of PHP 8.0.0 this function is deprecated and not recommended. Instead, use
+   <methodname>ReflectionParameter::getType</methodname> to get the <classname>ReflectionType</classname>
+   of the parameter, then interrogate that object to determine the parameter type.
+  </para>
 
   &warn.undocumented.func;
 
@@ -36,7 +41,7 @@
    or the declared type is not a class or interface.
   </para>
  </refsect1>
- 
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
@@ -55,12 +60,6 @@ echo $aParameter->getClass()->name;
 ?>
 ]]>
     </programlisting>
-    &example.outputs;
-    <screen>
-<![CDATA[
-Exception
-]]>
-    </screen>
    </example>
   </para>
  </refsect1>

reference/reflection/reflectionparameter/gettype.xml

@@ -92,6 +92,32 @@ NULL
 ]]>
     </screen>
    </example>
+   <example>
+   <title><methodname>ReflectionParameter::getType</methodname> Usage in PHP 8.0.0 and later</title>
+    <para>
+     As of PHP 8.0.0, this method may return a <classname>ReflectionNamedType</classname> instance or
+     a <classname>ReflectionUnionType</classname> instance.  The latter is a collection of the former.
+     To analyze a type, it is often convenient to normalize it to an array of <classname>ReflectionNamedType</classname>
+     objects.  The following function will return an array of <literal>0</literal> or more <classname>ReflectionNamedType</classname>
+     instances.
+    </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+function getAllTypes(ReflectionParameter $reflectionParameter): array
+{
+    $reflectionType = $reflectionParameter->getType();
+
+    if (!$reflectionType) return [];
+
+    return $reflectionType instanceof ReflectionUnionType
+        ? $reflectionType->getTypes()
+        : [$reflectionType];
+}
+?>
+]]>
+   </programlisting>
+  </example>
   </para>
  </refsect1>
 

reference/reflection/reflectionparameter/isarray.xml

@@ -9,6 +9,7 @@
 
  <refsynopsisdiv>
    &warn.deprecated.function-8-0-0;
+  <para>See the example below for an alternative way to derive this information.</para>
  </refsynopsisdiv>
 
  <refsect1 role="description">
@@ -34,6 +35,37 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>PHP 8.0.0 equivalent</title>
+    <para>
+     As of PHP 8.0.0, the following code will report if a type declares arrays,
+     including as part of a union.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function declaresArray(ReflectionParameter $reflectionParameter): bool
+{
+    $reflectionType = $reflectionParameter->getType();
+
+    if (!$reflectionType) return false;
+
+    $types = $reflectionType instanceof ReflectionUnionType
+        ? $reflectionType->getTypes()
+        : [$reflectionType];
+
+   return in_array('array', array_map(fn(ReflectionNamedType $t) => $t->getName(), $types));
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>

reference/reflection/reflectionparameter/iscallable.xml

@@ -9,6 +9,7 @@
 
  <refsynopsisdiv>
    &warn.deprecated.function-8-0-0;
+  <para>See the example below for an alternative way to derive this information.</para>
  </refsynopsisdiv>
 
  <refsect1 role="description">
@@ -38,6 +39,36 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+  <example>
+   <title>PHP 8.0.0 equivalent</title>
+   <para>
+    As of PHP 8.0.0, the following code will report if a type supports callables,
+    including as part of a union.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+function declaresCallable(ReflectionParameter $reflectionParameter): bool
+{
+    $reflectionType = $reflectionParameter->getType();
+
+    if (!$reflectionType) return false;
+
+    $types = $reflectionType instanceof ReflectionUnionType
+        ? $reflectionType->getTypes()
+        : [$reflectionType];
+
+   return in_array('callable', array_map(fn(ReflectionNamedType $t) => $t->getName(), $types));
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ </refsect1>
 
 </refentry>