Type-safe Options, Object Metadata and Mixed Data
When working with WordPress, you may need to retrieve and manipulate options or
object meta data. Out of the box, the data will come back as mixed
. You can
and should check the type of the data before using it. This can be cumbersome
and error-prone.
Mantle includes a option
helper function that can be used to retrieve an
option's value in a type-safe manner. It can also update the option's value and
manipulate it in various ways. Mantle also includes post_meta
, term_meta
,
user_meta
, and comment_meta
helper functions that can be used to retrieve
and manipulate object meta data in a type-safe manner. These build off the
mixed
helper that can be used to manage and manipulate mixed data from any
source.
Usage
Usage for Options
The option
function can be used to retrieve an option's value and does not
require the rest of the framework to do so:
use function Mantle\Support\Helpers\option;
// Set the value of an option.
update_option( 'option_name', 'option_value' );
// Get the value of an option as a string.
option( 'option_name' )->string();
// Get the value of an option as an integer.
option( 'option_name' )->integer();
// Get the value of an option as a boolean.
option( 'option_name' )->boolean();
// Get the value of an option as an array.
option( 'option_name' )->array();
Usage for Object Metadata
The post_meta
, term_meta
, user_meta
, and comment_meta
functions can be
used to retrieve object meta data and do not require the rest of the framework
to do so:
use function Mantle\Support\Helpers\post_meta;
use function Mantle\Support\Helpers\term_meta;
use function Mantle\Support\Helpers\user_meta;
use function Mantle\Support\Helpers\comment_meta;
// Retrieve post meta data.
post_meta( 1234, 'meta_key' )->string(); // string
post_meta( 1234, 'meta_key' )->boolean(); // bool
post_meta( 1234, 'meta_key' )->integer(); // int
// Retrieve term meta data.
term_meta( 1234, 'meta_key' )->string(); // string
term_meta( 1234, 'meta_key' )->boolean(); // bool
Meta data can also be updated and deleted:
use function Mantle\Support\Helpers\post_meta;
// Update post meta data.
$meta = post_meta( 1234, 'meta_key' );
if ( $meta->is_empty() ) {
$meta->set( 'meta_value' );
$meta->save();
}
// Delete post meta data.
post_meta( 1234, 'meta_key' )->delete();
Usage for Mixed Data
The mixed
helper can be used to manage and manipulate mixed data from any
source. You can pass any value to the mixed
helper and it will return a
Mantle\Support\Mixed_Data
object that provides a consistent interface for
retrieving and manipulating the data. This is useful when you need to work
with data that may come from various sources, such as user input, API
responses, or database queries.
use function Mantle\Support\Helpers\mixed;
$value = mixed( 'some_value' )->string(); // string
$value = mixed( '1234' )->integer(); // int
You can also use the Mixed_Data::of()
method to create a new instance of the
Mixed_Data
class with a specific value:
use Mantle\Support\Mixed_Data;
$value = Mixed_Data::of( 'some_value' )->string(); // string
Methods
The following methods are shared between the option
helper and all the object
meta data helpers.
array()
Get the value of the option as an array.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->array(); // array
You can use the get()
method to retrieve a specific key from the array
(supports dot notation):
use function Mantle\Support\Helpers\option;
update_option(
'example_option',
[
'key' => 'value',
'nested' => [
'key' => 'value',
],
]
);
$value = option( 'example_option' )->array(); // array{key: 'value', nested: array{key: 'value'}}
$nested = option( 'example_option' )->array( 'nested' ); // array{key: 'value'}
$sub = option( 'example_option' )->get( 'key' ); // string: value
// Supports dot notation.
$sub = option( 'example_option' )->get( 'nested.key' ); // string: value
// Check if a key exists.
$has = option( 'example_option' )->has( 'key' ); // bool: true
boolean()
Get the value of the option as a boolean.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->boolean(); // bool
collect()
Get the value of the option as a collection.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->collect(); // Mantle\Support\Collection
date()
Get the value of the option as a Carbon date instance.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->date(); // Carbon\Carbon
It also supports passing a format and/or timezone:
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->date( format: 'Y-m-d H:i:s', timezone: 'UTC' ); // Carbon\Carbon
dd()
Dump the value of the option and end the script execution.
use function Mantle\Support\Helpers\option;
option( 'option_name' )->dd();
dump()
Dump the value of the option and continue script execution.
use function Mantle\Support\Helpers\option;
option( 'option_name' )->dump();
float()
Get the value of the option as a float.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->float(); // float
int()
Get the value of the option as an integer.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->int(); // int
// or
$value = option( 'option_name' )->integer(); // int
is_empty()
Check if the value of the option is empty.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_empty() ) {
// The option is empty.
}
is_not_null()
Check if the value of the option is not null
.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_not_null() ) {
// The option is not null.
}
is_type( string $type )
Check if the value of the option is of a specific type.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_type( 'string' ) ) {
// The option is a string.
}
is_not_type()
Check if the value of the option is not of a specific type.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_not_type( 'string' ) ) {
// The option is not a string.
}
is_array()
Check if the value of the option is an array.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_array() ) {
// The option is an array.
}
is_not_array()
Check if the value of the option is not an array.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_not_array() ) {
// The option is not an array.
}
is_object()
Check if the value of the option is an object.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_object() ) {
// The option is an object.
}
is_not_object()
Check if the value of the option is not an object.
use function Mantle\Support\Helpers\option;
if ( option( 'option_name' )->is_not_object() ) {
// The option is not an object.
}
object()
Get the value of the option as an object.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->object(); // object
You can use the get()
method to retrieve a specific property from the object:
use function Mantle\Support\Helpers\option;
update_option(
'example_option',
(object) [
'key' => 'value',
'nested' => (object) [
'key' => 'value',
],
]
);
$value = option( 'example_option' )->object(); // object{key: 'value', nested: object{key: 'value'}}
$nested = option( 'example_option' )->object( 'nested' ); // object{key: 'value'}
$sub = option( 'example_option' )->get( 'key' ); // string: value
// Supports dot notation.
$sub = option( 'example_option' )->get( 'nested.key' ); // string: value
// Check if a property exists.
$has = option( 'example_option' )->has( 'key' ); // bool: true
string()
Get the value of the option as a string.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->string(); // string
stringable()
Get the value of the option as a Stringable object.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->stringable(); // Mantle\Support\Stringable
throw()
Throw an exception if the option is not able to be cast to the specified type. For example, if you try to cast an array to a string, an exception will be thrown.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->throw()->string(); // string
// The following will throw an exception:
$value = option( 'option_name' )->throw()->array();
throw_if()
Throw an exception if the option is not able to be cast to the specified type based on a condition.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )
->throw_if( 'production' !== wp_get_environment_type() )
->string(); // string
value()
Get the value of the option. Will return with a type of mixed
.
use function Mantle\Support\Helpers\option;
$value = option( 'option_name' )->value(); // mixed
Update and Delete Methods
These methods can be used on object metadata and options.
set()
The option
helper can also be used to update an option's or a object's meta
data value:
use function Mantle\Support\Helpers\option;
// Update the value of an option.
$meta = option( 'option_name' );
$meta->set( 'new_value' );
$meta->save();
delete()
The option
helper can also be used to delete an option or a object's meta data:
use function Mantle\Support\Helpers\option;
// Delete an option.
option( 'option_name' )->delete();