Download the PHP package stellarwp/pipeline without Composer

StellarWP Pipeline

A Pipeline / Chain of Responsibility design pattern implementation based on Laravel's Pipeline implementation.

A Pipeline is an object that accepts input data and sends it through a series of handlers (or "pipes") — which are functions, closures, and/or classes — to get a result at the end.

Table of contents

• Installation
• Prerequisites
• Getting started
  • Creating a simple pipeline
  • Building pipelines in parts
  • Using functions
  • Using closures
  • Using classes with the handle method
  • Using classes with a custom method
  • Bailing early
  • Doing more than returning
  • Using a container in the pipeline
  • Declaring pipelines for reuse
  • Example
    • Service provider
    • Response transporter
    • Intake_response
    • Failed_response
    • Listener
    • Let's put it all together
• Methods
  • pipe() (aliases: add_pipe())
  • send()
  • set_container() (aliases: setContainer())
  • then() (aliases: run())
  • then_return() (aliases: run_and_return(), thenReturn())
  • through() (aliases: pipes())
  • via()

Installation

It's recommended that you install Pipeline as a project dependency via Composer:

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

An important note on namespaces:

The docs will in this repo all use StellarWP\Pipeline as the base namespace, however, if you are using Strauss to prefix namespaces in your project, you will need to adapt the namespaces accordingly. (Example: Boom\Shakalaka\StellarWP\Pipeline)

Prerequisites

There aren't any required prerequisites of note.

However! If you wish to use the stellarwp/container-contract.

Getting started

Luckily, there isn't a whole lot to Pipelines from a code perspective, so implementing them is pretty easy. We'll walk through some of the basic concepts.

Important note: The examples provide a string as input data. That is just for simplicity's sake! You can actually pass whatever you want - a scalar, an object, an array, whatever.

Creating a simple pipeline

Let's say you have a string that you want to pass through a series of steps in order to manipulate it. You can create a pipeline to do that like so:

Building pipelines in parts

You don't need to build the pipeline all at once, you can spread it out over a number of lines.

Using closures

If you have a more complicated function that you wish to use as a pipe, you can pass in a callable instead of a string. Your closure will need to accept two parameters, the first being the input data and the second being the next item in the pipeline.

Using classes with the handle method

You can even create your own classes to use as pipes in the pipeline. For a class to be usable in the pipeline, it needs a method that accepts two parameters, the first being the input data and the second being the next item in the pipeline.

By default, the Pipeline expects that the method is called handle. If you want to use that method name, you can optionally implement the StellarWP\Pipeline\Contracts\Pipe interface to enforce that method convention.

Example classes

First class:

Second class:

Example pipeline

Using classes with a custom method

If you want to use classes but want to use a different method than the expected default (handle), you can declare the alternate method name using the via() method.

Example classes

First class:

Second class:

Example pipeline

Bailing early

Sometimes in the middle of a pipeline, you want to stop processing the rest of the pipes and return a value. Luckily, you can do this with a return statement!

Example pipeline

Doing more than returning

Sometimes you may want to do more than returning the result when the pipeline completes. You can do that by using the then() (or its alias, run()) method instead of then_return().

Example pipeline

Using a container in the pipeline

Pipelines can be instantiated with a container that conforms to the stellarwp/container-contract StellarWP\ContainerContract\ContainerInterface interface. Adding a container to the pipeline allows you to pass classes as pipes and allow those classes to be instantiated when the pipeline is being run.

Declaring pipelines for reuse

A common approach to using pipelines is to declare them in a dependency injection container so that you can get an instance of a specifically configured pipeline when you need it.

Example

In this example, we are accepting in a WP_REST_Response object and we want to use a pipeline to process the response and fire off some actions based on the contents of the object.

We'll start with a couple of assumptions:

1. We are building some WordPress logic.
2. We will declare the reusable pipelines in a Service Provider class that extends a class named MyProject\AbstractServiceProvider and we can pretend that it accepts a container instance as a constructor argument.
3. That Service Provider class gets instantiated somewhere in our application and has a class property called $container that holds a container instance.
4. Our container conforms to the StellarWP\ContainerContract\ContainerInterface interface from the stellarwp/container-contract library.

This example's directory structure looks something like this:

Service provider

First, we'll create our service provider class.

Response_Transporter

Let's create a really simple object that will hold both a WP_REST_Request and a WP_REST_Response instance. This will be the object that we pass through our pipeline.

Intake_Response

Next, we'll create our Intake_Response class.

Failed_Response

Next, we'll create our Failed_Response class.

Listener

Finally, we'll create our Listener class.

Let's put it all together

Methods

pipe()

This method is used to add a pipe to the pipeline.

Aliases: add_pipe()

Examples

send()

This method is used to set the object being passed through the pipeline.

Examples

set_container()

This method is used to set the container instance.

Aliases: setContainer()

Examples

then()

This method is used to run the pipeline and return the result.

Aliases: run()

Examples

then_return()

This method is used to run the pipeline and return the result.

Aliases: run_and_return(), thenReturn()

Examples

through()

This method is used to set the handlers (or "pipes") that are used to process the data.

Aliases: pipes()

Examples

via()

This method is used to set the method to call on all the pipes in the pipeline.

Examples