sebastiaanluca / php-pipe-operator

Method chaining for any value using any method.

PHP Pipe Operator

Method chaining (or fluent expressions) for any value using any method.

Table of contents

• Requirements
• How to install
• How to use
  • The basics
  • Using first class callable syntax (enabling IDE autocompletion)
  • Using closures
  • Using class methods
• What does it solve?
  • A simple example
  • Another way of writing
  • More examples of the issue at hand
• Notes
• License
• Change log
• Testing
• Contributing
• Security
• Credits
• About

Requirements

• PHP 8.1 or 8.2

How to install

Via Composer:

composer require sebastiaanluca/php-pipe-operator

How to use

The basics

The basic gist of the package is that it takes a value and performs one or more actions on it. A simple example:

use SebastiaanLuca\PipeOperator\Pipe;

Pipe::from('hello')->strtoupper()->get();

// "HELLO"

A few alternatives to create the same instance:

take('hello')->strtoupper()->get();

// "HELLO"

pipe('hello')->strtoupper()->get();

// "HELLO"

Of course that's not very useful since you could've just used strtoupper('hello') and be done with it, but the goal is to make multi-method calls on a value easier to read and write:

$subdomain = Pipe::from('https://blog.sebastiaanluca.com')
    ->parse_url()
    ->end()
    ->explode('.', PIPED_VALUE)
    ->reset()
    ->get();

// "blog"

Note that in comparison to the original RFC, there's no need to pass the initial value to methods that receive the value as first parameter and have no other required parameters. The previous value is always passed as first parameter. In effect, both of the following examples will work:

Pipe::from('hello')->strtoupper()->get();

// "HELLO"

Pipe::from('hello')->strtoupper(PIPED_VALUE)->get();

// "HELLO"

In contrast, if a method takes e.g. a setting before the previous value, we need to set it manually using the replacement identifier (the globally available PIPED_VALUE constant). This identifier can be placed anywhere in the method call, it will simply be replaced by the previous value.

Pipe::from(['key' => 'value'])
    ->array_search('value', PIPED_VALUE)
    ->get();

// "key"

Using first class callable syntax (enabling IDE autocompletion)

Since PHP 8.1, you can use a first class callable syntax, or simply put an anonymous function, to pipe the value through. This enables full method autocompletion.

take('STRING')
    ->pipe(strtolower(...))
    ->get()

// "string"

Or using parameters:

Pipe::from('https://sebastiaanluca.com/blog')
    ->pipe(parse_url(...))
    ->end()
    ->pipe(substr(...), PIPED_VALUE, 3)
    ->pipe(strtoupper(...))
    ->get(),

// "OG"

Using closures

Sometimes standard methods don't cut it and you need to perform a custom operation on a value in the process. You can do so using a closure:

Pipe::from('string')
    ->pipe(fn(string $value): string => 'prefixed-' . $value)
    ->get();

// "prefixed-string"

Using class methods

The same is possible using a class method (regardless of visibility):

class MyClass
{
    public function __construct()
    {
        Pipe::from('HELLO')
            ->pipe($this)->lowercase()
            ->get();

        // "hello"
    }

    /**
     * @param string $value
     *
     * @return string
     */
    private function lowercase(string $value) : string
    {
        return mb_strtolower($value);
    }
}

Class method alternatives

If you don't want to use the internal pipe proxy and pass $this, there are two other ways you can use class methods.

Using first class callable syntax:

class MyClass
{
    public function __construct()
    {
        Pipe::from('HELLO')
            ->pipe($this->lowercase(...))
            ->get();

        // "hello"
    }

    /**
     * @param string $value
     *
     * @return string
     */
    public function lowercase(string $value) : string
    {
        return mb_strtolower($value);
    }
}

Using an array (for public methods only):

class MyClass
{
    public function __construct()
    {
        Pipe::from('HELLO')
            ->pipe([$this, 'lowercase'])
            ->get();

        // "hello"
    }

    /**
     * @param string $value
     *
     * @return string
     */
    public function lowercase(string $value) : string
    {
        return mb_strtolower($value);
    }
}

By parsing the callable method to a closure:

use Closure;

