Data Block Package

PHP Package for Managing Nested Data

This PHP package provides classes and methods for managing, querying, filtering, and setting nested data structures with ease. Whether you're working with complex JSON data, hierarchical configurations, or deeply nested arrays, this package offers a streamlined approach to handling nested data easly.

The Block class

The Block class offers a comprehensive set of methods to create, manage, and access nested data structures.

The Block class provides various methods, including:

• Creating structures from Arrays, JSON, and YAML files.
• Querying nested data with ease.
• Filtering data based on specific criteria.
• Setting and updating values within deeply nested structures.

Installing and using the Block class

For adding to your projects, the Block class with its method and helper you can run the composer require command:

For supporting the development you can star the repository: https://github.com/Hi-Folks/data-block

Then in your PHP files, you can import the HiFolks\DataType\Block Namespace:

Method for creating Block objects

To show the capabilities of the following methods, I will use this nested associative array:

The static make() method

With the static make() method, you can generate a Block object from an associative array:

The $data object is an instance of the Block class.

In the case you want to initialize an empty Block object, you can call the make() method with no parameters:

Once you initialize the Block object, you can use its methods.

The get() method

The get() method supports keys/indexes with the dot (or custom) notation for retrieving values from nested arrays. It returns the original type of data. If you need to obtain a Block object, you should use the getBlock() method instead of get(). For example:

For example, with the $fruitsArray sample data, the $data->get("avocado") is:

• an array;
• has 5 elements;

For example, the $data->get("avocado.color") is:

• a string;
• has the value "green";

The $data->get("avocado.rating") is:

• a numeric;
• specifically an integer;

The $data->get("banana.rating") is:

• a numeric;
• specifically a float;

You can customize the notation with a different character:

If you are going to access a not valid key, a null value is returned:

You can define a default value in the case the key doesn't exist:

And you can combine the default value and the nested character:

The getBlock() method

If you need to manage a complex array (nested array) or an array obtained from a complex JSON structure, you can access a portion of the array and obtain the Block object via the getBlock() method.

Let's see an example:

If the element accessed via getBlock() is a scalar type (integer, float, string, etc.), a Block object (with just one element) will be returned using getBlock().

For example, $data->getBlock("avocado") returns a Block object with five elements.

For example, $data->getBlock("avocado.color") returns a Block object with just one element.

If you are going to access a non-valid key, an empty Block object is returned, so the $data->getBlock("avocado.notexists") returns a Block object with a length equal to 0.

The set() method

The set() method supports keys with the dot (or custom) notation for setting values for nested data. If a key doesn't exist, the set() method creates one and sets the value. If a key already exists, the set() method will replace the value related to the key.

Parameters

• key (int|string): The key to which the value should be assigned. If a string is provided, you can use dot notation to set nested values.
• value (mixed): The value to be assigned to the specified key.
• charNestedKey (string, optional): The character used for dot notation in nested keys. Defaults to ..

Returns

• self: Returns the instance of the class for method chaining.

Example Usage

So when you try to set a nested key as "content.0.content.0.text", it will be created elements as a nested array.

Once you set the values, you can access them via get() (or getBlock()) methods:

Extracting Keys

Via the keys() method, you can retrieve the list of the keys:

You can retrieve the keys of a nested element, combining the usage of getBlock() and the keys():

Exporting data

Exporting to array with toArray()

The toArray() method can access the native array (associative and nested).

This is helpful when manipulating data with the Block class, and at a certain point, you need to send the data to your function or a function from a third-party package that expects to receive a native array as a parameter.

Exporting to JSON string with toJson()

If you need to generate a valid JSON string using the content of the Block object, you can use the toJson() method.

This is helpful when you are manipulating data with the Block class and at a certain point need to send the data in JSON string format to your own function or a function from a third-party package that expects to receive a JSON string as a parameter.

Exporting to YAML string with toYaml()

If you need to generate a valid YAML string using the content of the Block object, you can use the toYaml() method.

This is helpful when manipulating data with the Block class and, at a certain point, need to send the data in YAML string format to your function or a function from a third-party package that expects to receive a YAML string as a parameter.

Loading Data

Loading Data from JSON file

Loading Data from JSON URL

You can build your Block data from a remote JSON (like an API). For example, you can use the fromJsonUrl() method to build a Block object from the latest commits via GitHub API. Retrieving JSON API into a Block object is useful for applying the methods provided by the Block class, for example, filtering the data. In the example, I'm going to filter the commit based on the name of the author of the commit:

Loading Data from YAML file

Adding and appending elements

Appending the elements of a Block object to another Block object

