2017 © Pedro Peláez
 

library assembly-builder

Lightweight functional assembly builder pattern with Scala like For Comprehension

image

chippyash/assembly-builder

Lightweight functional assembly builder pattern with Scala like For Comprehension

  • Wednesday, July 4, 2018
  • by chippyash
  • Repository
  • 1 Watchers
  • 0 Stars
  • 1,936 Installations
  • PHP
  • 5 Dependents
  • 0 Suggesters
  • 0 Forks
  • 0 Open issues
  • 14 Versions
  • 23 % Grown

The README.md

chippyash/Assembly-Builder

Quality Assurance

PHP 5.6 PHP 7 Build Status Code Climate Test Coverage, (*1)

The above badges represent the current development branch. As a rule, I don't push to GitHub unless tests, coverage and usability are acceptable. This may not be true for short periods of time; on holiday, need code for some other downstream project etc. If you need stable code, use a tagged version. Read 'Further Documentation' and 'Installation'., (*2)

Developer support for PHP5.4 & 5.5 was withdrawn at version 2.0.0 of this library. If you need support for PHP 5.4 or 5.5, please use a version>=1,<2, (*3)

Developer support for PHP7.X was withdrawn at version 3.0.0 of this library. If you need support for PHP 7.X, please use a version>=2,<3, (*4)

What?

Provides an Assembler, a lightweight variant of the Builder Pattern. Also provides a Scala like For Comprehension, (a simple descendant of Assembler.), (*5)

Why?

In my research of the Scala language, I came across the For Comprehension. It turns out that at its core, it is really a variant of a classic Builder Pattern, but without the associated requirements for a Director., (*6)

I did some searching but couldn't find anything remotely like it, so if you know of anything please do let me know., (*7)

So why is it useful?, (*8)

In essence it provides a mechanism to collect together things and then assemble them at some later point. The things in this case are functions. Since the introduction of Callables (or Closures) in PHP, life has changed a bit for the PHP dev. The anonymous function gives a freedom to do anything (PHP has always had that,) in a much simpler way., (*9)

It is really simple:

  • create an Assembler
  • attach a bunch of functions to it with a key (variable name) for the function
    • functions can access previously defined functions (or stored variables)
  • assemble everything (call the functions that have been previously attached)
  • access one, some or none of the results

The examples/OneManCoffeeShop.php script gives a flavour of the Assembler in action in a relatively simple scenario., (*10)

examples/CarAssemblyLine.php is a bit more complex, but shows how you can pass around an Assembler to various processes a bit like a shopping trolley, leaving it until some point in the future where it is all assembled into some final product. It also demonstrates a simple derivation of the Assembler, the Scala like For Comprehension which because For is a reserved word in PHP, is called FFor., (*11)

In a large system, you might want to use an Assembler as a collection point for stuff going on in the application. For this purpose you can get a Singleton instance via Assembler::get(). Of course, you can only use this once (as in subsequent calls to Assembler::get() will return the same instance,) so use with care., (*12)

How?

Assembler

Create an Assembler, (*13)

use Assembler\Assembler;

$myAssembler = Assembler::create();
//or to create the singleton instance
$myAssembler = Assembler::get();

Add functions to an Assembler. This may seems strange at first. The pattern for adding functions is:, (*14)

Assembler->nameOfVar(function(){ return ...;});
//e.g.
$myAssembler->foo(function(){return 'foo';});

Or to chain a number of assembly items together:, (*15)

$myAssembler->foo(function(){return 'foo';})
    ->bar(function(){return 'bar';});

You can reference predefined entries by passing in their name as a parameter to subsequent entries:, (*16)

$myAssembler->foo(function(){return 'foo';})
    ->bar(function($foo){return "$foo bar";});

At this point, the Assembler has not executed your functions, so you can redefined them:, (*17)

$myAssembler->foo(function(){return 'foo';})
    ->bar(function($foo){return "$foo bar";})
    ->foo(function(){return 'foo foo';});

To execute the functions, call the assemble() method:, (*18)

