rfc:pipe-operator-v2

PHP RFC: Pipe Operator v2

Version: 0.4

Date: 2020-04-20

Author: Larry Garfield larry@garfieldtech.com

Status: Under Discussion

First Published at: http://wiki.php.net/rfc/pipe-operator-v2

Introduction

Code like the following is quite common in procedural code: getPromotions ( mostExpensiveItem ( getShoppingList ( getCurrentUser ( ) , 'wishlist' ) , [ 'exclude' => 'onSale' ] ) , $holiday ) ; That is ugly, error prone, and hard to read or maintain. Generally, breaking it up as follows will improve readability: $user = getCurrentUser ( ) ; $shoppingList = getShoppingList ( $user , 'wishlist' ) ; $mostExpensiveItem = mostExpensiveItem ( $shoppingList , [ 'exclude' => 'onSale' ] ) ; $promotions = getPromotions ( $mostExpensiveItem , $holiday ) ; That, however, is still rather verbose and requires defining intermediary variables, and thus either coming up with names for them or using generic placeholder names like `$x`. The result is still error prone and it is possible to get confused by the variable names without realizing it. In OOP, it's common to answer “well use a fluent interface,” which might look like this: $promotions = getCurrentUser ( ) -> getShoppingList ( 'wishlist' ) -> mostExpensiveItem ( [ 'exclude' => 'onSale' ] ) -> getPromotions ( $holiday ) ; That's easier to read, but requires very specific methods on very specific objects, which are not always logical or possible to put there. This RFC aims to improve this type of code with the introduction of a “Pipe Operator,” which is a common approach in many other languages.

Proposal

This RFC introduces a new operator `|>`, “pipe”. Pipe evaluates left to right by passing the value (or expression result) on the left as the first parameter to the callable on the right. That is, the following two code fragments are exactly equivalent: $result = "Hello World" |> 'strlen' ; $result = strlen ( "Hello World" ) ; 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 also exactly equivalent: $result = "Hello World" |> 'htmlentities' |> 'explode' |> fn ( $x ) => array_map ( fn ( $v ) => 'strtoupper' , $x ) |> fn ( $x ) => array_filter ( $x , fn ( $v ) => $v != 'O' ) ; $result = array_filter ( array_map ( 'strtotupper' , explode ( htmlentties ( "Hello World" ) ) ) , fn ( $v ) => $v != 'O' ) ; Or, more practically, the example at the start of this RFC could be written as: $holiday = "Lincoln's Birthday" ; $result = getCurrentUser ( ) |> fn ( $x ) => getShoppingList ( $x , 'wishlist' ) |> fn ( $x ) => mostExpensiveItem ( $x , [ 'exclude' => 'onSale' ] ) |> fn ( $x ) => getPromotions ( $x , $holiday ) ; 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. If the right-hand side does not evaluate to a valid callable it will throw an Error. Functions that accept their first parameter by reference are supported, and will behave exactly as if they were called in the normal “inside out” fashion. However, unless they return a value as well they are not of much use. The pipe operator evaluates immediately. It does not produce a new function. However, it is simple to produce a new function by writing an arrow function: $holiday = "Lincoln's Birthday" ; $new_function = fn ( $user ) => $user |> fn ( $x ) => getShoppingList ( $x , 'wishlist' ) |> fn ( $x ) => mostExpensiveItem ( $x , [ 'exclude' => 'onSale' ] ) |> fn ( $x ) => getPromotions ( $x , $holiday ) ; $new_function ( getCurrentUser ( ) ) ;

More robust example with PSR-7

ServerRequest :: fromGlobals ( ) |> 'authenticate' |> [ $router , 'resolveAction' ] |> fn ( $request ) => $request -> getAttribute ( 'action' ) ( $request ) |> 'renderResult' |> 'buildResponse' |> 'emit' ;

Prior art

A previous RFC , Pipe Operator v1 from 2016 by Sara Golemon and Marcelo Camargo, proposed similar functionality. Its primary difference was to model on Hack, which allowed an arbitrary expression on the right-hand side and introduced a new `$$` magic variable as a placeholder for the left-hand side. While promising, the v2 authors concluded that short-lambdas made a custom one-off syntax unnecessary. The semantics proposed here are more consistent with most languages that offer a pipe operator. Portions of this RFC are nonetheless based on the previous iteration, and the author wishes to thank the v1 authors for their inspiration.

