waUtils

Methods

• arrayInsertAfter

  Adds new array items after a specified key.

• dropNotPositive

  Filters out array items which are not positive numbers.

• extractValuesByKeys

  Returns array items with specified keys.

• getFieldValues

  Extracts values from array items.

• groupBy

  Groups sub-arrays by specified field’s values.

• jsonDecode

  Wrapper for json_decode() function.

• jsonEncode

  Wrapper for json_encode() function.

• orderKeys

  Sorts items of an associative array in the specified order.

• toIntArray

  Returns an array of values cast to integer type.

• toStrArray

  Returns an array of values cast to string type.

• varExportToFile

  Saves a variable value to a configuration file.

• getRandomHexString

  Returns a random string composed of characters used for writing hexadecimal numbers.

• urlSafeBase64Encode

  Returns a representation of a string value encoded for safe use in URLs.

• urlSafeBase64Decode

  Restores an original string value from its representation encoded for sage use in URLs.

• isUrlSafeBase64Encoded

  Verifies whether a specified string is a valid representation of a string value encoded for safe use in URLs.

• gcd

  Returns the greatest common divisor of two positive integers.

• lcm

  Returns the least common multiple of two positive integers.

public static function arrayInsertAfter (array $array, $key, array $new)

Adds new array items after a specified key.

Parameters

• $array

  Original associative array.

• $key

  Array key after which new items must be added.

• $new

  Array with new items.

Example

$array = array(
    'name' => 'value',
    'name2' => 'value2',
    'name3' => 'value3',
    'name4' => 'value4',
);

waUtils::arrayInsertAfter($array, 'name2', array('name5' => 'value5'));

Result

array(
    'name' => 'value',
    'name2' => 'value2',
    'name5' => 'value5',
    'name3' => 'value3',
    'name4' => 'value4',
);

public static function dropNotPositive ($int_array)

Filters out array items which are not positive numbers.

Parameters

• $int_array

  Original array of numbers.

Example

$array = array(
    -2,
    -1,
    0,
    1,
    2,
);

Result

array(
    3 => 1,
    4 => 2,
);

public static function extractValuesByKeys (array $array, $keys = array(), $skip = true, $populate = null)

Returns array items with specified keys.

Parameters

• $array

  Original associative array.

• $keys

  Array of keys of array items which must be returned.

• $skip

  Whether array items with keys missing in $keys parameter must not be included in the resulting array.

• $populate

  The value which must replace the values of original array’s items, whose keys are not contained in the $keys parameter, when they are added to the resulting array with false specified in $skip.

Example

$array = array(
    'apple' => 100,
    'orange' => 200,
    'pineapple' => 300,
    'watermelon' => 400,
);

$keys = array(
    'orange',
    'watermelon',
    'strawberry',
);

waUtils::extractValuesByKeys($array, $keys);

Result

array(
    'orange' => 200,
    'watermelon' => 400,
);

Example

$array = array(
    'apple' => 100,
    'orange' => 200,
    'pineapple' => 300,
    'watermelon' => 400,
);

$keys = array(
    'orange',
    'watermelon',
    'strawberry',
);

waUtils::extractValuesByKeys($array, $keys, false, 0);

Result

array(
    'orange' => 200,
    'watermelon' => 400,
    'strawberry' => 0,
);

public static function getFieldValues (array $array, $field, $index_key = null)

Extracts the values of a field from array items, associative sub-arrays or objects.

Parameters

• $array

  Array of values.

• $field

  A field whose values must be returned. It can be either a key used in sub-arrays or a public field of objects contained in the values array.

• $index_key

  Keys to be used in the result array. Acceptable keys are:

  • One of keys used in sub-arrays or objects. Values with a specified key will be used as keys in the result array.
  • true. Keys in the result array will be those of the values array.
  • null. Keys in the result array will be incrementing numbers starting with 0. The result array will contain only unique values in this case.

Example

$array = array(
	111 => array(
		'id' => 1,
		'name' => 'one',
	),
	222 => array(
		'id' => 2,
		'name' => 'two',
	),
	333 => array(
		'id' => 3,
		'name' => 'three',
	),
);
waUtils::getFieldValues($array, 'name', 'id');
waUtils::getFieldValues($array, 'name', true);
waUtils::getFieldValues($array, 'name', null);

Result

//key is 'id'
array(
    1 => 'one',
    2 => 'two',
    3 => 'three',
);

//true
array(
    111 => 'one',
    222 => 'two',
    333 => 'three',
);

