Download the PHP package neunerlei/options without Composer

Option Applier

This nifty little helper can be used to apply a schema to any given array. It is designed to work as an on-the-fly validator for method options but is powerful enough to validate all sorts of API requests as well.

Installation

Install this package using composer:

Basic Usage

The main purpose of the package is to validate options that are passed to methods or functions, like in this basic example:

Simple Definition

As you can see above, you can define a simple list of keys and matching default values, that act like "array_merge" would. All keys passed to $options that are not in the definition will throw a validation exception. In general, you can pass any value as a default (arrays require a little quirk, tho (see below));

Defining an array as default value

Please note that it is not possible to pass an array as a default value like you would with any other type. You have to make sure that your default array is wrapped by an outer array like:

If you don't wrap the default array in an array a InvalidOptionDefinitionException will be thrown.

Advanced Definition

In addition to the simple default values, you can also use an array as a value in your definitions array. In it, you can set the following options to validate and manipulate the options to your liking.

I choose arrays as a definition because they run fast,and one is only required to remember a handful of options.

Options

default (mixed|callable)

This is the default value to use when the key in $options is not given. If not set, the option key is required! If the default value is a Closure, the closure is called, and its result is used as the value.

type (string|array)

Allows basic type validation of the input. It can either be a string or an array of strings. If multiple values are supplied as an array, they are seen as chained via OR operator. Possible values are:

• boolean
• bool
• true
• false
• integer
• int
• double
• float
• number (int and float)
• numeric (both int and float + string numbers -> is_numeric)
• string
• resource
• null
• callable

It is also possible to validate the type of an instance based on a class or interface name.

preFilter (callable)

A callback that is called BEFORE the type validation takes place and can be used to cast the incoming value before validating its type.

filter (callable)

A callback to call after the type validation took place and can be used to process a given value before the custom validation begins.

validator (callable)

Executes a given callable. The function receives: $value, $key, $options, $node, $context.

• If the function returns FALSE the validation is failed.
• If the function returns TRUE the validation is passed.
• If the function returns an array of values, the values will be passed on, and handled like an array passed to " validator".
• If the function returns a string, it is considered a custom error message.

validator (string)

If the given value is a non-callable string, it will be evaluated as regular expression

validator (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).

children (array)

This can be used to apply nested definitions on option trees. The children definition is done exactly the same way as on root level. The children will only be used if the value in $options is an array (or has a default value of an empty array). There are three options on how children will be evaluated:

1. Validating a direct, associative child of a node:

2. Validating a list of child nodes that have the same structure:

3. Validating a list of values with the same type, (for example a list of phone numbers):

Boolean Flags

It is also possible to supply options that have a type of "boolean" as "flags," which means you don't have to provide any values to it. NOTE: Boolean Flags can only be used to set a boolean value to TRUE if you want to set it to FALSE you have to set the key, value pair.

Additional options

The third parameter of the Options::make() method lets you define additional options. All boolean values can be either passed as key-value pairs or as boolean flags.

allowUnknown (bool)

DEFAULT: FALSE

If set to TRUE, unknown keys will be kept in the result.

ignoreUnknown (bool)

DEFAULT: FALSE

If set to TRUE, unknown keys will be ignored but removed from the result.

allowBooleanFlags (bool)

DEFAULT: TRUE

If set to FALSE, it is not allowed to use boolean flags in your input array. Useful when validating API inputs.

Single value handling

In general, this does the same as Options::make() but is designed to validate non-array options.

NOTE: There is one gotcha. As you see in our example, we define $anOption as = null in the signature. This will cause the method to use the default value of " foo" if the property is not set. So make sure, if you want to allow NULL as non-default value to use a callback as default and handle null on your own.

Usage without static class

The static class uses a singleton of the class for all its actions. So if you want to use the applier as a service using dependency injection, just use the applier class instead of the static Options class.

Extending the applier class

The static Options class has a public, static property called , which defines the name of the class used for the logic. If you should ever want to extend the functionality, you can simply extend the applier class and set to the name of your extended class and will be good to go.

Special Thanks

Special thanks go to the folks at LABOR.digital (which is the german word for laboratory and not the English "work" :D) for making it possible to publish my code online.

Postcardware

You're free to use this package, but if it makes it to your production environment, I highly appreciate you sending me a postcard from your hometown, mentioning which of our package(s) you are using.

You can find my address here.

Thank you :D