PHP 8.5's pipe operator and the array stdlib problem

#laravel #php #symfony #webdev

PHP 8.5 shipped a pipe operator, from Larry Garfield's RFC (approved 33-7). The marketing examples look great:

$slug = $title
    |> trim(...)
    |> strtolower(...);

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.

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.

The naive port

A common form-handling task: clean user-submitted tags and sort a-z.

$cleanTags = array_values(
    array_filter(
        array_map(fn($t) => strtolower(trim($t)), $rawTags),
        fn($t) => strlen($t) >= 3
    )
);
sort($cleanTags);

Three nested calls plus a trailing sort. It has to be its own statement because sort returns bool and mutates the array by reference. You read the nested part middle-out: array_map runs first, then array_filter, then array_values. Eyes parse opposite to execution.

The pipe operator should clean this up. Here's the rewrite:

$cleanTags = $rawTags
    |> (fn($ts) => array_map(fn($t) => strtolower(trim($t)), $ts))
    |> (fn($ts) => array_filter($ts, fn($t) => strlen($t) >= 3))
    |> array_values(...)
    |> (function ($ts) { sort($ts); return $ts; });

Better than the nested version. Reads top to bottom. But three things are happening here that the toy examples don't tell you about.

Gotcha 1: argument-order mismatch

array_map and array_filter take their arguments in different orders.

array_map(callable $callback, array $array, ...); // callable first
array_filter(array $array, ?callable $callback, ...); // array first

The pipe operator passes the left value as the first argument to whatever's on the right, so you can't first-class either function into a chain:

$result = $rawTags |> array_filter(...); // works, array is first arg
$result = $rawTags |> array_map(...); // broken, $rawTags lands as callback

To use array_map in a pipe, wrap it in an arrow function to swap the argument order. In the rewrite, both array_map and array_filter need a wrapper. array_map to swap arguments, array_filter to inject the predicate. Only array_values fits naturally because it's single-argument.

The pipe operator doesn't paper over the stdlib's inconsistencies; it makes them more visible. Every chain across array_map / array_filter / array_reduce ends up with this kind of glue in it.

Gotcha 2: arrow functions need parentheses

Look at the wrappers in the rewrite:

|> (fn($ts) => array_map(fn($t) => strtolower(trim($t)), $ts))

The parens around the arrow function are required, not stylistic. Without them, the arrow function "captures" everything to the end of the expression:

$result = $rawTags |> fn($ts) => array_map(...) |> array_values(...);

The parser reads that as the arrow function returning everything from array_map(...) through |> array_values(...). One stage, not two.

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.

First-class callables (trim(...), strtolower(...)) 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 (fn($x) => ...) over and over.

Gotcha 3: by-reference functions don't compose

That last step in the rewrite is uglier than the others for a reason:

|> (function ($ts) { sort($ts); return $ts; });

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:

$rawTags |> sort(...); // error: by-ref param
$rawTags |> array_walk(...); // same
$stack |> array_pop(...); // same

sort, rsort, usort, ksort, array_push, array_pop, array_shift, array_unshift, array_walk. 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 sort outside the pipe and feed the result in.

Where the pipe operator actually shines

For chains of unary stdlib functions, the operator is exactly what you'd want:

$slug = $title
    |> trim(...)
    |> strtolower(...)
    |> (fn($s) => preg_replace('/[^a-z0-9]+/', '-', $s));

$payload = $body
    |> json_encode(...)
    |> gzencode(...)
    |> base64_encode(...);

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. __invoke objects and instance methods compose cleanly too, which is probably the use case the operator was actually designed for.

A coherent collection API does this naturally

The same tag-cleanup code with a collection library:

$cleanTags = listOf($rawTags)
    ->map(fn(string $t) => strtolower(trim($t)))
    ->filter(fn(string $t) => strlen($t) >= 3)
    ->sorted();

No wrappers, no parens-around-arrows, no array_values plumbing, no by-ref dance. PHPStan carries ImmutableList<string> all the way through. map(), filter(), and sorted() are methods, so the data is implicit (it's $this) and the callable is the first explicit argument every time.

The example uses noctud/collection, 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.

The real fix would be native

The deeper issue is the stdlib itself. PHP's stdlib was never shaped for chaining. array_map and array_filter 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.

Nikita Popov's scalar_objects extension, from 2014, already showed what that could look like: $str->length(), $arr->map(...), 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.

Doing it there means making the harder calls extensions get to dodge: which methods, what's the receiver, and the bigger question of whether array 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 array, that's the win the pipe operator alone can't deliver.

The takeaway

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 __invoke objects.

For array operations (anything involving array_map, array_filter, or by-reference functions like sort and array_walk), 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.