//null
array(
    0 => 'one',
    1 => 'two',
    2 => 'three',
);

public static function groupBy (array $array, $field, $type = 'collect')

Groups sub-arrays by specified field’s values. Those values are used as the keys of the resulting array.

Parameters

• $array

  Array containing, usually associative, sub-arrays that need to be grouped.

• $field

  Name of key whose values must be used for sub-arrays grouping.

• $type

  Grouping method:

  • 'collect': sub-arrays of the original array, containing equal values of the key specified in $field parameter, are grouped into sub-arrays of the resulting array; the values of the specified field are used as the keys of the resulting array.
  • 'first': only the first sub-array of each group of sub-arrays with the same values of the specified field is added to the resulting array.
  • 'last': only the last sub-array of each group of sub-arrays with the same values of the specified field is added to the resulting array.

Example

$array = array(
    'key1' => array(
        'name' => 'Name 1',
        'value' => 111,
    ),
    'key2' => array(
        'name' => 'Name 1',
        'value' => 222,
    ),
    'key3' => array(
        'name' => 'Name 2',
        'value' => 333,
    ),
    'key4' => array(
        'name' => 'Name 2',
        'value' => 444,
    ),
    'key5' => array(
        'name' => 'Name 3',
        'value' => 555,
    ),
    'key6' => array(
        'name' => 'Name 3',
        'value' => 666,
    ),
);

waUtils::groupBy($array, 'name', 'collect');
waUtils::groupBy($array, 'name', 'first');
waUtils::groupBy($array, 'name', 'last');

Result

//'collect'
array(
    'Name 1' => array(
        'key1' => array(
            'name' => 'Name 1',
            'value' => 111,
        ),
        'key2' => array(
            'name' => 'Name 1',
            'value' => 222,
        ),
    ),
    'Name 2' => array(
        'key3' => array(
            'name' => 'Name 2',
            'value' => 333,
        ),
        'key4' => array(
            'name' => 'Name 2',
            'value' => 444,
        ),
    ),
    'Name 3' => array(
        'key5' => array(
            'name' => 'Name 3',
            'value' => 555,
        ),
        'key6' => array(
            'name' => 'Name 3',
            'value' => 666,
        ),
    ),
);

//'first'
array(
    'Name 1' => array(
        'name' => 'Name 1',
        'value' => 111,
    ),
    'Name 2' => array(
        'name' => 'Name 2',
        'value' => 333,
    ),
    'Name 3' => array(
        'name' => 'Name 3',
        'value' => 555,
    ),
);

//'last'
array(
    'Name 1' => array(
        'name' => 'Name 1',
        'value' => 222,
    ),
    'Name 2' => array(
        'name' => 'Name 2',
        'value' => 444,
    ),
    'Name 3' => array(
        'name' => 'Name 3',
        'value' => 666,
    ),
);

public static function jsonDecode ($json, $assoc = false, $depth = 512, $options = 0)

Wrapper for json_decode() function. In case of a failure while parsing a JSON string, the method generates a waException class exception with an error message.

Parameters

• $json

  JSON string.

• $assoc

  2nd parameter for json_decode() function. Default value: false.

• $depth

  3rd parameter for json_decode() function. Default value: 512.

• $options

  4th parameter for json_decode() function. Default value: 0.

Example

$json = '{
    "name": "value",
    "name2": "value2",
    "name3": "value3",
    "name4": "value4"
}';

waUtils::jsonDecode($json, true);

Result

array(
    'name' => 'value',
    'name2' => 'value2',
    'name3' => 'value3',
    'name4' => 'value4',
);

public static function jsonEncode ($value, $options = 0, $depth = 512)

Wrapper for json_encode() function.

Parameters

• $value

  Value to be passed to json_encode function.

• $options

  2nd parameter for json_encode() function. If 0 is specified then:

  • If JSON_UNESCAPED_UNICODE constant is defined then its value is added to this parameter.
  • Id the debug mode is enabled and JSON_PRETTY_PRINT constant is defined then its value is added to this parameter.
• $depth

  3rd parameter for json_encode() function. Default value is 512.

Example

$array = array(
    'name' => 'value',
    'name2' => 'value2',
    'name3' => 'value3',
    'name4' => 'value4',
);

Result

// debug mode is enabled
'{
    "name": "value",
    "name2": "value2",
    "name3": "value3",
    "name4": "value4"
}'

public static function orderKeys (array $array, $order = array())

Sorts items of an associative array in the specified order.

Parameters

