README

Quality Assurance

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'.

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

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

What?

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

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.

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

So why is it useful?

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.

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.

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.

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.

How?

Assembler

Create an Assembler

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:

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

Or to chain a number of assembly items together:

$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:

$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:

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

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

$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.

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:

$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.

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:

$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.

$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.

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:

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.

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.

See the tests and Test Contract for further information.

Check out ZF4 Packages for more packages

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.

Changing the library

fork it
write the test
amend it
do a pull request

Found a bug you can't figure out?

fork it
write the test
do a pull request

NB. Make sure you rebase to HEAD before your pull request

Or - raise an issue ticket.

Where?

The library is hosted at Github. It is available at Packagist.org

Installation

Install Composer

For production

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

Or to use the latest, possibly unstable version:

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

For development

Clone this repo, and then run Composer in local repo root to pull in dependencies

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

To run the tests:

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

License

This software library is released under the BSD 3 Clause license

History

V1.0.0 Initial Release

V1.1.0 Add ability to send in parameters on Assembler and Ffor creation

V1.1.1 Fix parameter order passing bug

V1.1.2 Add ParameterGrabable trait

V1.2.0 Update to use Chippyash\Type V3

V1.2.1 Add link to packages

V1.2.2 Verify PHP 7 compatibility

V1.2.3 Update dependency on Monad

V1.2.4 Update build scripts

V1.2.5 update composer - forced by packagist composer.json format change

V2.0.0 BC Break. Support withdrawn for old php versions

V2.1.0 Change of license from GPL V3 to BSD 3 Clause

V3.0.0 BC Break. Support for PHP <V8 withdrawn

chippyash / assembly-builder

Maintainers

Details