Download the PHP package lukaszmakuch/haringo without Composer

Haringo

Serialize the way how you create an object, not the object itself!

What's Haringo?

Haringo is a libary that aims to solve main problems with classical serialization:

• lost references which cause presence of __wakeup() methods which use global variables
• data corruption after moving or renaming classes of serialized objects

How's that achieved?

No more __wakeups!

Haringo allows to describe how an object should be built and then serialize that description instead of the created object. Thanks to this fact, any object built based on the serialized build plan doesn't need to know anything about things like global registry of resources or the current user session.

Freedom of renaming!

With Haringo you can make your serialized data totally free of things like:

• class paths
• method names
• parameter names

It's possible thanks to configurable map based sources and selectors.

Table of contents

1. Getting Haringo
   • Building Haringo
   • Haringo builder
   • Getting the basic Haringo
   • Maps
   • Extensions
   • Using Haringo
   • Build plans
     • New instance
     • Static factory method product
     • Factory object product
     • Builder object product
   • Class path sources
     • Exact class path
     • Class path from a map
   • Method selectors
     • Constructor selector
     • Method by exact name
     • Method from a map
   • Parameter selectors
     • Parameter by position
     • Parameter by exact name
     • Parameter from a map
   • Value sources
     • Scalar
     • Array
     • Build plan result
   • Working with build plans
     • Building objects
     • Serialization
     • Fetching build plans by objects
   • Extending Haringo

Installation

Use composer to get the latest version:

Building Haringo

To build Haringo, you can use the default implementation of the \lukaszmakuch\Haringo\Builder\HaringoBuilder interface.

Getting the builder

Getting a basic Haringo instance

If you're not going to somehow extend your Haringo instance, you can directly call the HaringoBuilder::build():Haringo method.

Setting Maps

In order to use a ClassPathFromMap, MethodFromMap or a ParamFromMap, you need to build Haringo with instances of maps you are able to configure.

ClassPathSourceMap

Creating the map

All you need to create a map of class path sources, is to create a new ClassPathSourceMap instance.

Adding the map to Haringo

The new map must be passed to the Haringo builder before using it to build a new Haringo. However, it may be configured later, as it's passed as a reference.

MethodSelectorMap

All you need to create a map of class path sources, is to create a new MethodSelectorMap instance.

Creating the map

Adding the map to Haringo

The new map must be passed to the Haringo builder before using it to build a new Haringo. However, it may be configured later, as it's passed as a reference.

ParamSelectorMap

All you need to create a map of class path sources, is to create a new ParamSelectorMap instance.

Creating the map

Adding the map to Haringo

The new map must be passed to the Haringo builder before using it to build a new Haringo. However, it may be configured later, as it's passed as a reference.

Extensions

ValueSourceExtension

It's possible to add support of different ValueSource implementations. Every extension must implement the \lukaszmakuch\Haringo\Builder\Extension\ValueSourceExtension interface and must be passed to the Haringo builder before using it to build a new Haringo. See the description of creating your own Haringo extension.

Using Haringo

Build plans

Every build plan describes how to get an instance of some class. For documenting (and testing) purposes let's use that simple class:

NewInstanceBuildPlan

Describes how a new instance of some class should be built. It takes a source of class to instantiate and optional method calls which will be called on the new instance.

Code equal to the result of the following build plan:

Example build plan:

StaticFactoryProductBuildPlan

Describes how to get a product of a static factory method. It requires two things:

1. class source of the factory
   • method call of the static factory method which returns the product

Let's create a class which provides a static factory method:

Code equal to the result of the following build plan:

Example build plan:

FactoryObjectProductBuildPlan

Describes how to use a factory object to get some product. It requires two things:

1. value source which is resolved to a factory object
   • method call which returns the product

Let's create a class which provides a factory method:

Code equal to the result of the following build plan:

Example build plan:

BuilderObjectProductBuildPlan

Describes how to use a builder object to get some product. There are two mandatory elements of plan:

1. value source which is resolved to a builder object
   • method call which returns the product As it's a builder, it's also possible to call some methods which determine the further result state.

Let's create a builder:

Code equal to the result of the following build plan:

Example build plan:

Class path sources

ExactClassPath

Represents a full class path of some class.

ClassPathFromMap

Allows to assign any class path to a string key.

The key stay unchanged while you move or rename your class, so a previously serialized build plan doesn't get out of date.

In order to Haringo be able to resolve a class path from a map, it must be built with the map.

Adding a new path source the map

Using a class path from the map

Method selectors

ConstructorSelector

Selects the constructor.

MethodByExactName

Selects some method by it's exact name. It may be "__constructor" as well, but for convenience it's preferable to use the ConstructorSelector.

MethodFromMap

Allows to assign any full method identifier to a string key. A full method identifier is a full class path source together with some method selector.

Because every full method identifier contains a class path source, it's possible to have two mapped methods under the same key which will represent different methods of different classes.

The key stays unchanged while you rename your method, so a previously serialized build plan doesn't get out of date.

In order to Haringo be able to get a method selector from a map, it must be built with the map.

Adding a new method selector

Using a method selector from the map

Parameter selectors

ParamByPosition

Selects one parameter by it's position from left (from index 0).

ParamByExactName

Selects one parameter by it's exact name.

ParamFromMap

Allows to assign any full parameter identifier to a string key. A full parameter identifier is a full class path source together with some method selector and parameter selector.

Because every full parameter identifier contains a class path source and a method selector, it's possible to have two mapped parameters under the same key which will represent different parameters of different methods (even of different classes).

The key stays unchanged while you rename or move the parameter or method, so a previously serialized build plan doesn't get out of date.

In order to Haringo be able to get a parameter selector from a map, it must be built with the map.

Adding a new parameter selector

Using a parameter selector from the map

Value sources

ScalarValue

Represents a value like: boolean, integer, float, string.

ArrayValue

Represents an array of other ValueSource objects. Other sources may also be ArrayValue objects. Keys may be both integers and strings.

BuildPlanResultValue

Represents a value which is the result of building something based the given BuildPlan object. It may be used in order to create a build plan of a complex composite.

Working with build plans

Building objects based on build plans

To get the product, call the buildObjectBasedOn method with a BuildPlan:

Serialization of build plans

There are two methods which allow to serialize and deserialize build plans:

• Haringo::serializeBuildPlan(BuildPlan): String
• Haringo::deserializeBuildPlan(String): BuildPlan

Fetching build plans by built objects

It's possible to figure out what was the build plan used to built some object:

Extend Haringo

Haringo is easily extensible!

ValueSourceExtension

It's possible to add support of a totally new ValueSource. All what you need to do, is to implement the \lukaszmakuch\Haringo\Builder\Extension\ValueSourceExtension interface and add it to the HaringoBuilder as described in the Building Haringo chapter. For more details, check documentation of thats interface.