Builders, Context, and PHP 7

What's new?

This release adds a couple new concepts to the Incoming processing pipeline, and updates the minimum supported PHP runtime version to PHP 7.0.0.

Builders and type processing

A new 'Builder' and type-processor concept has been introduced, to better support immutable values/models.

Incoming was designed to take loose input, transform it (potentially sanitize it), and then populate value objects and data-structures with that input. Unfortunately, the design never really took immutable objects or un-instantiated objects into account. While there are definitely ways to work around the shortcomings of the design, no solution was quite ideal.

Well, this release solves this issue by introducing a new "builder" concept, designed to use alongside "hydrators". New interfaces, abstractions, and processes were introduced to make it so that building values, whether immutable or not, could be more easily achieved.

In particular, the following new (or changed) interfaces have been introduced:

• Incoming\Hydrator\Builder: The basis of the new value instantiation strategy, akin to a hydrator for un-instantiated values/models
• Incoming\Hydrator\BuilderFactory: A factory for builders, so that builders can be automatically resolved at runtime, similar to how hydrators work in the current Processor logic
• Incoming\TypeProcessor: A new interface for enabling the ability to process specific "types", rather than actual model values, allowing you to process with an argument such as User::class
• Incoming\ModelProcessor: A renaming of the old ProcessorInterface, designed to work specifically with already instantiated/constructed models

The Processor has been updated to implement both the new TypeProcessor and the new ModelProcessor

Context

A new 'Context' concept has been introduced to hydrators, builders, and the process pipeline, to enable more advanced value/model processing in a more functional manner, without having to resort to holding state in a hydrator/builder.

This new feature enables hydrators and builders to take in an optional new "context" parameter as a generic key-value map. This "context" parameter can be useful for passing additional information to the hydrate/build process, which can enable more advanced conditional processing such as authorization-dependent input handling. The new interfaces are extensions and are compatible with their parents, so that they can be used generically and with the same factories and integrations. 😃

This idea of "context" isn't new or novel, as its something often seen in other languages and frameworks, and is likely most notably seen (at least in the PHP world) in the PSR-3 Logger specification and interface. That being said, it is a powerful generic abstraction for this type of process.

This new "context" idea should allow for more advanced hydrate and build processes without needing to resort to using constructor parameters (which make dependency injection abstraction difficult and create state 🤢) or using other instance state mechanisms that can cause stateful bugs/issues. This "context" parameter inherently enables more functional programming patterns to be used with Incoming. 😄

PHP 7

This release also upgrades the minimum required version of PHP to 7.0.0.

This change is intended to modernize the type-system and features utilized by the library.

In response of the runtime upgrade, the following changes have also been made:

• Upgraded development composer packages, to modern versions
• Added scalar type declarations to parameters, where possible
• Added return type declarations
• Enabled "strict typing" on all files
• Updated some doc-blocks to newer styles (such as @type -> @var)
• Updated tests to use new features and work with the new testing framework updates

StructureFactory Map Detection and PHP 7 Test Support

This release fixes a bug with how the StructureFactory detected map-like structures with mixed key types and fixes a unit test to be compatible with PHP 7's new TypeError engine exception.

Delegation and Type-Hinted Hydrators

This release adds a new AbstractDelegateHydrator abstract hydration class that allows for the hydration to be delegated to a callback or other callable. By default, a named method is attempted to be found, but any callable could be returned through overrides.

This enables a lot of interesting uses, most notably this allows hydrators to be created that have strongly type-hinted hydration arguments while still perfectly satisfying the HydratorInterface. Essentially this allows the bypassing of the type variance rules enforced by PHP in a way that provides a generics-like definition. Ultimately, if/when PHP gets generics this will no longer be necessary, as one could simply implement a hydrator using typed arguments like: HydratorInterface<IncomingDataType, ModelType>.

This feature was born out of a frustration with being unable to properly implement the HydratorInterface in an application I was using Incoming in without dropping the type hints:

Initial Release!

Incoming is a PHP library designed to simplify and abstract the transformation of loose, complex input data into consistent, strongly-typed data structures.

Born out of inspiration from using Fractal, Incoming can be seen as a spiritual inversion.
When working with data models of any kind (database, remote service, etc), it can be a huge pain to take raw input data and turn it into anything usable. Even worse is when something changes and you have to duplicate code or try and keep backwards compatibility. Incoming is here to make all this easier while enabling you to create more concern-separated, reusable, and testable code.