wp-media / apply-filters-typed
Library for usage of WordPress filters in a safe-type way
Installs: 14 274
Dependents: 3
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 5
Requires (Dev)
This package is auto-updated.
Last update: 2024-08-26 08:14:45 UTC
README
Library for usage of WordPress filters in a typesafe way.
What problem does it solve?
When using a filter with apply_filters()
, there is currently no guarantee that the type of the final value (after all callbacks have been called) will match the type of the initial value for this filter.
This can cause unexpected errors in your code if you do some processing with this value later on, assuming the final value type is the same as the original one.
This library is a way to solve this problem, by introducing functions that are applying strict type checking.
It is also a a proof of concept for a WordPress change that has been proposed in this core ticket: https://core.trac.wordpress.org/ticket/51525.
Limitation
If the end value type returned by the filter doesn't match the initial value type, the end value is discarded and the initial (default) one is returned. It's a limitation caused by the impossibility to access the internals of the hook system.
If the value is discarded, an error message will be added to the error.log when WP_DEBUG
is enabled: Return value of "hook_name" filter must be of the type "expected", "unexpected" returned.
The patch proposed to core handles the situation better, discarding callbacks that return an unexpected type instead of discarding the final value.
Installation
You can install the library using composer:
composer require wp-media/apply-filters-typed
Usage
You have 2 functions available to replace the default apply_filters()
function:
wpm_apply_filters_typesafe( $hook_name, $value, ...$args )
This function takes the same parameters as the apply_filters()
function. It will automatically determine the type to use for validation by checking the type of the $value
parameter.
wpm_apply_filters_typed( $type, $hook_name, $value, ...$args )
This function takes as its first parameter the expected type of the value to be filtered, in addition to the usual parameters of the apply_filters()
function.
In the context of WordPress, the common types would be:
- boolean
- integer
- double
- string
- array
- object
Create your own type validation
If you have a need for more complex type validation of the value passed to the filter, for example in case of an array that should only have values with a specific type, you can use the dynamic filter wpm_is_type_{$type}
, where $type
would match with the $type
value you pass to wpm_apply_filters_typed()
.
Here is an example to do custom type validation on an array of strings:
wpm_apply_filters_typed( 'string[]', 'filter_this_array', $value );
add_filter( 'wpm_is_type_string[], function( $value ) {
if ( ! is_array( $value ) ) {
return false;
}
foreach ( $value as $val ) {
if ( ! is_string( $val ) ) {
return false;
}
}
return true;
} );