$myAssembler->foo(function(){return 'foo})
    ->bar(function($foo){return "$foo bar";})
    ->foo(function(){return 'foo foo';})
    ->assemble();

At this point, the entries become immutable and cannot be overwritten. You can continue to add additional entries, perhaps referencing earlier ones and then call ->assemble() again to fix the entries., (*19)

To retrieve one of more values from the Assembler you use the release() method. release() takes one or more strings, the names of the items that you want to release. To release a single item:, (*20)

$myFoo = Assembler::create()
    ->foo(function(){return 'foo})
    ->bar(function($foo){return "$foo bar";})
    ->foo(function(){return 'foo foo';})
    ->assemble()
    ->release('foo');

Releasing multiple items will return an array of values, so perhaps the easiest way to access them is to use the venerable PHP list() (or []) method, e.g., (*21)

list($myFoo, $myBar) = Assembler::create()
    ->foo(function(){return 'foo})
    ->bar(function($foo){return "$foo bar";})
    ->foo(function(){return 'foo foo';})
    ->assemble()
    ->release('foo', 'bar');

You can merge one Assembler into another using the merge() method:, (*22)

$worker1 = Assembler::create()
    ->foo(function(){return 'foo});
    
$worker2 = Assembler::create()
    ->bar(function($foo){return "$foo bar";})
    
$myFoo = $worker1->merge($worker2->assemble())
    ->assemble()
    ->release('foo');

You can send in parameters during the creation (create() or get()) of an Assembler. This is most useful to prevent you having to use the use clause during function definition. Parameters sent in during the create process are immutable, i.e. you cannot override them with a later declaration., (*23)

$a = 'foo';
$b = 'bar'

$value = Assembler::create(['a'=>$a, 'b'=>$b])
    ->foo(function($a, $b) { return "$a$b";})
    ->assemble()
    ->release('foo');
// $value == 'foobar'

//This will have no effect on 'a'
$value = Assembler::create(['a'=>$a, 'b'=>$b])
    ->a(function() {return 1;})
    ->foo(function($a, $b) { return "$a$b";})
    ->assemble()
    ->release('foo');

//without parameter injection
$value = Assembler::create()
    ->foo(function() use ($a, $b) { return "$a$b";})
    ->assemble()
    ->release('foo');

You can utilise the ParameterGrabable trait to facilitate parameter injection into the create() constructor., (*24)

use Assembler\Traits\ParameterGrabable;
use Assembler\Assembler;

class myClass {
     use ParameterGrabable;

     static function foo($param1, $param2 = null) {
         $a = Assembler::create(self::grabFunctionParameters(__CLASS__, __FUNCTION__, func_get_args());
     }

     function bar($param1, $param2 = null) {
         $a = Assembler::create($this->grabMethodParameters(__CLASS__, __METHOD__, func_get_args());
     }
}

FFor

The FFor class is a simple extension of Assembler, but with restrictions:, (*25)

  • you cannot create a singleton FFor via get(). Use create(). FFor is intended as a language construct
  • you cannot merge() a FFor.
  • there is an additional method; fyield(). fyield() is a pseudonym for ->assemble()->release() and takes the same parameters as release()

See the examples/CarAssemblyLine.php script for a usage example., (*26)

Further documentation

Please note that what you are seeing of this documentation displayed on Github is always the latest dev-master. The features it describes may not be in a released version yet. Please check the documentation of the version you Compose in, or download., (*27)

Uml diag, (*28)

See the tests and Test Contract for further information., (*29)

Check out ZF4 Packages for more packages, (*30)

Running the examples

Although the library itself does not have any other dependencies other than PHP, the examples do. These are included in the composer requires-dev statement so as long as you have included the dev requirements (default for Composer,) you should be good to go., (*31)

Changing the library

  1. fork it
  2. write the test
  3. amend it
  4. do a pull request

Found a bug you can't figure out?, (*32)

  1. fork it
  2. write the test
  3. do a pull request

NB. Make sure you rebase to HEAD before your pull request, (*33)

Or - raise an issue ticket., (*34)

Where?

The library is hosted at Github. It is available at Packagist.org, (*35)

Installation

Install Composer, (*36)

For production

    "chippyash/assembly-builder": ">=3"

Or to use the latest, possibly unstable version:, (*37)

    "chippyash/assembly-builder": "dev-master"

For development

Clone this repo, and then run Composer in local repo root to pull in dependencies, (*38)

    git clone git@github.com:chippyash/Assembly-Builder.git Assembler
    cd Assembler
    composer install

To run the tests:, (*39)

    cd Assembler
    vendor/bin/phpunit -c test/phpunit.xml test/

License

This software library is released under the BSD 3 Clause license, (*40)

This software library is Copyright (c) 2015, Ashley Kitson, UK, (*41)

History

V1.0.0 Initial Release, (*42)

V1.1.0 Add ability to send in parameters on Assembler and Ffor creation, (*43)

V1.1.1 Fix parameter order passing bug, (*44)

V1.1.2 Add ParameterGrabable trait, (*45)

V1.2.0 Update to use Chippyash\Type V3, (*46)

V1.2.1 Add link to packages, (*47)

V1.2.2 Verify PHP 7 compatibility, (*48)

V1.2.3 Update dependency on Monad, (*49)

V1.2.4 Update build scripts, (*50)

V1.2.5 update composer - forced by packagist composer.json format change, (*51)

V2.0.0 BC Break. Support withdrawn for old php versions, (*52)

V2.1.0 Change of license from GPL V3 to BSD 3 Clause, (*53)

V3.0.0 BC Break. Support for PHP <V8 withdrawn, (*54)

The Versions

04/07 2018

dev-master

9999999-dev http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

BSD-3-Clause GPL V3+ GPL-3.0-or-later

The Requires

  • php >=5.6

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

04/07 2018

2.1.0

2.1.0.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

BSD-3-Clause

The Requires

  • php >=5.6

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

03/04 2018

2.0.0

2.0.0.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL-3.0-or-later

The Requires

  • php >=5.6

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

08/02 2018

1.2.5

1.2.5.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL-3.0-or-later

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

05/01 2018

1.2.4

1.2.4.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

24/05 2017

1.2.3

1.2.3.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

08/06 2016

1.2.2

1.2.2.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

22/03 2016

1.2.1

1.2.1.0 http://zf4.biz/packages?utm_source=packagist&utm_medium=web&utm_campaign=blinks&utm_content=assembler

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

03/03 2016

1.2.0

1.2.0.0 http://the-matrix.github.io/

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

23/01 2016

1.1.2

1.1.2.0 http://the-matrix.github.io/

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

23/01 2016

1.1.1

1.1.1.0 http://the-matrix.github.io/

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

22/01 2016

1.1.0

1.1.0.0 http://the-matrix.github.io/

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

22/01 2016

1.0.1

1.0.1.0 http://the-matrix.github.io/

Lightweight functional assembly builder pattern with Scala like For Comprehension

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson

functional for comprehension builder pattern

28/06 2015

1.0.0

1.0.0.0

Lightweight assembly builder pattern

  Sources   Download

GPL V3+

The Requires

  • php >=5.4

 

The Development Requires

by Ashley Kitson