Map

About 9 min

Map

Enhanced array access class.

The Map class acts similar to a normal PHP Array but extends it's functionality considerably. You are able to reset a Map to default values, easily extend using another Map or Array, have more simplified access to array key functions, as well as output to various formats such as Array or JSON.

Example

$map = new Hazaar\Map();
$map->depth0->depth1->depth2 = ['foo', 'bar'];
echo $map->toJson();

The above example will print the JSON string:

{ "depth0" : { "depth1" : { "depth2" : [ "foo", "bar" ] } } }

Filters

Filters are callback functions or class methods that are executed upon a get/set call. There are two methods used for applying filters.

Map::addInputFilter() - Executes the filter when the element is added to the Map (set).
Map::addOutputFilter() - Executes the filter when the element is read from the Map (get).

The method executed is passed two arguments, the value and the key, in that order. The method must return the value that it wants to be used or stored.

Using Filters

Here is an example of using an input filter to convert a Date object into an array of epoch and a timezone field.

$callback = function($value, $key){
    if(is_a('\Hazaar\Date', $value)){
        $value = new Map([
            'datetime' => $value->timestamp(),
            'timezone' => $value->timezone()
        ]);
    }
    return $value;
}
$map->addInputFilter($callback, '\Hazaar\Date', true);

Here is an example of using an output filter to convert an array with two elements back into a Date object.

$callback = funcion($value, $key){
    if(Map::is_array($value) && isset('datetime', $value) && isset('timezone', $value)){
        $value = new \Hazaar\Date($value['datetime'], $value['timezone']);
    }
    return $value;
}
$map->addInputFilter($callback, '\Hazaar\Map', true);

The second parameter to the addInputFilter/addOutputFilter methods is a class condition, meaning that the callback will only be called on objects of that type (uses is_a() internally).

The third parameter says that you want the filter to be applied to all child Map elements as well. This is a very powerful feature that will allow type modification of any element at any depth of the Map.

Properties

defaults

Holds the original child objects and values.

protected array $defaults

elements

Holds the active elements.

protected array $elements

current

The current value for array access returned by Map::each().

protected mixed $current

locked

Allows the map to be locked so that it's values are not accidentally changed.

protected bool $locked

filter

Optional filter definition to modify objects as they are set or get.

private array $filter

Filters are an array with the following keys:

callback - The method to execute. Can be a PHP callback definition or function name.
class - A class name or array of class names that that the callback will be executed on. Null means all elements.
recurse - Whether this filter should be recursively added to new and existing child elements

Methods

__construct

The Map constructor sets up the default state of the Map. You can pass an array or another Map

public  __construct({Array})

object to use as default values.

In the constructor you can also optionally extend the defaults. This is useful for when you have a default set of values that may or may not exist in the extended array.

Example

  $config = ['enabled' => true];
  $map = new Hazaar\Map([
    'enabled' => false,
    'label' => 'Test Map'
  ], $config);

  var_dump($map->toArray());

This will output the following text:

  array (size=2)
    'enabled' => boolean true
    'label' => string 'Test Map' (length=8)

!!! notice If the input arguments are strings then the Map class will try and figure out what kind of string it is and either convert from JSON or unserialize the string.

Parameter	Type	Description
`$defaults`	`mixed`	Default values will set the default state of the Map
`$extend`	`mixed`	Extend the default values overwriting existing key values and creating new ones
`$filter_def`	`array`

Parameter	Type	Description
`$defaults`	`Map`	map or Array of values to initialise the Map with
`$erase`	`bool`	If TRUE resets the default values. If FALSE, then the existing defaults are kept

Parameter	Type	Description
`$callback`	`callable`	the function to execute on get
`$filterRecurse`	`bool`	All children will have the same filter applied
`$filterField`	`string`
`$filterType`	`string`	a class name or array of class names to run the callback on

Parameter	Type	Description
`$callback`	`callable`	the function to execute on set
`$filterRecurse`	`bool`	All children will have the same filter applied
`$filterField`	`string`
`$filterType`	`string`	a class name or array of class names to run the callback on

Parameter	Type	Description
`$criteria`	`array`
`$field`	`string`	Return a single field. If the field does not exist returns null. This allows

Parameter	Type	Description
`$criteria`	`Map`
`$fields`	`array`	The fields to use for the sum. If omitted all numeric fields will be summed.

Parameter	Type	Description
`$inner_glue`	`string`	the glue to use between the key and value
`$outer_glue`	`string`	the glue to use between each key/value pair
`$ignore`	`array`	an array of keys to ignore

Parameter	Type	Description
`$key`	`string`	The name of the key to pass to the callback
`$elem`	`mixed`	The element that we are executing the callback on
`$direction`	`string`	The filter direction identified ('in' or 'out')

Parameter	Type	Description
`$ignorenulls`	`bool`
`$flags`	`int`
`$depth`	`int`