Document the pipe operator. (#4890)

Author: Crell

language/operators.xml

@@ -42,6 +42,7 @@
  &language.operators.string;
  &language.operators.array;
  &language.operators.type;
+ &language.operators.functional;
 
 </chapter>
 <!-- Keep this comment at the end of the file

language/operators/functional.xml

@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="utf-8"?>
+<sect1 xml:id="language.operators.functional">
+ <title>Functional Operators</title>
+ <titleabbrev>Functional</titleabbrev>
+ <para>
+  PHP 8.5 and later supports one operator that works directly on callables.  The <literal>|></literal>
+  operator, or “pipe,” accepts a single-parameter callable on the right and passes
+  the left-side value to it, evaluating to the callable's result.  The callable
+  on the right may be any valid PHP callable: a <classname>Closure</classname>,
+  a <link linkend="functions.first_class_callable_syntax">first-class callable</link>,
+  an object that implements <link linkend="object.invoke">__invoke()</link>, etc.
+ </para>
+ <para>
+  That means the following two lines are logically equivalent.
+  <example>
+   <title>Using <literal>|></literal></title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$result = "Hello World" |> strlen(...);
+print $result . PHP_EOL;
+
+$result = strlen("Hello World");
+print $result . PHP_EOL;
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+11
+11
+]]>
+   </screen>
+  </example>
+ </para>
+ <para>
+  For a single call that is not especially useful. It becomes useful when multiple calls are chained together.
+  That is, the following two code fragments are logically equivalent:
+  <example>
+   <title>Chaining |> calls</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$result = "PHP Rocks"
+    |> htmlentities(...)
+    |> str_split(...)
+    |> (fn($x) => array_map(strtoupper(...), $x))
+    |> (fn($x) => array_filter($x, fn($v) => $v != 'O'))
+;
+print $result . PHP_EOL;
+
+$temp = "PHP Rocks";
+$temp = htmlentities($temp);
+$temp = str_split($temp);
+$temp = array_map(strtoupper(...), $temp);
+$temp = array_filter($temp, fn($v) => $v != 'O');
+$result = $temp;
+print $result . PHP_EOL;
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+Array
+(
+    [0] => P
+    [1] => H
+    [2] => P
+    [3] =>
+    [4] => R
+    [6] => C
+    [7] => K
+    [8] => S
+)
+Array
+(
+    [0] => P
+    [1] => H
+    [2] => P
+    [3] =>
+    [4] => R
+    [6] => C
+    [7] => K
+    [8] => S
+)
+]]>
+   </screen>
+  </example>
+ </para>
+ <para>
+  The left-hand side of the pipe may be any value or expression.  The right-hand side
+  may be any valid PHP callable that takes a single parameter, or any expression
+  that evaluates to such a callable.  Functions with more than one required parameter
+  are not allowed and will fail as if the function were called normally
+  with insufficient arguments. Functions that take a variable by reference are not allowed.
+  If the right-hand side does not evaluate to a valid callable it will throw an Error.
+ </para>
+ <note>
+  <para>
+   Be aware that, to avoid syntax ambiguity, <link linkend="functions.arrow">arrow functions</link>
+   MUST be wrapped in parentheses when used with a pipe operator, as in the examples above.
+   Failing to do so will result in a fatal error.
+  </para>
+ </note>
+
+ <sect2 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><classname>Closure</classname></member>
+   </simplelist>
+  </para>
+ </sect2>
+</sect1>