Download the PHP package toobo/pipepie without Composer

PipePie

Introduction

PipePie is a generic tool to apply a set of callbacks to some input data to obtain some output data.

So:

• Pipeline::pipe() is used to add callbacks to the pipeline
• Pipeline::applyTo() is used to apply the callbacks pipeline to some data

Every callback in the pipeline receives as 1st argument the value returned by previous callback. The 1st callback receives the input data.

Note that callbacks may be anything that evaluates as callable in PHP, so not only closures.

E.g. is possible to use invokable objects (i.e objects that have an __invoke() method) to improve code reusability.

Initial Value Access

The second argument that callbacks in the pipeline receive, is always the initial value, i.e. the value that was passed to Pipeline::applyTo()

In this way, every callback in the pipeline can do its work with being aware of the initial value.

DTO

DTO stands for "Data Transportation Object".

PipePie uses this kind of object to make possible to pass data across callbacks.

In fact, 3rd argument that callbacks receive is an instance of Toobo\PipePie\DTO class that is a very simple object that implements ArrayAccess interface.

Once this object instance is the same for all the callbacks in the pipeline, is possible to use it to pass data from a callback to next ones.

For the sake of data integrity, DTO implements ArrayAccess in a way that:

• it's not possible inside a callback to unset a DTO value that has been set by a previous callback
• it's not possible inside a callback to override a DTO value that has been set by a previous callback, if that value is an object

Context

As shown above, DTO is a good way to pass data from a callback to others.

Sometimes may be desirable to pass some context to all the callbacks, at Pipeline level.

That can be done by passing context data as 1st argument to Pipeline constructor. After that, context is reachable inside callbacks via DTO::context() method, called on the DTO instance that is passed to callbacks.

DTO "freshness"

Every time Pipeline::applyTo() is called on same Pipeline instance, DTO instance passed to callbacks is a fresh one, i.e. DTO state is not maintained across applyTo() calls.

Only DTO::context() returns the same value because it is set at Pipeline level.

Auto Type Casting

May be desirable to be sure that every callback in the pipeline returns a specific data type. PipePie allows to do that in 2 ways:

• via Pipeline flags
• via custom callback

Type Casting via Flag

Pipeline class has some constants:

• Pipeline::TO_ARRAY
• Pipeline::TO_OBJECT
• Pipeline::TO_STRING
• Pipeline::TO_INT
• Pipeline::TO_BOOL
• Pipeline::TO_FLOAT

Passing one of them as 2nd argument to Pipeline constructor is possible be sure that the type returned by all the callbacks is the desired one.

Note that, by default, initial value passed to 1st callback, is not type casted (but its returning value is).

However, it's also possible to type cast even the initial value before it is passed to first callback. That can be done by passing true as 3rd argument to Pipeline constructor.

Type Casting via Custom Callback

Is possible to pass as 2nd argument to Pipeline constructor a callback that can be used to type cast the value returned by all the callbacks in the Pipeline.

Even if main scope of type-casting custom callback is, in fact, type-cast Pipeline callbacks result, it can be actually used to do anything.

Callback Additional Arguments

In the examples above is shown how Pipeline callbacks receive at least 3 arguments:

• 1st argument will be the result of previous callback in the pipeline (or initial value for 1st callback);
• 2nd argument will always be the initial data;
• 3rd argument will be a DTO instance.

It is possible to pass additional arguments on a callback basis.

That is done by passing an array of arguments as 2nd argument for Pipeline::pipe() method:

Nested Pipelines

If you like the fact that invokable objects can be used as callback to promote code reusability, you'll love the fact that Pipeline class implements an __invoke() method, that allows to use any Pipeline as a callback to be added to a "parent" Pipeline.

Note that when using nested pipelines, just like in code above, DTO is shared among pipelines, i.e. DTO instance is the same for callbacks in parent pipeline and callbacks in child pipelines.

Debug Aids

Pipeline class has a method: info() that gives information on:

• the context of the Pipeline (whatever was passed as 1st argument to constructor)
• for every applyTo() call on the Pipeline instance, the method returns an array with:
  • key 'started_at': contains the Unix timestamp with microseconds (obtained via microtime(true)) at the moment applyTo() was called
  • key 'transported': array representation of the whole content of the DTO object related to the applyTo() call
  • key: 'input' the initial value that was passed to applyTo()

Note that:

• information on various applyTo() calls, are shown in inverse chronological order: later calls are shown first;
• an info() call flushes information, so on subsequent calls the method returns only data for applyTo() calls happened since last info() call.

Requirements

• PHP 5.4+
• Composer to install

Installation

• PipePie is a Composer package available on Packagist and can be installed by running

Unit Tests

PipePie repository contains some unit tests written for PHPUnit.

To run tests, navigate to repo folder from console and run:

License

PipePie is released under MIT, see LICENSE file for more info.