class MyClass
{
    public function __construct()
    {
        Pipe::from('HELLO')
            ->pipe(Closure::fromCallable([$this, 'lowercase']))
            ->get();

        // "hello"
    }

    /**
     * @param string $value
     *
     * @return string
     */
    private function lowercase(string $value) : string
    {
        return mb_strtolower($value);
    }
}

What does it solve?

This package is based on the pipe operator RFC by Sara Golemon (2016), who explains the problem as:

A common PHP OOP pattern is the use of method chaining, or what is also known as “Fluent Expressions”. […] This works well enough for OOP classes which were designed for fluent calling, however it is impossible, or at least unnecessarily arduous, to adapt non-fluent classes to this usage style, harder still for functional interfaces.

Coming across the proposal, I also blogged about it.

A simple example

Say you want to get the subdomain from a URL, you end up with something like this:

$subdomain = 'https://blog.sebastiaanluca.com/';
$subdomain = parse_url($subdomain, PHP_URL_HOST);
$subdomain = explode('.', $subdomain);
$subdomain = reset($subdomain);

// "blog"

This works, of course, but it's quite verbose and repetitive.

Another way of writing

Same result, different style:

$subdomain = explode('.', parse_url('https://blog.sebastiaanluca.com/', PHP_URL_HOST))[0];

// "blog"

This might be the worst of all solutions, as it requires you to start reading from the center, work your way towards the outer methods, and keep switching back and forth. The more methods and variants, the more difficult to get a sense of what's going on.

More examples of the issue at hand

See Sara's RFC for more complex and real-world examples.

Notes

While this packages makes a good attempt at bringing the pipe operator to PHP, it unfortunately does not offer autocompletion on chained methods. For that to work we need the real deal, so make some noise and get the people in charge to vote for Sara's RFC!

License

This package operates under the MIT License (MIT). Please see LICENSE for more information.

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

composer install
composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Sebastiaan Luca
• All Contributors

About

My name is Sebastiaan and I'm a freelance Laravel developer specializing in building custom Laravel applications. Check out my portfolio for more information, my blog for the latest tips and tricks, and my other packages to kick-start your next project.

Have a project that could use some guidance? Send me an e-mail at [email protected]!

php-pipe-operator's Issues

Seems like an abandoned project

It seems this is an abandoned project that does not support the latest PHP version. People looking for a good replacement can try boostphp/pipe-operator.

Why not a pipe() function?

Is there a specific reason you went for a pipe class instead of a simple pipe function, like:

function pipe() {
    $args = func_get_args();
    $result = $args[0];
    $functions = array_slice($args, 1);
    foreach ($functions as $function) {
        $result = $function($result);
    }
    return $result;
}

Just curious. ^^

Fluent interface

I do love the fluent code but wouldn't it be better to write a fluent interface? It would eliminate the need for PIPED_VALUE.

For example see the fluent strings in Laravel:
https://laravel.com/docs/8.x/helpers#fluent-strings

You could do the same for arrays and others.

Am I missing something?

strict_types=1 makes pipe-operator less agile [question]

Hi

It is very nice piece of work, I am using pipe-operator in my projects. It really rocks, especially in combination with symfony expression language.

When I upgraded to 5.x within php8 migration I noticed that some of my expressions need to be fix because of strict_types=1.

I am wondering is declaring strict_types=1 is good for pipe-operator? What were the arguments for doing this?

As I understand the purpose of the pipe-operator it to make the code flow :), get it more compact and agile and so does the php coercive mode which is good thing in specific cases, changing it to strict_types in my opinion takes pipe-operator one step back in terms of agile.

For example:

class A 
{
  public function __toString(): string
  {
    return '[]';
  }
}
take(new A())->json_decode()->get();

On version 3-4.x it executes with no errors, on version 5.x it ends with:

PHP Fatal error:  Uncaught TypeError: json_decode(): Argument #1 ($json) must be of type string, A given in /home/psuw/xtm/projekty/portal/portal/vendor/sebastiaanluca/php-pipe-operator/src/Pipe.php:37

Of course it will work but it is not so compact:

take((string) new A())->json_decode()->get();

symfony expression language:

take(a.__toString()).json_decode().get()