Download the PHP package zahran/data-mapper without Composer

JSON Data Mapper

Author: Mohamed Zahran

Requirements

• PHP 7.2 or higher.
• cakephp/utility 4.0 or higher.

Table of Contents

• Installation
• Usage
• Examples
  1. Mapping JSON Objects
  2. Mapping JSON Arrays
  3. Applying Conditions
  4. Cast Values To Another Type
  5. Applying Mutators
  6. Additional Features
• Extending The Package
  1. Custom Cast Type
  2. Add Custom Condition
  3. Add Custom Mutator
• Contributing
• Credits
• License

Installation

Install using composer:

Usage

After installing the package, make sure you get an instance of the Container and register the instances that the tool needs. Each instance have an alias/id so it can be easily overridden by custom implementations. The overriding part will be explained in detail later on.

Mappings Examples

1. Mapping JSON Objects

In this example, we'll learn how to map simple objects:

Original JSON:

Output:

Mappings:

NOTE: REMOVE THE COMMENTS BELOW AFTER YOU COPY/PASTE THE MAPPINGS!

Comments below are used for demonstration purposes only. Please remove them before you use the sample!

Interesting, isn't it? P.S. You don't have to include all attributes of the JSON object. Map the attributes that you only need.

2. Mapping JSON Arrays

In this example, we'll learn how to map a JSON Array "items" to "ItemsArray" and rename the "name" attribute.

Original JSON:

Output:

Mappings:

NOTE: REMOVE THE COMMENTS BELOW AFTER YOU COPY/PASTE THE MAPPINGS!

Comments below are used for demonstration purposes only. Please remove them before you use the sample!

3. Applying Conditions

We'll learn how to apply conditions to an attribute. In this example, we'll replace the value of "completed" to either Completed or Pending based on the original value of the attribute.

A list of supported condition types:

• Contains: contains
• Equals: eq
• Greater Than: gt
• Greater Than or Equals: gte
• Inset: in
• Not Inset: not_in
• Less Than: lt
• Less Than or Equals: lte
• Not Equals: neq
• Not Null: notnull
• Null: null
• Is Boolean: is_boolean
• Is Double: is_double
• Is Float: is_float
• Is Numeric: is_numeric
• Is String: is_string

Original JSON:

Output:

Mappings:

NOTE: REMOVE THE COMMENTS BELOW AFTER YOU COPY/PASTE THE MAPPINGS!

Comments below are used for demonstration purposes only. Please remove them before you use the sample!

4. Cast Values To Another Type

You can cast values to another type. For example, you may need to change "1" to become "true", or convert a date to another date format.

A list of supported types:

• Boolean: boolean
• Date: date
• Integer: integer
• String: string
• Float: float

Original JSON:

Output:

Mappings:

NOTE: REMOVE THE COMMENTS BELOW AFTER YOU COPY/PASTE THE MAPPINGS!

Comments below are used for demonstration purposes only. Please remove them before you use the sample!

5. Applying Mutators

Sometimes, you may need to change a value based on some business logic. Mutators allow you to apply custom PHP logic around the attribute value. It also gives the ability to use native PHP built-in functions.

A list of supported mutators:

• Arithmetic Multiplication: multiply
• PHP Built-in Functions

Original JSON:

In this example, we are going to convert the title to uppercase and multiply the views by 5.

Output:

Mappings:

NOTE: REMOVE THE COMMENTS BELOW AFTER YOU COPY/PASTE THE MAPPINGS!

Comments below are used for demonstration purposes only. Please remove them before you use the sample!

6. Additional Features

Default Values

It's possible to set a default value for an attribute. This can be useful if the path you set doesn't exist, or you want to set a default value anyway.

Limiting Array Items

Sometimes, you may want to get certain items from an array depending on your use-case. It's possible to define a list of indices. Please note that the first index starts with 0. To do so, append an array of indices as a second argument to the "path" array on the target attribute. Possible ways to limit items:

Original JSON:

In this example, we are going to map all items but limit the categories to the first two items of the array and inject some hard-coded values as the default value for an attribute that's going to be created during runtime.

Output:

Mappings:

NOTE: REMOVE THE COMMENTS BELOW AFTER YOU COPY/PASTE THE MAPPINGS!

Comments below are used for demonstration purposes only. Please remove them before you use the sample!

Appending Values On Limiting Array Items

In the example, above we learnt how to get certain items from an array using indices, but you may have a case where you want to append a value at the end of the list. This is can be done this way:

Notes On The Mappings

You should now be aware of how Mappings are built. Nevertheless, I feel that you may need to bear these things in mind while building yours.

• You shouldn't add any modifiers (Cast type, conditions or mutators) to an attribute of type array because they won't be effective. Instead, add modifiers to the attributes that sit under that JSON array - AKA Nested Attributes.

Extending The Package

The package is built to be extensible to allow you to add custom cast types, conditions and/or mutators. Moreover, you can retire any of the core classes, just make sure you're implementing the right interface.

Custom Cast Type

1. You'll need to implement \Zahran\Mapper\Contract\CastType. It has two public methods: setModel and cast. Create the new Cast Type you want and follow the example below:

2. Add your custom cast type to the Container. Replace {type} with the name you want to use in the mappings (i.e. custom). You can replace a core class by overriding the id. For example, if you want to replace class \Zahran\Mapper\CastType\Boolean with your own version, you'll need to register your custom implementation under cast_type.boolean.

Add Custom Condition

1. You'll need to implement \Zahran\Mapper\Contract\Condition. It has two public methods: setModel and apply. Create the new Condition you want and follow the example below:

2. Add your custom condition to the Container. Replace {condition_type} with the name you want to use in the mappings (i.e. custom). You can replace a core class by overriding the id. For example, if you want to replace class \Zahran\Mapper\Condition\Equals with your own version, you'll need to register your custom implementation under condition.eq.

Add Custom Mutator

1. You'll need to implement \Zahran\Mapper\Contract\Condition. It has two public methods: setModel and apply. Create the new Condition you want and follow the example below:

2. Add your custom mutator to the Container. Replace {name} with the name you want to use in the mappings (i.e. custom). You can replace a core class by overriding the id. For example, if you want to replace class \Zahran\Mapper\Mutator\Multiply with your own version, you'll need to register your custom implementation under mutator.multiple.

Contributing

All changes that makes the Mapper more accurate is always highly appreciated and welcome.

License

The JSON Mapper is open-sourced software licensed under the MIT license.