Download the PHP package kylekatarnls/morph without Composer

Morph

Generic tooling to compose transformations

$info is an array as follows:

Installation

Usage

All the classes under the Morph namespace implements Morph\Morph:

And are also callable.

Any kind of callable (Closure, function name, invokable objects) or instance of a class that implements Morph\Morph can be used as a transformation (e.g. be used in a Morph\Sequence, Morph\Merge etc.)

The transformer above can also be written in a class:

The Morph\Sequence can be written the same way overriding the getTransformers method.

Note that this syntax allows to lazy-load the inner transformers that won't even be created if new UserTransformer is not called. And they will still be cached once created so if you call ->transform() multiple times, the same transformers instances are re-used.

In the example above 'sha1' is passed as an additional parameter of transform() and is passed to each sub-transformer while in this case, it's only used by HashUserId, another option is to create a static config for HashUserId and UserTransformer:

Output:

Why/when to use?

While it may be overkill to use Morph if you only use PublicPropertiesToArray or just few simple transformations, it becomes handy when you have complex Models or DTO and want to properly isolate the handling of input and output transformations, lazy-load them and/or share part of it among the code base.

It provides a clean way to represent steps a transformations process or ETL system.

Last, Morph comes with Reflection tooling which can allow to define a transformation right into the class definition, using attributes or PHPDoc and so synchronize a class with its definition and transformation. Typically, when using an auto-documented API system such as GraphQL or Protobuf.

See more in the Reflection chapter.

Built-in transformers

FilterKeys

Filter an array to keep only keys for which the given callable returns true (or is truthy if no callable was passed in the constructor).

FilterValues

Filter an array to keep only values for which the given callable returns true (or is truthy if no callable was passed in the constructor).

Getters

Return the list of the methods (as an array of \Morph\Reflection\Method) that start with "get" or one of the given prefixes if you passed a list or prefixes in the constructor.

Note that Getters does not call the methods, it just return the definitions of those methods.

See more in the Reflection chapter.

GettersToArray

Return values for each public method of an object that start with "get" or one of the given prefixes if you passed a list or prefixes in the constructor.

LowerFirstLetter

Lowercase the first letter of the input if it's a string. If a mapping array is given in the constructor, this will be used prior to the lowercase action.

UpperFirstLetter

Uppercase the first letter of the input if it's a string. If a mapping array is given in the constructor, this will be used prior to the uppercase action.

LowerKeysFirstLetter

Lowercase the first letter of each key of a given array. If a mapping array is given in the constructor, this will be used prior to the lowercase action.

UpperKeysFirstLetter

Uppercase the first letter of each key of a given array. If a mapping array is given in the constructor, this will be used prior to the uppercase action.

Merge

Merge (using array_merge) the results of a list of transformers.

It will be mostly useful to combine other Morph classes:

Only

Keep from an array only the given keys.

It can be an array or a single key:

Pick

Return the value at a given key or null if the key does not exist.

Properties

Return the list of the properties defined in a class (as an array of \Morph\Reflection\Property)

See more in the Reflection chapter.

PublicProperties

Return the list of the public properties defined in a class (as an array of \Morph\Reflection\Property)

See more in the Reflection chapter.

PublicPropertiesToArray

Return the list of the public properties defined in a class (as an array of \Morph\Reflection\Property)

Sequence

Group transformation and execute them in the given order. Each transformation receive as input the result of the previous transformation.

TransformKeys

Transform each key of an array using the given transformation.

TransformValues

Transform each value of an array using the given transformation.

Transform each value of an array using the given transformation.

MorphBase

Abstract MorphBase that can be extended to craft new transformations and inherit from handy methods:

useTransformerWith() can use as a transformer either any callable or a class instance that have a transform() method.

mapWithTransformer() is the same but take an array and apply the transformer to each value of this array.

Reflection

Output:

Iteration

When a transformation is iterable (Morph\Iteration\*Iterable classes), or a Sequence of iterable transformations and get passed an iterable value (Traversable, Generator, etc.), it will proceed lazily, so it won't start the iteration but return a new iterable and transformation will be proceeded as you iterate on the returned iterable value.

Every iterable can also take array values and then use array_* functions for better performance.

Transformation

Morph\Transformation is a build object, it allows to prepare a transformation with multiple steps using chaining. It's handy when wanting to optimize memory consumption long iteration (reading line by line a big log file for instance).

As it's a lazy builder, it won't start any actual transformation until you call ->get() on it.

Output:

CountIterable

Count iterations (use count on Countable values) otherwise iterate.

Use ->count() on Transformation builder object to add it as a step.

SumIterable

Count iterations (use array_sum on array value) otherwise iterate.

Use ->sum() on Transformation builder object to add it as a step.

ValuesIterable

Get values (use array_values on array value) otherwise iterate dropping indexes.

As keys are dropped, you get the output:

Use ->values() on Transformation builder object to add it as a step.

KeysIterable

Get values (use array_keys on array value) otherwise iterate dropping input values and yielding indexes as output values.

Output:

Use ->keys() on Transformation builder object to add it as a step.

FilterIterable

Filter iterable value keeping only items matching a given filter.

Only values matching the callback remain:

Alternatively, FilterIterable can also take a property or key named argument:

FilterIterable(property: 'active') is equivalent to: FilterIterable(static fn ($item) => $item->active ?? false)

FilterIterable(key: 'active') is equivalent to: FilterIterable(static fn ($item) => $item['active'] ?? false)

Additionally, you can drop indexes when filtering (in the same loop) by setting dropIndex: true argument.

FilterIterable() (with no callback, property nor key) will keep truthy elements.

Use ->filter(...) on Transformation builder object to add it as a step.

FlipIterable

Flip keys and values (use array_flip on array value) otherwise iterate.

Output:

Use ->flip() on Transformation builder object to add it as a step.

MapIterable

Transform each value of an iterable with a transformation callback.

The callback receive first the value, second the index, then extra arguments as passed when invoking the transformer.

Output:

Alternatively, MapIterable can also take a property or key named argument:

MapIterable(property: 'active') is equivalent to: MapIterable(static fn ($item) => $item->active ?? false)

MapIterable(key: 'active') is equivalent to: MapIterable(static fn ($item) => $item['active'] ?? false)

Use ->map(...) on Transformation builder object to add it as a step.

ReduceIterable

Applies iteratively the callback function to the elements of the array/iterable, to reduce it to a single value (use array_reduce on array value) otherwise iterate.

Initial value might be passed either on construct or on invocation.

Use ->reduce() on Transformation builder object to add it as a step.