• $array

  Associative array whose items must be sorted.

• $order

  Array, or instance of a class implementing Traversable interface, containing keys in the order in which original array’s items must be sorted. If some of specified keys are not available in the original array then they are ignored. Original array’s items with keys not provided in the $order parameter are moved to the end of the resulting array.

Example

$array = array(
    'apple' => 100,
    'orange' => 200,
    'pineapple' => 300,
    'watermelon' => 400,
);

$order = array(
    'watermelon',
    'pineapple',
    'strawberry',
);

waUtils::orderKeys($array, $order;

Result

array(
    'watermelon' => 400,
    'pineapple' => 300,
    'apple' => 100,
    'orange' => 200,
);

public static function toIntArray ($val)

Returns an array of values cast to integer type.

Parameters

• $val

  Original value. If an array is specified then the method returns an array of its values cast to integer type. If a scalar value is specified then the method returns an array of a single item whose value is the original value cast to integer type.

Example

$array = array(
    'foo',
    1,
    '2',
    null,
    array(),
    array(1, 2, 3)
);

waUtils::toIntArray($array)

Result

array(
    0 => 0,
    1 => 1,
    2 => 2,
    3 => 0,
    4 => 0,
    5 => 0,
);

public static function toStrArray ($val, $trim = true)

Returns an array of values cast to string type.

Parameters

• $val

  Original value. If an array is specified then the method returns an array of its values cast to string type. If a scalar value is specified then the method returns an array of a single item whose value is the the original value cast to string type.

• $trim

  Whether leading and trailing whitespace characters must be removed from strings.

Example

$array = array(
    'foo',
    ' bar ',
    null,
    ' 1 ',
);

waUtils::toStrArray($array);

Result

array(
    0 => 'foo',
    1 => 'bar',
    2 => '',
    3 => '1',
);

Example

$array = array(
    'foo',
    ' bar ',
    null,
    ' 1 ',
);

waUtils::toStrArray($array, false);

Result

array(
    0 => 'foo',
    1 => ' bar ',
    2 => '',
    3 => ' 1 ',
);

public static function varExportToFile ($var, $file, $export = true)

Saves a variable value to a configuration file.

Parameters

• $var

  Variable value.

• $file

  Path to file to save the variable value to.

• $export

  Whether a variable must be saved as the result of var_export() function. It is usually done when an array is saved.

Example

//array
$array_var = array(
    'id' => 'some',
    'url' => '/test/',
);
$file = wa()->getConfig()->getConfigPath('plugins/test/config_array.php');
waUtils::varExportToFile($var, $file);

//scalar value
$scalar_var = 1528117809;
$file = wa()->getConfig()->getConfigPath('plugins/test/config_scalar.php');
waUtils::varExportToFile($scalar_var, $file, false);

public static function getRandomHexString ($length = 64)

Returns a random string composed of characters used for writing hexadecimal numbers.

Parameters

• $length

  Length of a desired random string.

Example

$safe_random_hex_string = waUtils::getRandomHexString(32);

public static function urlSafeBase64Encode ($string)

Returns a representation of a string value encoded for safe use in URLs. Such an encoded representation can be decoded back using the urlSafeBase64Decode() method.

Parameters

• $string

  Original string.

Example

$safe_string_for_url = waUtils::urlSafeBase64Encode('hello');

public static function urlSafeBase64Decode ($string)

Restores an original string value from its representation encoded for sage use in URLs using the urlSafeBase64Encode() method.

Parameters

• $string

  Representation of a string value encoded using the urlSafeBase64Encode() method.

Example

$original_string = waUtils::urlSafeBase64Decode('aGVsbG8');

public static function isUrlSafeBase64Encoded ($string)

Verifies whether a specified string is a valid representation of a string value encoded for safe use in URLs using the urlSafeBase64Encode() method.

Parameters

• $string

  String value which must be checked.

Example

wa_dump(waUtils::isUrlSafeBase64Encoded('aGVsbG8'));    // true
wa_dump(waUtils::isUrlSafeBase64Encoded('qwerty000'));  // false

public static function gcd ($a, $b)

Returns the greatest common divisor of two positive integers.

Parameters

• $a

  First positive integer.

• $b

  Second positive integer.

Example

echo waUtils::gcd(36, 48); // 12

public static function lcm ($a, $b)

Returns the least common multiple of two positive integers.

Parameters

• $a

  First positive integer.

• $b

  Second positive integer.

Example

echo waUtils::lcm(12, 16); // 48