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