If you have a Block object, you can add elements from another Block object. One use case is if you have multiple JSON files and want to retrieve paginated content from an API. In this case, you want to create one Block object with all the elements from every JSON file.

Appending the elements of an array to a Block object

If you have an array, you can add elements to a Block object. Under the hood, a Block object is an array (that potentially can be a nested array). Appending an array will add elements at the root level:

Appending an element

If you need to append an element as a single element (even if it is an array or a Block object), you can use the appendItem() function:

Querying, sorting data

The where() method

You can filter data elements for a specific key with a specific value. You can also set the operator

With the where() method, the filtered data keeps the original keys. If you want to avoid preserving the keys and set new integer keys starting from 0, you can set the fourth parameter (preserveKeys) as false.

With where() method you can use different operators, like "==", ">", "<" etc. You can use also the in operator in the case your nested data contains arrays. For example if you have posts and each post can have multiple tags, you can filter posts with a specific tag:

The orderBy() method

You can order or sort data for a specific key. For example, if you want to retrieve the data at story.content.body key and sort them by component key:

You can also order data for a nested attribute. Consider retrieving a remote JSON like the dummy JSON posts and then ordering the posts via the reactions.likes nested field in descending order:

The select() method

The select() method allows you to select only the needed fields. You can list the field names you need as parameters for the select() method. For example:

You can combine the select(), the where(), and the orderBy() method. If you want to retrieve elements with product and price keys, with a price greater than 100 and ordered by price:

The groupBy() method

Groups the elements of the Block object by a specified field.

This method takes a field name as an argument and groups the elements of the Block object based on the values of that field. Each element is grouped into an associative array where the keys are the values of the specified field and the values are arrays of elements that share that key.

The exists() method

You can use the exists() method to check if an element that meets a certain condition exists. This method is a convenient way to determine if any records match your query without needing to count them explicitly.

Here’s how you can use it:

This will return true if a banner component exists, and false if it does not.

Looping Data

The Block class implements the Iterator interface. While looping an array via Block, by default, if the current element should be an array, a Block is returned so that you can access the Block method for handling the current array item in the loop. For example, with the previous code, if you loop through $data (which is a Block object), each element in each iteration of the loop will be an array with two elements, with the keys product and price. If in the loop you need to manage the current element via Block class, you should manually call the Block::make, for example:

You can apply filters and then loop into the result:

If you want to loop through $data and obtain the current $item variable as an array you should set false as a second parameter in the static make() method:

The iterateBlock() method

With the iterateBlock() method, you can switch from array or Block for nested lists inside the main Block object if you already instanced it as a Block object. In the example above, you have the $table Block object. You can loop across the items of the $table object. If each item in the loop is itself an array (so an array of arrays), you can retrieve it as an array or a Block, depending on your needs:

Using forEach() method

The Block class implements the forEach()method.

If you need to walk through the Block object, you can use the forEach() method. You can specify the function as an argument of the forEach() method to manage each single element.

Validating Data

You can validate the data in the Block object with JSON schema. JSON Schema is a vocabulary used to annotate and validate JSON documents.

More info about JSON Schema: https://json-schema.org/learn/getting-started-step-by-step

If you need some common/popular schemas, you can find some schemas here: https://www.schemastore.org/json/ For example:

• Schema for validating the composer.json file: https://getcomposer.org/schema.json
• Schema for validating the GitHub Actions workflows: https://json.schemastore.org/github-workflow.json

Or you can build your own schema according to the JSON schema specifications: https://json-schema.org/learn/getting-started-step-by-step#create-a-schema-definition

Or you can define your own schema:

And then validate it with your Block object:

If you are starting to use the Data Block and testing it just to gain confidence, implementing different scenarios, or testing a non-valid JSON, try changing the "rating" type from number to integer (the validation should fail because in the JSON, we have ratings with decimals). And, yes, to change on the fly the schema you can use the Block object :)

Applying functions

The applyField() method applies a callable function to the value of a specified field and sets the result to another field. This method supports method chaining.

Parameters

• key (string|int): The key of the field whose value will be processed.
• targetKey (string|int): The key where the result of the callable function should be stored.
• callable (callable): The function to apply to the field value. This function should accept a single argument (the value of the field) and return the processed value.

Returns

• self: Returns the instance of the class for method chaining.

Example Usage

bash composer test

## Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

## Contributing

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

## Security Vulnerabilities

Please review [our security policy](../../security/policy) on reporting security vulnerabilities.

## Credits

- [Roberto B.](https://github.com/roberto-butti)
- [All Contributors](../../contributors)

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.