WooCommerce Code Reference

Note extends WC_Data
in package

Note class.

Table of Contents

E_WC_ADMIN_NOTE_ACTIONED  = 'actioned'
E_WC_ADMIN_NOTE_EMAIL  = 'email'
E_WC_ADMIN_NOTE_ERROR  = 'error'
E_WC_ADMIN_NOTE_INFORMATIONAL  = 'info'
E_WC_ADMIN_NOTE_MARKETING  = 'marketing'
E_WC_ADMIN_NOTE_PENDING  = 'pending'
E_WC_ADMIN_NOTE_SENT  = 'sent'
E_WC_ADMIN_NOTE_SNOOZED  = 'snoozed'
E_WC_ADMIN_NOTE_SURVEY  = 'survey'
E_WC_ADMIN_NOTE_UNACTIONED  = 'unactioned'
E_WC_ADMIN_NOTE_UPDATE  = 'update'
E_WC_ADMIN_NOTE_WARNING  = 'warning'
$cache_group  : string
Cache group.
$changes  : array<string|int, mixed>
Core data changes for this object.
$data  : array<string|int, mixed>
Core data for this object. Name value pairs (name + default value).
$data_store  : object
Contains a reference to the data store for this class.
$default_data  : array<string|int, mixed>
Set to _data on construct so we can track and reset data if needed.
$extra_data  : array<string|int, mixed>
Extra data for this object. Name value pairs (name + default value).
$id  : int
ID for this object.
$legacy_datastore_props  : array<string|int, mixed>
List of properties that were earlier managed by data store. However, since DataStore is a not a stored entity in itself, they used to store data in metadata of the data object.
$meta_data  : array<string|int, mixed>
Stores additional meta data.
$object_read  : bool
This is false until the object is read from the DB.
$object_type  : string
This is the name of this object type.
__clone()  : mixed
When the object is cloned, make sure meta is duplicated correctly.
__construct()  : mixed
Note constructor. Loads note data.
__sleep()  : array<string|int, mixed>
Only store the object ID to avoid serializing the data object instance.
__toString()  : string
Change data to JSON format.
__wakeup()  : mixed
Re-run the constructor with the object ID.
add_action()  : mixed
Add an action to the note
add_meta_data()  : mixed
Add meta data.
add_nonce_to_action()  : void
Add a nonce to an existing note action.
apply_changes()  : mixed
Merge changes with data and clear.
clear_actions()  : mixed
Clear actions from a note.
delete()  : bool
Delete an object, set the ID to 0, and return result.
delete_meta_data()  : mixed
Delete meta data.
delete_meta_data_by_mid()  : mixed
Delete meta data.
delete_meta_data_value()  : mixed
Delete meta data with a matching value.
generate_meta_cache_key()  : string
Generate cache key from id and group.
get_action()  : object
Get action by action name on the note.
get_actions()  : array<string|int, mixed>
Get actions on the note (if any).
get_allowed_statuses()  : array<string|int, mixed>
Get allowed statuses.
get_allowed_types()  : array<string|int, mixed>
Get allowed types.
get_changes()  : array<string|int, mixed>
Return data changes only.
get_content()  : string
Get note content.
get_content_data()  : object
Get note content data (i.e. values that would be needed for re-localization)
get_data()  : array<string|int, mixed>
Returns all data for this object.
get_data_keys()  : array<string|int, mixed>
Returns array of expected data keys for this object.
get_data_store()  : object
Get the data store.
get_date_created()  : WC_DateTime|null
Get date note was created.
get_date_reminder()  : WC_DateTime|null
Get date on which user should be reminded of the note (if any).
get_extra_data_keys()  : array<string|int, mixed>
Returns all "extra" data keys for an object (for sub objects like product types).
get_id()  : int
Returns the unique ID for this object.
get_image()  : array<string|int, mixed>
Get note image (if any).
get_is_deleted()  : bool
Get deleted status.
get_is_read()  : bool
Get is_read status.
get_is_snoozable()  : bool
Get note snoozability.
get_layout()  : array<string|int, mixed>
Get note layout (the old notes won't have one).
get_locale()  : string
Get note locale.
get_meta()  : mixed
Get Meta Data by Key.
get_meta_cache_key()  : string
Helper method to compute meta cache key. Different from WP Meta cache key in that meta data cached using this key also contains meta_id column.
get_meta_data()  : array<string|int, mixed>
Get All Meta Data.
get_name()  : string
Get note name.
get_object_read()  : bool
Get object read property.
get_source()  : string
Get note source.
get_status()  : string
Get note status.
get_title()  : string
Get note title.
get_type()  : string
Get note type.
init_meta_data()  : mixed
Helper function to initialize metadata entries from filtered raw meta data.
meta_exists()  : bool
See if meta data exists, since get_meta always returns a '' or array().
prime_raw_meta_data_cache()  : mixed
Prime caches for raw meta data. This includes meta_id column as well, which is not included by default in WP meta data.
read_meta_data()  : mixed
Read Meta Data from the database. Ignore any internal properties.
save()  : int
Save should create or update based on object existence.
save_meta_data()  : mixed
Update Meta Data in the database.
set_actions()  : mixed
Set actions on a note.
set_content()  : mixed
Set note content.
set_content_data()  : mixed
Set note data for potential re-localization.
set_date_created()  : mixed
Set date note was created. NULL is not allowed
set_date_reminder()  : mixed
Set date admin should be reminded of note. NULL IS allowed
set_defaults()  : mixed
Set all props to default values.
set_icon()  : mixed
Set note icon (Deprecated).
set_id()  : mixed
Set ID.
set_image()  : mixed
Set note image.
set_is_deleted()  : mixed
Set note deleted status. NULL is not allowed
set_is_read()  : mixed
Set note is_read status. NULL is not allowed
set_is_snoozable()  : mixed
Set note snoozability.
set_layout()  : mixed
Set note layout.
set_locale()  : mixed
Set note locale.
set_meta_data()  : mixed
Set all meta data from array.
set_name()  : mixed
Set note name.
set_object_read()  : mixed
Set object read property.
set_props()  : bool|WP_Error
Set a collection of props in one go, collect any errors, and return the result.
set_source()  : mixed
Set note source.
set_status()  : mixed
Set note status.
set_title()  : mixed
Set note title.
set_type()  : mixed
Set note type.
update_meta_data()  : mixed
Update meta data by key or ID, if provided.
error()  : mixed
When invalid data is found, throw an exception unless reading from the DB.
filter_null_meta()  : bool
Filter null meta values from array.
get_hook_prefix()  : string
Prefix for action and filter hooks on data.
get_prop()  : mixed
Gets a prop for a getter method.
is_internal_meta_key()  : bool
Check if the key is an internal one.
maybe_read_meta_data()  : mixed
Read meta data if null.
set_date_prop()  : mixed
Sets a date prop whilst handling formatting and datetime objects.
set_prop()  : mixed
Sets a prop for a setter method.

Constants

Properties

$default_data

Set to _data on construct so we can track and reset data if needed.

protected array<string|int, mixed> $default_data = array()
Tags
since
3.0.0

$extra_data

Extra data for this object. Name value pairs (name + default value).

protected array<string|int, mixed> $extra_data = array()

Used as a standard way for sub classes (like product types) to add additional information to an inherited class.

Tags
since
3.0.0

$legacy_datastore_props

List of properties that were earlier managed by data store. However, since DataStore is a not a stored entity in itself, they used to store data in metadata of the data object.

protected array<string|int, mixed> $legacy_datastore_props = array()

With custom tables, some of these are moved from metadata to their own columns, but existing code will still try to add them to metadata. This array is used to keep track of such properties.

Only reason to add a property here is that you are moving properties from DataStore instance to data object. If you are adding a new property, consider adding it to to $data array instead.

$object_type

This is the name of this object type.

protected string $object_type = 'admin-note'

Methods

__construct()

Note constructor. Loads note data.

public __construct([mixed $data = '' ]) : mixed
Parameters
$data : mixed = ''

Note data, object, or ID.

Return values
mixed —

__sleep()

Only store the object ID to avoid serializing the data object instance.

public __sleep() : array<string|int, mixed>
Return values
array<string|int, mixed> —

__wakeup()

Re-run the constructor with the object ID.

public __wakeup() : mixed

If the object no longer exists, remove the ID.

Return values
mixed —

add_action()

Add an action to the note

public add_action(string $name, string $label[, string $url = '' ][, string $status = self::E_WC_ADMIN_NOTE_ACTIONED ][, bool $primary = false ][, string $actioned_text = '' ]) : mixed
Parameters
$name : string

Action name (not presented to user).

$label : string

Action label (presented as button label).

$url : string = ''

Action URL, if navigation needed. Optional.

$status : string = self::E_WC_ADMIN_NOTE_ACTIONED

Status to transition parent Note to upon click. Defaults to 'actioned'.

$primary : bool = false

Deprecated since version 3.4.0.

$actioned_text : string = ''

The label to display after the note has been actioned but before it is dismissed in the UI.

Return values
mixed —

add_meta_data()

Add meta data.

public add_meta_data(string $key, string|array<string|int, mixed> $value[, bool $unique = false ]) : mixed
Parameters
$key : string

Meta key.

$value : string|array<string|int, mixed>

Meta value.

$unique : bool = false

Should this be a unique key?.

Tags
since
2.6.0
Return values
mixed —

add_nonce_to_action()

Add a nonce to an existing note action.

public add_nonce_to_action(string $note_action_name, string $nonce_action, string $nonce_name) : void
Parameters
$note_action_name : string

Name of action to add a nonce to.

$nonce_action : string

The nonce action.

$nonce_name : string

The nonce Name. This is used as the paramater name in the resulting URL for the action.

Tags
link
https://codex.wordpress.org/WordPress_Nonces
throws
Exception

If note name cannot be found.

Return values
void —

apply_changes()

Merge changes with data and clear.

public apply_changes() : mixed
Tags
since
3.0.0
Return values
mixed —

clear_actions()

Clear actions from a note.

public clear_actions() : mixed
Return values
mixed —

delete()

Delete an object, set the ID to 0, and return result.

public delete([bool $force_delete = false ]) : bool
Parameters
$force_delete : bool = false

Should the date be deleted permanently.

Tags
since
2.6.0
Return values
bool — result

delete_meta_data()

Delete meta data.

public delete_meta_data(string $key) : mixed
Parameters
$key : string

Meta key.

Tags
since
2.6.0
Return values
mixed —

delete_meta_data_by_mid()

Delete meta data.

public delete_meta_data_by_mid(int $mid) : mixed
Parameters
$mid : int

Meta ID.

Tags
since
2.6.0
Return values
mixed —

delete_meta_data_value()

Delete meta data with a matching value.

public delete_meta_data_value(string $key, mixed $value) : mixed
Parameters
$key : string

Meta key.

$value : mixed

Meta value. Entries will only be removed that match the value.

Tags
since
7.7.0
Return values
mixed —

generate_meta_cache_key()

Generate cache key from id and group.

public static generate_meta_cache_key(int|string $id, string $cache_group) : string
Parameters
$id : int|string

Object ID.

$cache_group : string

Group name use to store cache. Whole group cache can be invalidated in one go.

Tags
since
4.7.0
Return values
string — Meta cache key.

get_action()

Get action by action name on the note.

public get_action(string $action_name[, string $context = 'view' ]) : object
Parameters
$action_name : string

The action name.

$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
object — the action.

get_actions()

Get actions on the note (if any).

public get_actions([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
array<string|int, mixed> —

get_allowed_statuses()

Get allowed statuses.

public static get_allowed_statuses() : array<string|int, mixed>
Return values
array<string|int, mixed> —

get_allowed_types()

Get allowed types.

public static get_allowed_types() : array<string|int, mixed>
Return values
array<string|int, mixed> —

get_changes()

Return data changes only.

public get_changes() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_content()

Get note content.

public get_content([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

get_content_data()

Get note content data (i.e. values that would be needed for re-localization)

public get_content_data([string $context = 'view' ]) : object
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
object —

get_data()

Returns all data for this object.

public get_data() : array<string|int, mixed>

Override \WC_Data::get_data() to avoid errantly including meta data from ID collisions with the posts table.

Return values
array<string|int, mixed> —

get_data_keys()

Returns array of expected data keys for this object.

public get_data_keys() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_date_created()

Get date note was created.

public get_date_created([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
WC_DateTime|null — object if the date is set or null if there is no date.

get_date_reminder()

Get date on which user should be reminded of the note (if any).

public get_date_reminder([string $context = 'view' ]) : WC_DateTime|null
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
WC_DateTime|null — object if the date is set or null if there is no date.

get_extra_data_keys()

Returns all "extra" data keys for an object (for sub objects like product types).

public get_extra_data_keys() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed> —

get_image()

Get note image (if any).

public get_image([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
array<string|int, mixed> —

get_is_deleted()

Get deleted status.

public get_is_deleted([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
bool —

get_is_read()

Get is_read status.

public get_is_read([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
bool —

get_is_snoozable()

Get note snoozability.

public get_is_snoozable([string $context = 'view' ]) : bool
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
bool — Whether or not the note can be snoozed.

get_layout()

Get note layout (the old notes won't have one).

public get_layout([string $context = 'view' ]) : array<string|int, mixed>
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
array<string|int, mixed> —

get_locale()

Get note locale.

public get_locale([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

get_meta()

Get Meta Data by Key.

public get_meta([string $key = '' ][, bool $single = true ][, string $context = 'view' ]) : mixed
Parameters
$key : string = ''

Meta Key.

$single : bool = true

return first found meta with key, or all with $key.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
2.6.0
Return values
mixed —

get_meta_cache_key()

Helper method to compute meta cache key. Different from WP Meta cache key in that meta data cached using this key also contains meta_id column.

public get_meta_cache_key() : string
Tags
since
4.7.0
Return values
string —

get_meta_data()

Get All Meta Data.

public get_meta_data() : array<string|int, mixed>
Tags
since
2.6.0
Return values
array<string|int, mixed> — of objects.

get_name()

Get note name.

public get_name([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

get_source()

Get note source.

public get_source([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

get_status()

Get note status.

public get_status([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

get_title()

Get note title.

public get_title([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

get_type()

Get note type.

public get_type([string $context = 'view' ]) : string
Parameters
$context : string = 'view'

What the value is for. Valid values are 'view' and 'edit'.

Return values
string —

init_meta_data()

Helper function to initialize metadata entries from filtered raw meta data.

public init_meta_data([array<string|int, mixed> $filtered_meta_data = array() ]) : mixed
Parameters
$filtered_meta_data : array<string|int, mixed> = array()

Filtered metadata fetched from DB.

Return values
mixed —

meta_exists()

See if meta data exists, since get_meta always returns a '' or array().

public meta_exists([string $key = '' ]) : bool
Parameters
$key : string = ''

Meta Key.

Tags
since
3.0.0
Return values
bool —

prime_raw_meta_data_cache()

Prime caches for raw meta data. This includes meta_id column as well, which is not included by default in WP meta data.

public static prime_raw_meta_data_cache(array<string|int, mixed> $raw_meta_data_collection, string $cache_group) : mixed
Parameters
$raw_meta_data_collection : array<string|int, mixed>

Array of objects of { object_id => array( meta_row_1, meta_row_2, ... }.

$cache_group : string

Name of cache group.

Tags
since
4.7.0
Return values
mixed —

read_meta_data()

Read Meta Data from the database. Ignore any internal properties.

public read_meta_data([bool $force_read = false ]) : mixed

Uses it's own caches because get_metadata does not provide meta_ids.

Parameters
$force_read : bool = false

True to force a new DB read (and update cache).

Tags
since
2.6.0
Return values
mixed —

set_actions()

Set actions on a note.

public set_actions(array<string|int, mixed> $actions) : mixed
Parameters
$actions : array<string|int, mixed>

Note actions.

Return values
mixed —

set_content()

Set note content.

public set_content(string $content) : mixed
Parameters
$content : string

Note content.

Return values
mixed —

set_content_data()

Set note data for potential re-localization.

public set_content_data(object $content_data) : mixed
Parameters
$content_data : object

Note data.

Tags
todo

Set a default empty array? https://github.com/woocommerce/woocommerce-admin/pull/1763#pullrequestreview-212442921.

Return values
mixed —

set_date_created()

Set date note was created. NULL is not allowed

public set_date_created(string|int $date) : mixed
Parameters
$date : string|int

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed.

Return values
mixed —

set_date_reminder()

Set date admin should be reminded of note. NULL IS allowed

public set_date_reminder(string|int|null $date) : mixed
Parameters
$date : string|int|null

UTC timestamp, or ISO 8601 DateTime. If the DateTime string has no timezone or offset, WordPress site timezone will be assumed. Null if there is no date.

Return values
mixed —

set_icon()

Set note icon (Deprecated).

public set_icon(string $icon) : mixed
Parameters
$icon : string

Note icon.

Return values
mixed —

set_image()

Set note image.

public set_image(string $image) : mixed
Parameters
$image : string

Note image.

Return values
mixed —

set_is_deleted()

Set note deleted status. NULL is not allowed

public set_is_deleted(bool $is_deleted) : mixed
Parameters
$is_deleted : bool

Note deleted status.

Return values
mixed —

set_is_read()

Set note is_read status. NULL is not allowed

public set_is_read(bool $is_read) : mixed
Parameters
$is_read : bool

Note is_read status.

Return values
mixed —

set_is_snoozable()

Set note snoozability.

public set_is_snoozable(bool $is_snoozable) : mixed
Parameters
$is_snoozable : bool

Whether or not the note can be snoozed.

Return values
mixed —

set_layout()

Set note layout.

public set_layout(string $layout) : mixed
Parameters
$layout : string

Note layout.

Return values
mixed —

set_locale()

Set note locale.

public set_locale(string $locale) : mixed
Parameters
$locale : string

Note locale.

Return values
mixed —

set_meta_data()

Set all meta data from array.

public set_meta_data(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>

Key/Value pairs.

Tags
since
2.6.0
Return values
mixed —

set_name()

Set note name.

public set_name(string $name) : mixed
Parameters
$name : string

Note name.

Return values
mixed —

set_object_read()

Set object read property.

public set_object_read([bool $read = true ]) : mixed
Parameters
$read : bool = true

Should read?.

Tags
since
3.0.0
Return values
mixed —

set_props()

Set a collection of props in one go, collect any errors, and return the result.

public set_props(array<string|int, mixed> $props[, string $context = 'set' ]) : bool|WP_Error

Only sets using public methods.

Parameters
$props : array<string|int, mixed>

Key value pairs to set. Key is the prop and should map to a setter function name.

$context : string = 'set'

In what context to run this.

Tags
since
3.0.0
Return values
bool|WP_Error —

set_source()

Set note source.

public set_source(string $source) : mixed
Parameters
$source : string

Note source.

Return values
mixed —

set_status()

Set note status.

public set_status(string $status) : mixed
Parameters
$status : string

Note status.

Return values
mixed —

set_title()

Set note title.

public set_title(string $title) : mixed
Parameters
$title : string

Note title.

Return values
mixed —

set_type()

Set note type.

public set_type(string $type) : mixed
Parameters
$type : string

Note type.

Return values
mixed —

update_meta_data()

Update meta data by key or ID, if provided.

public update_meta_data(string $key, string|array<string|int, mixed> $value, int $meta_id) : mixed
Parameters
$key : string

Meta key.

$value : string|array<string|int, mixed>

Meta value.

$meta_id : int

Meta ID.

Tags
since
2.6.0
Return values
mixed —

error()

When invalid data is found, throw an exception unless reading from the DB.

protected error(string $code, string $message[, int $http_status_code = 400 ][, array<string|int, mixed> $data = array() ]) : mixed
Parameters
$code : string

Error code.

$message : string

Error message.

$http_status_code : int = 400

HTTP status code.

$data : array<string|int, mixed> = array()

Extra error data.

Tags
throws
WC_Data_Exception

Data Exception.

since
3.0.0
Return values
mixed —

filter_null_meta()

Filter null meta values from array.

protected filter_null_meta(mixed $meta) : bool
Parameters
$meta : mixed

Meta value to check.

Tags
since
3.0.0
Return values
bool —

get_prop()

Gets a prop for a getter method.

protected get_prop(string $prop[, string $context = 'view' ]) : mixed

Gets the value from either current pending changes, or the data itself. Context controls what happens to the value before it's returned.

Parameters
$prop : string

Name of prop to get.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
3.0.0
Return values
mixed —

is_internal_meta_key()

Check if the key is an internal one.

protected is_internal_meta_key(string $key) : bool
Parameters
$key : string

Key to check.

Tags
since
3.2.0
Return values
bool — true if it's an internal key, false otherwise

set_date_prop()

Sets a date prop whilst handling formatting and datetime objects.

protected set_date_prop(string $prop, string|int $value) : mixed
Parameters
$prop : string

Name of prop to set.

$value : string|int

Value of the prop.

Tags
since
3.0.0
Return values
mixed —

set_prop()

Sets a prop for a setter method.

protected set_prop(string $prop, mixed $value) : mixed

This stores changes in a special array so we can track what needs saving the DB later.

Parameters
$prop : string

Name of prop to set.

$value : mixed

Value of the prop.

Tags
since
3.0.0
Return values
mixed —