<p>PHP 8.5 shipped a pipe operator, from <a href="https://wiki.php.net/rfc/pipe-operator-v3" rel="noopener noreferrer">Larry Garfield's RFC</a> (approved 33-7). The marketing examples look great:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$slug</span> <span class="o">=</span> <span class="nv">$title</span> <span class="o">|&gt;</span> <span class="nb">trim</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="nb">strtolower</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> </code></pre> </div> <p>Reads top to bottom, no nesting, types flow. For chains of single-input transformations, which is what the RFC was explicit about targeting, the operator does exactly what you'd want.</p> <p>The friction starts when you reach for it on PHP's array stdlib, which is where most day-to-day chaining happens. Most of what follows isn't really a flaw in the pipe operator itself. It's the stdlib's call-shape inconsistencies leaking through whatever composition mechanism you put on top of them.</p> <h2> The naive port </h2> <p>A common form-handling task: clean user-submitted tags and sort a-z.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$cleanTags</span> <span class="o">=</span> <span class="nb">array_values</span><span class="p">(</span> <span class="nb">array_filter</span><span class="p">(</span> <span class="nb">array_map</span><span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strtolower</span><span class="p">(</span><span class="nb">trim</span><span class="p">(</span><span class="nv">$t</span><span class="p">)),</span> <span class="nv">$rawTags</span><span class="p">),</span> <span class="k">fn</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strlen</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">3</span> <span class="p">)</span> <span class="p">);</span> <span class="nb">sort</span><span class="p">(</span><span class="nv">$cleanTags</span><span class="p">);</span> </code></pre> </div> <p>Three nested calls plus a trailing <code>sort</code>. It has to be its own statement because <code>sort</code> returns <code>bool</code> and mutates the array by reference. You read the nested part middle-out: <code>array_map</code> runs first, then <code>array_filter</code>, then <code>array_values</code>. Eyes parse opposite to execution.</p> <p>The pipe operator should clean this up. Here's the rewrite:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$cleanTags</span> <span class="o">=</span> <span class="nv">$rawTags</span> <span class="o">|&gt;</span> <span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$ts</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">array_map</span><span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strtolower</span><span class="p">(</span><span class="nb">trim</span><span class="p">(</span><span class="nv">$t</span><span class="p">)),</span> <span class="nv">$ts</span><span class="p">))</span> <span class="o">|&gt;</span> <span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$ts</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">array_filter</span><span class="p">(</span><span class="nv">$ts</span><span class="p">,</span> <span class="k">fn</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strlen</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">3</span><span class="p">))</span> <span class="o">|&gt;</span> <span class="nb">array_values</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="p">(</span><span class="k">function</span> <span class="p">(</span><span class="nv">$ts</span><span class="p">)</span> <span class="p">{</span> <span class="nb">sort</span><span class="p">(</span><span class="nv">$ts</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$ts</span><span class="p">;</span> <span class="p">});</span> </code></pre> </div> <p>Better than the nested version. Reads top to bottom. But three things are happening here that the toy examples don't tell you about.</p> <h2> Gotcha 1: argument-order mismatch </h2> <p><code>array_map</code> and <code>array_filter</code> take their arguments in different orders.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nb">array_map</span><span class="p">(</span><span class="n">callable</span> <span class="nv">$callback</span><span class="p">,</span> <span class="k">array</span> <span class="nv">$array</span><span class="p">,</span> <span class="mf">...</span><span class="p">);</span> <span class="c1">// callable first</span> <span class="nb">array_filter</span><span class="p">(</span><span class="k">array</span> <span class="nv">$array</span><span class="p">,</span> <span class="o">?</span><span class="n">callable</span> <span class="nv">$callback</span><span class="p">,</span> <span class="mf">...</span><span class="p">);</span> <span class="c1">// array first</span> </code></pre> </div> <p>The pipe operator passes the left value as the <em>first</em> argument to whatever's on the right, so you can't first-class either function into a chain:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$result</span> <span class="o">=</span> <span class="nv">$rawTags</span> <span class="o">|&gt;</span> <span class="nb">array_filter</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> <span class="c1">// works, array is first arg</span> <span class="nv">$result</span> <span class="o">=</span> <span class="nv">$rawTags</span> <span class="o">|&gt;</span> <span class="nb">array_map</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> <span class="c1">// broken, $rawTags lands as callback</span> </code></pre> </div> <p>To use <code>array_map</code> in a pipe, wrap it in an arrow function to swap the argument order. In the rewrite, both <code>array_map</code> and <code>array_filter</code> need a wrapper. <code>array_map</code> to swap arguments, <code>array_filter</code> to inject the predicate. Only <code>array_values</code> fits naturally because it's single-argument.</p> <p>The pipe operator doesn't paper over the stdlib's inconsistencies; it makes them more visible. Every chain across <code>array_map</code> / <code>array_filter</code> / <code>array_reduce</code> ends up with this kind of glue in it.</p> <h2> Gotcha 2: arrow functions need parentheses </h2> <p>Look at the wrappers in the rewrite:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="o">|&gt;</span> <span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$ts</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">array_map</span><span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strtolower</span><span class="p">(</span><span class="nb">trim</span><span class="p">(</span><span class="nv">$t</span><span class="p">)),</span> <span class="nv">$ts</span><span class="p">))</span> </code></pre> </div> <p>The parens around the arrow function are required, not stylistic. Without them, the arrow function "captures" everything to the end of the expression:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$result</span> <span class="o">=</span> <span class="nv">$rawTags</span> <span class="o">|&gt;</span> <span class="k">fn</span><span class="p">(</span><span class="nv">$ts</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">array_map</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="nb">array_values</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> </code></pre> </div> <p>The parser reads that as the arrow function returning everything from <code>array_map(...)</code> through <code>|&gt; array_values(...)</code>. One stage, not two.</p> <p>This was the edge case the 2025-08-28 RFC errata pinned down. The rule: wrap arrow functions in parens any time they appear in a pipe chain. Forget once and the bug is silent.</p> <p>First-class callables (<code>trim(...)</code>, <code>strtolower(...)</code>) avoid the issue because they're a single token, with no expression body for the parser to grab. The moment your chain has any non-unary stdlib function, though, you're back to writing <code>(fn($x) =&gt; ...)</code> over and over.</p> <h2> Gotcha 3: by-reference functions don't compose </h2> <p>That last step in the rewrite is uglier than the others for a reason:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="o">|&gt;</span> <span class="p">(</span><span class="k">function</span> <span class="p">(</span><span class="nv">$ts</span><span class="p">)</span> <span class="p">{</span> <span class="nb">sort</span><span class="p">(</span><span class="nv">$ts</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$ts</span><span class="p">;</span> <span class="p">});</span> </code></pre> </div> <p>It can't be a one-liner arrow function, and it can't be a first-class callable. The RFC explicitly forbids first-class callables for any function whose first parameter is by-reference, which takes a long list of stdlib functions out of the pipe-able set:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$rawTags</span> <span class="o">|&gt;</span> <span class="nb">sort</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> <span class="c1">// error: by-ref param</span> <span class="nv">$rawTags</span> <span class="o">|&gt;</span> <span class="nb">array_walk</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> <span class="c1">// same</span> <span class="nv">$stack</span> <span class="o">|&gt;</span> <span class="nb">array_pop</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> <span class="c1">// same</span> </code></pre> </div> <p><code>sort</code>, <code>rsort</code>, <code>usort</code>, <code>ksort</code>, <code>array_push</code>, <code>array_pop</code>, <code>array_shift</code>, <code>array_unshift</code>, <code>array_walk</code>. All by-reference, all rejected. Most of the in-place array operations you'd reach for during a chain. The workaround is the full closure shown above: a function that mutates and returns. In practice you'll usually call <code>sort</code> outside the pipe and feed the result in.</p> <h2> Where the pipe operator actually shines </h2> <p>For chains of unary stdlib functions, the operator is exactly what you'd want:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$slug</span> <span class="o">=</span> <span class="nv">$title</span> <span class="o">|&gt;</span> <span class="nb">trim</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="nb">strtolower</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="nv">$s</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">preg_replace</span><span class="p">(</span><span class="s1">'/[^a-z0-9]+/'</span><span class="p">,</span> <span class="s1">'-'</span><span class="p">,</span> <span class="nv">$s</span><span class="p">));</span> </code></pre> </div> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$payload</span> <span class="o">=</span> <span class="nv">$body</span> <span class="o">|&gt;</span> <span class="nb">json_encode</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="nb">gzencode</span><span class="p">(</span><span class="mf">...</span><span class="p">)</span> <span class="o">|&gt;</span> <span class="nb">base64_encode</span><span class="p">(</span><span class="mf">...</span><span class="p">);</span> </code></pre> </div> <p>Top to bottom, no argument-order gymnastics, the parens-around-arrow rule isn't a constant tax. String pipelines, encode/decode chains, math chains, hex round-trips. Anywhere the data is the first argument and the functions are unary, this is good code. <code>__invoke</code> objects and instance methods compose cleanly too, which is probably the use case the operator was actually designed for.</p> <h2> A coherent collection API does this naturally </h2> <p>The same tag-cleanup code with a collection library:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight php"><code><span class="nv">$cleanTags</span> <span class="o">=</span> <span class="nf">listOf</span><span class="p">(</span><span class="nv">$rawTags</span><span class="p">)</span> <span class="o">-&gt;</span><span class="nf">map</span><span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strtolower</span><span class="p">(</span><span class="nb">trim</span><span class="p">(</span><span class="nv">$t</span><span class="p">)))</span> <span class="o">-&gt;</span><span class="nf">filter</span><span class="p">(</span><span class="k">fn</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$t</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nb">strlen</span><span class="p">(</span><span class="nv">$t</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">3</span><span class="p">)</span> <span class="o">-&gt;</span><span class="nf">sorted</span><span class="p">();</span> </code></pre> </div> <p>No wrappers, no parens-around-arrows, no <code>array_values</code> plumbing, no by-ref dance. PHPStan carries <code>ImmutableList&lt;string&gt;</code> all the way through. <code>map()</code>, <code>filter()</code>, and <code>sorted()</code> are methods, so the data is implicit (it's <code>$this</code>) and the callable is the first explicit argument every time.</p> <p>The example uses <a href="https://noctud.dev" rel="noopener noreferrer">noctud/collection</a>, which is what I work on. Other collection libraries (illuminate/collections, doctrine/collections, ramsey/collection) solve the call-shape problem the same way at the method level. The point isn't the specific library; it's that a coherent method-chain API sidesteps the inconsistencies the pipe operator inherits from the stdlib.</p> <h2> The real fix would be native </h2> <p>The deeper issue is the stdlib itself. PHP's stdlib was never shaped for chaining. <code>array_map</code> and <code>array_filter</code> taking arguments in different orders is a 1995 design that calcified before anyone thought about composition. The pipe operator works around the symptom. Native methods on arrays and strings would fix the cause.</p> <p>Nikita Popov's <a href="https://github.com/nikic/scalar_objects" rel="noopener noreferrer">scalar_objects extension</a>, from 2014, already showed what that could look like: <code>$str-&gt;length()</code>, <code>$arr-&gt;map(...)</code>, methods directly on the primitives. It worked, and it's been sitting there as a proof of concept for over a decade. The reason it never made it to core is that as an extension, every userland library could register its own method set on the built-in types, trading the current inconsistency for a different one with composer-install collisions on top.</p> <p>Doing it there means making the harder calls extensions get to dodge: which methods, what's the receiver, and the bigger question of whether <code>array</code> is really one type or two (a list and a map) wearing the same hat. Most modern languages split them. PHP didn't, and userland libraries (noctud/collection included) only paper over that conflation from outside the language. If core ever takes a serious run at native methods on arrays and strings, plus the harder design call of splitting <code>array</code>, that's the win the pipe operator alone can't deliver.</p> <h2> The takeaway </h2> <p>PHP 8.5's pipe operator is a real improvement. Use it for unary chains: string normalization, encode/decode pipelines, math, hex round-trips, pipelines of <code>__invoke</code> objects.</p> <p>For array operations (anything involving <code>array_map</code>, <code>array_filter</code>, or by-reference functions like <code>sort</code> and <code>array_walk</code>), the operator inherits all of PHP's stdlib inconsistencies and adds an arrow-function-paren footgun on top. More readable than the nested version, but the readability gain shrinks once you've added all the wrappers. If your code spends most of its time chaining array operations, a collection library remains the cleaner answer.</p>