Out of scope

The pipe operator highlights the existing limitations around PHP's ability to reference existing callables. However, addressing that problem was determined to be out of scope, especially given the ease of using function name literals within a short lambda as above. Future work in other RFCs may address that issue, which would naturally complement this RFC . See the “Future Scope” section below.

Comparison with other languages

Several languages already support a pipe operator, using similar or identical syntax. In practice, the semantics proposed here are closest to Elixir and F#.

Hacklang

Hack has very similar functionality, also using the `|>` operator. However, in Hack the operator's right-hand side is an arbitrary expression in which a special placeholder, `$$` is used to indicate where the left-hand side should be injected. Effectively it becomes a one-off form of partial application. That is atypical among languages with such functionality and introduces additional questions about what sigil to use and other implementation details. The RFC authors opted to avoid the one-off partial application in favor of a narrower implementation for simplicity. A more holistic approach to partial application would be naturally beneficial here, however. (See “Future work”, below.) The Hack syntax was the subject of the v1 Pipe Operator RFC.

Haskell

Haskell has a function concatenation operator, `.`. However, its semantics are backwards. `reverse . sort` is equivalent to `reverse(sort())`, not to `sort(reverse())`. It also returns a new composed callable rather than invoking immediately. The inverse ordering is more difficult to reason about, and unfamiliar for PHP developers. The `.` operator itself would also cause confusion with the string concatenation operator, especially as strings can be callables. That is: 'hello' . 'strlen' Could be interpreted as evaluating to “hellostrlen” or to int 5. For that reason the `.` operator is not feasible.

F#

F# has no less than four function composition operators: Pipe forward `|>`, Pipe back `<|`, Compose forward `>>` and Compose back `<<`. The two pipe operators apply a value to a function, while the composer operator concatenates two functions to produce a new function that is the composition of the specified functions. The forward and back variants allow you to put the callable on either the left or right-hand side. The author decided that supporting both forward and back versions was too confusing. Additionally, a concatenation operator is unnecessary since users can simply form a short-lambda closure themselves. That is, this RFC proposes an equivalent of only the “pipe forward” operator.

Elixir

Elixir has a pipe operator, `|>`, using essentially the same semantics as described here.

Ruby

Ruby 2.6 added a similar syntax, although more akin to F#'s compose forward and compose back operators.

Javascript

A pipeline operator `|>` has been proposed for Javascript. As of this writing it is still in early stages and no implementations support it, but it may get accepted in the future. The semantics are essentially the same as described here.

Proposed PHP Version(s)

8.0

Backward compatibility issues

None.

Future Scope

This RFC suggests a number of additional improvements. They have been left for future work so as to keep this RFC focused and non-controversial. Should this RFC pass the authors intend to attempt these follow up improvements. (Assistance in doing so is quite welcome.) * Generic partial application. An RFC for this already exists, but does not yet have an implementation. This approach would allow for folding almost any multi-parameter function into a single-parameter function, including offering a clean way to reference a single parameter function by name. That would resolve the issues around referencing functions by name in the pipe right-hand side. * Iterable right-hand side. The pipe operator as presented here can only be used in a hard-coded fashion. A possible extension is to support an iterable of callables on the right-hand side, allowing for a runtime-defined pipeline. * A `__bind` method or similar on objects. If implemented by an object on the left-hand side, the right-hand side would be passed to that method to invoke as it sees fit. Effectively this would be operator overloading, which could be part of a second attempt at full operator overloading or a one-off magic method. It could also be implemented as a separate operator instead, for clarity. Such a feature would be sufficient to support arbitrary monadic behavior in PHP in a type-friendly way. All of these options are mentioned here for completeness and to give an indication of what is possible, but are *not* in scope and are *not* part of this RFC at this time.

Proposed Voting Choices

Adopt the Pipe Operator yes/no? Requires a 2/3 majority.

Patches and Tests