General Data Helpers

This class contains miscellaneous functionality, mostly related to data manipulation.

Use:
\blobfolio\common\data

array_compare()

Determine whether the contents (keys and values) of two arrays are equal. Sorting is ignored.

Arguments

Type	Description
array	Array one.
array	Array two.

Returns

Returns TRUE if both arrays are equal, FALSE if they differ or if either are not an array.

Example

$arr1 = array('apples','bananas','carrots');
$arr2 = array('bananas','carrots','apples');
var_dump(blobfolio\common\data::array_compare($arr1, $arr2)); // TRUE

array_idiff()

A case-insensitive version of array_diff(). Unlike array_diff(), however, type matters. That is, 2 !== "2", but "TWO" === "two".

Arguments

Type	Description
array	Array one.
array	Array two.
...	Additional array(s).

Returns

Returns an array containing items from the first array that were not present in any of the others.

array_iintersect()

A case-insensitive version of array_intersect(). Unlike array_intersect(), however, type matters. That is, 2 !== "2", but "TWO" === "two".

Arguments

Type	Description
array	Array one.
array	Array two.
...	Additional arrays.

Returns

Returns an array containing items from the first array that were present in all others.

array_ikey_exists()

Works exactly like array_key_exists() but is case-insensitive.

Arguments

Type	Description
string	Needle.
array	Haystack.

Returns

Returns TRUE or FALSE.

array_isearch()

Works exactly like array_search() but is case-insensitive.

Arguments

Type	Description	Default
string	Needle.
array	Haystack.
bool	Strict.	FALSE

Returns

Returns the matching array key or FALSE if not found.

array_map_recursive()

Recursively apply a callback function to the contents of an array.

Arguments

Type	Description
callable	Callback function.
array	Array.

Returns

Returns the filtered array.

array_otherize()

Convert an indefinitely long associative array of numeric values to one of a fixed length, with any extra summed under "other". This is useful for, e.g., pie chart stats, where spatial limitations make it impractical to list zillions of entries individually.

Note: US dollars, cents, and percentages are fine, but will be converted to floats, losing their string labels.

Arguments

Type	Description	Notes	Default
array	Array.
int	Length.	The number of items in the array returned will be less than or equal to this value.	5
string	Group label.	This is the key given to grouped values.	"Other"

Returns

Returns an array of the defined length, greatest to least, with overages grouped under the other label at the end of the array.

Example

$stats = array(
    'US'=>100,
    'CA'=>200,
    'CN'=>5,
    'GB'=>10,
    'MX'=>30
);
$foo = blobfolio\common\data::array_otherize($stats, 3, 'ZZ');
/*
array(
    CA => 200
    US => 100
    ZZ => 45
)
*/

array_pop()

Return the last element of an array, but without altering the array as the true array_pop() does.

Arguments

Type	Description	Notes
array	Array.	By reference.

Returns

Returns the last value in the array, or FALSE if the array is empty.

Example

$arr = array('apples','bananas','carrots');
$last = blobfolio\common\data::array_pop($arr);
echo $last; // carrots

array_pop_rand()

Return a random value from the array. This works for both associative or sequential arrays.

Arguments

Type	Description	Notes
array	Array.	By reference.

Returns

Returns a random value from the array, or FALSE if the array is empty.

Example

$arr = array('apples','bananas','carrots');
echo blobfolio\common\data::array_pop_rand($arr); // apples
echo blobfolio\common\data::array_pop_rand($arr); // carrots

array_pop_top()

Return the first element of an array, again without altering the original variable.

Arguments

Type	Description	Notes
array	Array.	By reference.

Returns

Returns the first value in the array, or FALSE if the array is empty.

Example

$arr = array('apples','bananas','carrots');
$first = blobfolio\common\data::array_pop_top($arr);
echo $first; // apples

cc_exp_months()

Generate an array of months for e.g. use in a checkout form.

Arguments

Type	Description	Default
string	Value format.	"m - M"

Returns

Returns an array of expiration months, keyed 1-12, values corresponding to the passed date format.

\blobfolio\common\data::cc_exp_months();
/*
array(
    1 => 01 - Jan,
    2 => 02 - Feb,
    ...
)
*/

cc_exp_years()

Generate an array of years for e.g. use in a checkout form.

Arguments

Type	Description	Default
int	Length.	10

Returns

Returns an array of expiration years beginning with the current year.

\blobfolio\common\data::cc_exp_years();
/*
array(
    2010 => 2010,
    2011 => 2011,
    ...
)
*/

datediff()

Calculate the number of days between two dates. This will use \DateTime if available, but will fall back to counting up the seconds between the timestamps.

Arguments

Type	Description
int, string	Date or timestamp.
int, string	Date or timestamp.

Returns

Returns the number of days between the two values. If the dates are equal or either are invalid, 0 is returned.

Example

echo \blobfolio\common\data::datediff('2015-01-01', '2015-01-02'); // 1

iin_array()

Works exactly like in_array() but is case-insensitive.

Arguments

Type	Description	Default
string	Needle.
array	Haystack.
bool	Strict.	FALSE

