Mask Array Function - for setting default array structures and masking


/ Published in: PHP
Save to your folder(s)

Summary
=======
A useful function for masking arrays. Very useful if you have a function or method that takes arguments in an array, and you would like to force that array to have a specific structure.

Its also great for setting defaults due to the fact that whatever structure or variables that are missing from the arguments array, and are present in the default (mask) array will be copied from the default array and merged into the returned array.

Description
========

**mask_array**( array $defaults , array $arguments [, bool $keep_unset ] )

Accepts two arrays. The first array is used as a mask on the second array.


Parameters
========

**$defaults** - An array of defaults to use as a mask.
**$arguments** - An array of arguments to be filtered by the mask array.
**$keep_unset** - Setting this to true disables discarding variables and structure that will not fit within the mask.

Example
======

/*
* Basic use case
*/

$defaults = array(
'colour' => 'red',
'shape' => 'circle'
'size' => 'large'
);

$arguments = array(
'colour' => 'blue'
'wooden' => true
);

$filtered = mask_array($defaults, $arguments) ;

Result
====

**$filtered** will look like this:

array(
color => blue,
shape => circle,
size => large
)

Note that the key 'broken' is discarded, while the color is carried over.

If the third argument is set to true the result would be the following:

array(
color => blue,
shape => circle,
size => large,
wooden => true
)

Note that because keep unset is true the mask does not cut out the key 'broken' is included.

Hope that you find this useful

~Robert Hurst


Copy this code and paste it in your HTML
  1. /**
  2.  * Takes an two arrays and merges them. the first array is used as
  3.  * a template or mask, and the second array is applied over top.
  4.  * If the second array contains variables or structure not present
  5.  * in the first array it is discarded.
  6.  *
  7.  * The first array acts as a mask on the second array.
  8.  *
  9.  * @author Robert Hurst
  10.  * @website http://thinktankdesign.ca/
  11.  *
  12.  * @param $defaults
  13.  * @param $arguments
  14.  * @param bool $keep_unset
  15.  * @return array
  16.  */
  17. private function mask_array($defaults, $arguments, $keep_unset = false) {
  18.  
  19. /*
  20. * If the arguments are invalid or broken fail gracefully by
  21. * returning first argument.
  22. *
  23. * Note: this is done instead of returning false to prevent serious
  24. * failures in other methods or functions that depend on this method.
  25. * This is extremely important in recursive or self executing functions.
  26. */
  27. if( ! is_array( $defaults ) || ! is_array( $arguments ) ){
  28. return $defaults; //just return the defaults (something goofed)
  29. }
  30.  
  31. /*
  32. * Copy the default array (the mask) to the results array. If the second
  33. * array is invalid or does not match the mask at all, the default mask
  34. * will be returned.
  35. */
  36. $results = $defaults;
  37.  
  38. //loop through the second array
  39. foreach( $arguments as $key => $argument ){
  40.  
  41. /*
  42. * Check to see if the method is set to discard unmasked data, or if
  43. * the current argument does not fit within the default mask array.
  44. * If both of these are false then discard the variable or structure
  45. */
  46. if( ! $keep_unset && ! isset( $defaults[$key] ) )
  47. continue; //the option is invalid
  48.  
  49. /*
  50. * If the current argument is more array structure instead of a
  51. * variable then check if it fits in the default mask. if it does
  52. * re execute on it.
  53. */
  54. if( is_array( $argument ) ){
  55.  
  56. /*
  57. * If the mask has a variable instead of structure in this position.
  58. */
  59. if( !is_array( $defaults[$key] ) ){
  60.  
  61. /*
  62. * Check to see if the method is set to discard unmasked structure.
  63. * If the method is set to keep unmasked structure then replace the
  64. * mask's variable with this structure.
  65. */
  66. if( $keep_unset ){
  67. $results[$key] = $argument;
  68. }
  69.  
  70. //continue to the next item in the second array.
  71. continue;
  72. }
  73.  
  74. /*
  75. * re execute on the current structure and the current mask position.
  76. */
  77. $results[$key] = mask_array($defaults[$key], $argument, $keep_unset);
  78.  
  79. /*
  80. * If the current argument is a variable then save it to the results. Make
  81. * sure the mask does not specify structure.
  82. */
  83. } else {
  84.  
  85. /*
  86. * If the mask contains structure at this position then skip to the next
  87. * variable.
  88. */
  89. if( is_array( $defaults[$key] ) ){
  90. continue;
  91. }
  92.  
  93.  
  94. // save the current variable to the results array.
  95. $results[$key] = $argument;
  96. }
  97. }
  98.  
  99. /*
  100. * After processing all of the array structure, return the new filtered
  101. * array.
  102. */
  103. return $results;
  104.  
  105. }

URL: http://thinktankdesign.ca/

Report this snippet


Comments

RSS Icon Subscribe to comments

You need to login to post a comment.