Skip to main content
Version: 1.x

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();