README

PHP package for constructing objects using configurations.

1. Requirements

php 5.4+

This package is not tested with outdated versions of PHP.

If you need to use nayjest/builder in environments with php <= 5.3, test it on your own.

2. Installation

The recommended way of installing the component is through Composer.

Run following command:

composer require nayjest/builder

3. Overview

3.1 Purpose

Building complex objects from configurations in architecturally beutiful way.

3.2 Explanation

If you are confident with builder design pattern, this package allows you to create builders for your classes in declarative style, based on build configuration.

3.3 Usage

3.3.1 Class Blueprints

When you need to construct objects of some type, first of all, you will create blueprint for that type. In terminology of this package blueprint specifies how to construct object of some specified type. It stores class name and set of build instructiuons.

use Nayjest\Builder\Blueprint;
$blueprint = new Blueprint(
  '\My\ExamplePackage\Person',  # Constructed class name
  []                            # Array of build instructions
);

3.3.2 Builders

Next, you will instantiate a builder with previously created blueprint as constructor argument. In terminology of this package, builder is a instance of Nayjest\Builder\Builder class, initialized with a blueprint of constructed class. This object has public build($input) method that accepts constructed class configurations, builds instance and returns it.

Builders are suitable for reusing. You can build multiple objects specified by same blueprint using same builder.

use Nayjest\Builder\Builder;

$builder = new Builder($blueprint);

$john = $builder->build([
  'name' => 'John',
  'age' => 27
]);

var_dump($john instanceof \My\ExamplePackage\Person); // result: true
var_dump($john->getAge());  // result: 27

3.3.3 Scaffold and Instructions

During taget object building, builder creates temporary object, called scaffold. Scaffold contains all information needed to build object (input config, class name, constructor arguments, target instance when it's ready).

This class is importand since all build instructions works with scaffold, scaffold provides interface for accessing all required data to instructions.

And finally, instructions. In terminology of this package, instruction is an instance of class that implements Nayjest\Builder\Instructions\Base\InstructionInterface and can modify data inside scaffold.

There is a set of predefined instructions, but you can create your own (the dirty way is usage of Nayjest\Builder\Instructions\Base\Instruction\CustomInstruction initialized by user function that will perform operations you want).

Also, instantiating target object and setting public properties or properties that has setters with corresponding names in camel case (i.e. setSomeAttribute($val) for 'some_attribute' input field) does not requires specific instruction in class blueprint, it's operations, performed by default.

4. Build Instructions

`Nayjest\Builder\Instructions\CustomInstruction`

Applies user function to scaffold.

`Nayjest\Builder\Instructions\SetValue`

Can be used to specify default values in build configuration or overwrite existing.

`Nayjest\Builder\Instructions\Remove`

Removes value from input configuration if exists.

`Nayjest\Builder\Instructions\Mapping\Build`

Replaces value by object builded using specified class blueprint.

`Nayjest\Builder\Instructions\Mapping\BuildChildren`

Replaces array elements inside target field by objects builded using specified class blueprint.

`Nayjest\Builder\Instructions\Mapping\ClassName`

Uses value in specified field as target class name.

`Nayjest\Builder\Instructions\Mapping\ConstructorArgument`

Uses value in specified field as constructor argument.

`Nayjest\Builder\Instructions\Mapping\CustomMapping`

Applies user function to specified field.

`Nayjest\Builder\Instructions\Mapping\Rename`

Renames specified field inside input configuration.

5. Testing