# 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 "Direct link to Usage")

### Usage for Options[​](#usage-for-options "Direct link to 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:

```php
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[​](#usage-for-object-metadata "Direct link to 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:

```php
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:

```php
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 Query Variables[​](#usage-for-query-variables "Direct link to Usage for Query Variables")

The `mixed_query_var` helper can be used to retrieve query variables in a type-safe manner:

```php
use function Mantle\Support\Helpers\mixed_query_var;

// Get the value of a query variable as a string.
mixed_query_var( 'query_var_name' )->string();

```

### Usage for Mixed Data[​](#usage-for-mixed-data "Direct link to 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.

```php
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:

```php
use Mantle\Support\Mixed_Data;

$value = Mixed_Data::of( 'some_value' )->string(); // string

```

## Methods[​](#methods "Direct link to Methods")

The following methods are shared between the `option` helper and all the object meta data helpers.

* [`array()`](#array)

* [`boolean()`](#boolean)

* [`collect()`](#collect)

* [`date()`](#date)

* [`dd()`](#dd)

* [`dump()`](#dump)

* [`float()`](#float)

* [`int()`](#int)

* [`is_empty()`](#is_empty)

* [`is_not_null()`](#is_not_null)

* [`is_type( string $type )`](#is_type-string-type-)

* [`is_not_type()`](#is_not_type)

* [`is_array()`](#is_array)

* [`is_not_array()`](#is_not_array)

* [`is_object()`](#is_object)

* [`is_not_object()`](#is_not_object)

* [`object()`](#object)

* [`string()`](#string)

* [`stringable()`](#stringable)

* [`throw()`](#throw)

* [`throw_if()`](#throw_if)

* [`value()`](#value)

* [Update and Delete Methods](#update-and-delete-methods)

  * [`set()`](#set)
  * [`delete()`](#delete)

### `array()`[​](#array "Direct link to array")

Get the value of the option as an array.

```php
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):

```php
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()`[​](#boolean "Direct link to boolean")

Get the value of the option as a boolean.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->boolean(); // bool

```

### `collect()`[​](#collect "Direct link to collect")

Get the value of the option as a [collection](/docs/features/support/collections.md).

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->collect(); // Mantle\Support\Collection

```

### `date()`[​](#date "Direct link to date")

Get the value of the option as a Carbon date instance.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->date(); // Carbon\Carbon

```

It also supports passing a format and/or timezone:

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->date( format: 'Y-m-d H:i:s', timezone: 'UTC' ); // Carbon\Carbon

```

### `dd()`[​](#dd "Direct link to dd")

Dump the value of the option and end the script execution.

```php
use function Mantle\Support\Helpers\option;

option( 'option_name' )->dd();

```

### `dump()`[​](#dump "Direct link to dump")

Dump the value of the option and continue script execution.

```php
use function Mantle\Support\Helpers\option;

option( 'option_name' )->dump();

```

### `float()`[​](#float "Direct link to float")

Get the value of the option as a float.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->float(); // float

```

### `int()`[​](#int "Direct link to int")

Get the value of the option as an integer.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->int(); // int

// or
$value = option( 'option_name' )->integer(); // int

```

### `is_empty()`[​](#is_empty "Direct link to is_empty")

Check if the value of the option is empty.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_empty() ) {
  // The option is empty.
}

```

### `is_not_null()`[​](#is_not_null "Direct link to is_not_null")

Check if the value of the option is not `null`.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_not_null() ) {
  // The option is not null.
}

```

### `is_type( string $type )`[​](#is_type-string-type- "Direct link to is_type-string-type-")

Check if the value of the option is of a specific type.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_type( 'string' ) ) {
  // The option is a string.
}

```

### `is_not_type()`[​](#is_not_type "Direct link to is_not_type")

Check if the value of the option is not of a specific type.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_not_type( 'string' ) ) {
  // The option is not a string.
}

```

### `is_array()`[​](#is_array "Direct link to is_array")

Check if the value of the option is an array.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_array() ) {
  // The option is an array.
}

```

### `is_not_array()`[​](#is_not_array "Direct link to is_not_array")

Check if the value of the option is not an array.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_not_array() ) {
  // The option is not an array.
}

```

### `is_object()`[​](#is_object "Direct link to is_object")

Check if the value of the option is an object.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_object() ) {
  // The option is an object.
}

```

### `is_not_object()`[​](#is_not_object "Direct link to is_not_object")

Check if the value of the option is not an object.

```php
use function Mantle\Support\Helpers\option;

if ( option( 'option_name' )->is_not_object() ) {
  // The option is not an object.
}

```

### `object()`[​](#object "Direct link to object")

Get the value of the option as an object.

```php
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:

```php
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()`[​](#string "Direct link to string")

Get the value of the option as a string.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->string(); // string

```

### `stringable()`[​](#stringable "Direct link to stringable")

Get the value of the option as a [Stringable](/docs/features/support/stringable.md) object.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->stringable(); // Mantle\Support\Stringable

```

### `throw()`[​](#throw "Direct link to 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.

```php
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_if "Direct link to throw_if")

Throw an exception if the option is not able to be cast to the specified type based on a condition.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )
  ->throw_if( 'production' !== wp_get_environment_type() )
  ->string(); // string

```

### `value()`[​](#value "Direct link to value")

Get the value of the option. Will return with a type of `mixed`.

```php
use function Mantle\Support\Helpers\option;

$value = option( 'option_name' )->value(); // mixed

```

### Update and Delete Methods[​](#update-and-delete-methods "Direct link to Update and Delete Methods")

These methods can be used on object metadata and options.

#### `set()`[​](#set "Direct link to set")

The `option` helper can also be used to update an option's or a object's meta data value:

```php
use function Mantle\Support\Helpers\option;

// Update the value of an option.
$meta = option( 'option_name' );

$meta->set( 'new_value' );
$meta->save();

```

#### `delete()`[​](#delete "Direct link to delete")

The `option` helper can also be used to delete an option or a object's meta data:

```php
use function Mantle\Support\Helpers\option;

// Delete an option.
option( 'option_name' )->delete();

```