Effector

A Php library to write effect aware code.

In this library you will find a collection of classes, each one representing a single (side) effects. This allows you to write completely functional code treating effects as data, and delegating their execution to another component of your application.

You could find more details about the ideas beyond this approach here.

Install

Add this library to your dependencies using Composer with the command

composer require marcosh/effector

Usage

Every class contained in the src/Effect folder represents a single (side) effect. For example Marcosh\Effector\Effect\Echo_ represents the operation of echoing a string, or Marcosh\Effector\Effect|FileGetContents represents the operation of reading a file.

You can create a new instance of an effects simply with

$effect = new Echo_();

Pay attention to the fact that nothing will actually happen at this moment (except for the creation of the new instance of the class).

To actually perform the effect described by the class, you will need to invoke it

$effect('hello!');

This will actually perform the effect and echo the string passed as argument.

Compose effects

Representing effects as data is useful since you could pass them around, as input parameters or as return values of functions. Still if you had not the ability to create more complex effects from simple ones, they could be quite limiting.

Luckily, composing effects is pretty easy. To do that you could use the Marcosh\Effector\Compose class. This will receive several effects and pieces of logic and combine them in a single complex effect.

For example, if you have an effect that receives an HTTP request and an effect that emits an HTTP response, you could compose them to create a web application. This could be done as follows:

$websiteLogic = function (RequestInterface $request): ResponseInterface { ... }

$app = Compose::pieces(
    new ReceiveRequest(),
    $websiteLogic,
    new EmitResponse()
);

When you compose effects and pieces of logic, you have to be careful the each piece should return the input for the next one.

Examples

Several examples of possible usages and functionalities are provided in the example folder.

Run an example using

php example/ArgvEcho.php

or, if you are using Docker to obtain a PHP 7.1 environment, you could use

docker run --rm -ti -v "$(pwd):/app" --workdir /app php:7.1-cli php example/ArgvEcho.php

The examples contained in Http.php and in SerializeEffect.php are web application, so you need a web server to try them. The easiest option is to use the built in PHP web server with

php -S localhost:8000 example/Http.php

or, if you are using Docker,

docker run --rm -ti -p 8000:8000 -v "$(pwd):/app" php:7.1-cli php -S 0.0.0.0:8000 /app/example/Http.php

and then navigate to localhost:8000 to see it working.