Returns

Returns TRUE or FALSE.

in_range()

Determine whether a value falls within a given range.

Arguments

Type	Description	Notes	Default
mixed	Value.
mixed	Minimum value.	If NULL, no minimum will be checked.	NULL
mixed	Maximum value.	If NULL, no maximum will be checked.	NULL

Returns

Returns TRUE or FALSE. Only passed boundaries are tested.

Example

var_dump(\blobfolio\common\data::in_range(3, 0, 300)); // TRUE

ip_in_range()

Determine if an IP address is within the range.

Arguments

Type	Description	Notes	Default
string	IP address.
string	Minimum IP or a CIDR.
string	Maximum IP.	This argument is ignored if a CIDR is passed above.	NULL

Returns

Returns TRUE or FALSE.

Example

// Test against a CIDR.
\blobfolio\common\data::in_range('127.0.0.1', '127.0.0.0/24'); // TRUE

// Test against two IPs.
\blobfolio\common\data::in_range('127.0.0.1', '127.0.0.0', '127.0.0.255'); // TRUE

is_json()

Determine whether a string represents JSON data.

Arguments

Type	Description	Notes	Default
string	String.
bool	Allow empty.	If TRUE, empty strings will be considered valid JSON.	FALSE

Returns

Returns TRUE or FALSE.

is_utf8()

Determine whether a string is UTF-8.

Arguments

Type	Description
string	String.

Returns

Returns TRUE or FALSE.

json_decode_array()

Decode a JSON string, make sure the result is an array, and optionally format its values against a template. See also: [parse_args()][#parse_args].

Arguments

Type	Description	Notes	Default
string	JSON.
array	Defaults.
bool	Strict.	If TRUE, provided JSON values will be typecast according to the corresponding default entries.	TRUE
bool	Recursive.	If TRUE, provided JSON values will be parsed recursively when the corresponding default is an associative array.	TRUE

Returns

Returns an array, optionally parsed according to the provided defaults.

Example

$json = '{"fruit":"apple","pet":dog}';
$defaults = array(
    'fruit'=>'banana',
    'vegetable'=>'carrot'
);
print_r(\blobfolio\common\data::json_decode_array($json, $defaults));
/*
array(
    fruit => apple,
    vegetable => carrot
)
*/

length_in_range()

Determine whether a string's length falls within a given range of characters. This function is multi-byte safe provided mbstring is present.

Arguments

Type	Description	Notes	Default
string	String.
int	Minimum length.	If NULL, no minimum will be checked.	NULL
int	Maximum length.	If NULL, no maximum will be checked.	NULL

Returns

Returns TRUE or FALSE.

Example

var_dump(\blobfolio\common\data::length_in_range('The dog is cute.', 1, 10)); // FALSE

parse_args()

Generate an array combining user arguments and expected defaults. The structure of the default takes priority; foreign keys from the user arguments are not included in the output.

Arguments

Type	Description	Notes	Default
array	Arguments.
array	Defaults.
bool	Strict.	If TRUE, provided argument values will be typecast according to the corresponding default entries.	TRUE
bool	Recursive.	If TRUE, provided argument values will be parsed recursively when the corresponding default is an associative array.	TRUE

Returns

Returns an array matching the default, with overrides courtesy of the passed arguments.

Example

$args = array(
    'fruit'=>'apple',
    'pet'=>'dog'
);
$defaults = array(
    'fruit'=>'banana',
    'vegetable'=>'carrot'
);
print_r(\blobfolio\common\data::parse_args($args, $defaults));
/*
array(
    fruit => apple,
    vegetable => carrot
)
*/

random_int()

Generate a random integer using random_int() if available, otherwise mt_rand().

Arguments

Type	Description	Default
int	Minimum.	0
int	Maximum	1

Returns

Returns a random integer between the bounds.

random_string()

Generate a random string.

Arguments

Type	Description	Notes	Default
int	Length.		10
array	Alphabet.	If not provided, the random string will be built using unambiguous uppercase letters and numbers (e.g. skipping things like "I" or 1).	NULL

Returns

Returns a random string of the specified length.

switcheroo()

Switch the values of two variables.

Arguments

Type	Description	Notes
mixed	Variable one.	By reference.
mixed	Variable two.	By reference.

Returns

Returns TRUE.

Example

$a = 'Hello';
$b = 'World';
\blobfolio\common\data::switcheroo($a, $b);

echo "$a $b"; // World Hello

unsetcookie()

Delete a cookie and unset the corresponding $_COOKIE superglobal. Note: this must be run before headers have been sent. For best results, the arguments should match those used during the original setcookie() call.

Arguments

Type	Description	Default
string	Name.
string	Path.	""
string	Domain.	""
bool	Secure.	FALSE
bool	HTTP-only.	FALSE

Returns

Returns TRUE or FALSE. TRUE does not necessarily mean the cookie was successfully deleted, but rather that no show-stopping errors were thrown while trying.

Example

// Set a cookie.
setcookie('foobar', 'Hello World');

// Unset it.
\blobfolio\common\data::unsetcookie('foobar');