This nifty little helper is used to apply a default definition of options
to a given object of options (presumably transferred as a function parameter)
An Example:
function myFunc(value, options){
const definition = {
foo: {
default: 123
},
bar: {
default: null
}
}
options = makeOptions(options, definition);
...
}
myFunc("something") => options will be {foo: 123, bar: null}
myFunc("something", {foo: 234}) => $options will be {foo: 234, bar: null}
myFunc("something", {rumpel: 234}) => This will cause an error, because the key is not known
myfunc("something", {foo: "rumpel"}) $options will be {foo: "rumpel", bar: null}
IMPORTANT NOTE: When you want to set an array as default value make sure to wrap it in a function
Example: $defaults = {rumpel: {default: {}}}} <- Don't do this! Do this: {rumpel: {default: () => {return {}; }}}
In addition to the simple default values you can also use an array as value in your definitions array.
In it you can set the following options to validate and filter options as you wish.
default (mixed|callable): This is the default value to use when the key in $options is empty.
If not set the option key is required! If the default value is a Closure the closure is called
and it's result is used as value.
The callback receives $key, $options, $definition, $path(For child arrays)
type (string|array): Allows basic type validation of the input. Can either be a string or an array of strings.
Possible values are: boolean, bool, true, false, number (int and float) or numeric (both int and float +
string numbers), string, null, callable object and plainObject.
If multiple values are supplied they will be seen as chained via OR operator.
preFilter (callable): A callback which is called BEFORE the type validation takes place and can be used to
cast the incoming value before validating it's type.
filter (callable): A callback which is called after the type validation took place and can be used to process
a given value before the custom validation begins.
The callback receives $value, $key, $options, $definition, $path(For child arrays)
validator (callable): A callback which allows custom validation using closures or other callables. If used the
function should return true if the validation was successful or false if not. It is also possible to return a
string which allows you to set your own error message. In addition you may return an array of values that will
be passed to the "values" validator (see the next point for the functionality)
The callback receives $value, $key, $options, $definition, $path(For child arrays)
values (array): A basic validation routine which receives a list of possible values and will check if
the given value will match at least one of them (OR operator). The array can either be set statically
in your definition, or by using a "validator" callback that returns an array of possible values.
The values validation takes place after the "validator" callback ran.
children (object): This can be used to apply nested definitions on option trees.
The children definition is done exactly the same way as on root level.
NOTE: The children will only be used if the value in $options is an array
(or has a default value of an empty array)
This nifty little helper is used to apply a default definition of options to a given object of options (presumably transferred as a function parameter)
An Example: function myFunc(value, options){ const definition = { foo: { default: 123 }, bar: { default: null } } options = makeOptions(options, definition); ... }
myFunc("something") => options will be {foo: 123, bar: null} myFunc("something", {foo: 234}) => $options will be {foo: 234, bar: null} myFunc("something", {rumpel: 234}) => This will cause an error, because the key is not known myfunc("something", {foo: "rumpel"}) $options will be {foo: "rumpel", bar: null}
IMPORTANT NOTE: When you want to set an array as default value make sure to wrap it in a function Example: $defaults = {rumpel: {default: {}}}} <- Don't do this! Do this: {rumpel: {default: () => {return {}; }}}
Advanced definitions
In addition to the simple default values you can also use an array as value in your definitions array. In it you can set the following options to validate and filter options as you wish.
default (mixed|callable): This is the default value to use when the key in $options is empty. If not set the option key is required! If the default value is a Closure the closure is called and it's result is used as value. The callback receives $key, $options, $definition, $path(For child arrays)
type (string|array): Allows basic type validation of the input. Can either be a string or an array of strings. Possible values are: boolean, bool, true, false, number (int and float) or numeric (both int and float + string numbers), string, null, callable object and plainObject. If multiple values are supplied they will be seen as chained via OR operator.
preFilter (callable): A callback which is called BEFORE the type validation takes place and can be used to cast the incoming value before validating it's type.
filter (callable): A callback which is called after the type validation took place and can be used to process a given value before the custom validation begins. The callback receives $value, $key, $options, $definition, $path(For child arrays)
validator (callable): A callback which allows custom validation using closures or other callables. If used the function should return true if the validation was successful or false if not. It is also possible to return a string which allows you to set your own error message. In addition you may return an array of values that will be passed to the "values" validator (see the next point for the functionality) The callback receives $value, $key, $options, $definition, $path(For child arrays)
values (array): A basic validation routine which receives a list of possible values and will check if the given value will match at least one of them (OR operator). The array can either be set statically in your definition, or by using a "validator" callback that returns an array of possible values. The values validation takes place after the "validator" callback ran.
children (object): This can be used to apply nested definitions on option trees. The children definition is done exactly the same way as on root level. NOTE: The children will only be used if the value in $options is an array (or has a default value of an empty array)