{"id":11088,"date":"2014-09-24T19:21:45","date_gmt":"2014-09-24T19:21:45","guid":{"rendered":"http:\/\/developer.wordpress.org\/?post_type=plugin-handbook&p=11088"},"modified":"2022-11-17T06:43:34","modified_gmt":"2022-11-17T06:43:34","slug":"working-with-user-metadata","status":"publish","type":"plugin-handbook","link":"https:\/\/developer.wordpress.org\/plugins\/users\/working-with-user-metadata\/","title":{"rendered":"Working with User Metadata"},"content":{"rendered":"\n

Introduction<\/h2>\n\n\n\n

WordPress’ users<\/code> table was designed to contain only the essential information about the user.<\/p>\n\n\n\n

\n
<\/div>\n

\nAs of WP 4.7 the table contains: ID<\/code>, user_login<\/code>, user_pass<\/code>, user_nicename<\/code>, user_email<\/code>, user_url<\/code>, user_registered<\/code>, user_activation_key<\/code>, user_status<\/code> and display_name<\/code>.
\n<\/div><\/div>\n\n\n\n\n

Because of this, to store additional data, the usermeta<\/code> table was introduced, which can store any arbitrary amount of data about a user.<\/p>\n\n\n\n

Both tables are tied together using one-to-many relationship based on the ID<\/code> in the users<\/code> table.<\/p>\n\n\n\n

Manipulating User Metadata<\/h2>\n\n\n\n

There are two main ways for manipulating User Metadata.<\/p>\n\n\n\n

    \n
  1. A form field in the user’s profile screen.<\/li>\n\n\n\n
  2. Programmatically, via a function call.<\/li>\n<\/ol>\n\n\n\n

    via a Form Field<\/h3>\n\n\n\n

    The form field option is suitable for cases where the user will have access to the WordPress admin area, in which he will be able to view and edit profiles.<\/p>\n\n\n\n

    Before we dive into an example, it’s important to understand the hooks involved in the process and why they are there.<\/p>\n\n\n\n

    show_user_profile<\/code> hook<\/h4>\n\n\n\n

    This action hook is fired whenever a user edits it’s own<\/strong> user profile.<\/p>\n\n\n\n

    Remember,<\/strong> a user that doesn’t have the capability of editing his own profile won’t fire this hook.<\/p>\n\n\n\n

    edit_user_profile<\/code> hook<\/h4>\n\n\n\n

    This action hook is fired whenever a user edits a user profile of somebody else<\/strong>.<\/p>\n\n\n\n

    Remember,<\/strong> a user that doesn’t have the capability for editing 3rd party profiles won’t fire this hook.<\/p>\n\n\n\n

    Example Form Field<\/h4>\n\n\n\n

    In the example below we will be adding a birthday field to the all profile screens. Saving it to the database on profile updates.<\/p>\n\n\n\n

    \/**\n * The field on the editing screens.\n *\n * @param $user WP_User user object\n *\/\nfunction wporg_usermeta_form_field_birthday( $user ) {\n    ?>\n    <h3>It's Your Birthday<\/h3>\n    <table class=\"form-table\">\n        <tr>\n            <th>\n                <label for=\"birthday\">Birthday<\/label>\n            <\/th>\n            <td>\n                <input type=\"date\"\n                       class=\"regular-text ltr\"\n                       id=\"birthday\"\n                       name=\"birthday\"\n                       value=\"<?= esc_attr( get_user_meta( $user->ID, 'birthday', true ) ) ?>\"\n                       title=\"Please use YYYY-MM-DD as the date format.\"\n                       pattern=\"(19[0-9][0-9]|20[0-9][0-9])-(1[0-2]|0[1-9])-(3[01]|[21][0-9]|0[1-9])\"\n                       required>\n                <p class=\"description\">\n                    Please enter your birthday date.\n                <\/p>\n            <\/td>\n        <\/tr>\n    <\/table>\n    <?php\n}\n \n\/**\n * The save action.\n *\n * @param $user_id int the ID of the current user.\n *\n * @return bool Meta ID if the key didn't exist, true on successful update, false on failure.\n *\/\nfunction wporg_usermeta_form_field_birthday_update( $user_id ) {\n    \/\/ check that the current user have the capability to edit the $user_id\n    if ( ! current_user_can( 'edit_user', $user_id ) ) {\n        return false;\n    }\n \n    \/\/ create\/update user meta for the $user_id\n    return update_user_meta(\n        $user_id,\n        'birthday',\n        $_POST['birthday']\n    );\n}\n \n\/\/ Add the field to user's own profile editing screen.\nadd_action(\n    'show_user_profile',\n    'wporg_usermeta_form_field_birthday'\n);\n \n\/\/ Add the field to user profile editing screen.\nadd_action(\n    'edit_user_profile',\n    'wporg_usermeta_form_field_birthday'\n);\n \n\/\/ Add the save action to user's own profile editing screen update.\nadd_action(\n    'personal_options_update',\n    'wporg_usermeta_form_field_birthday_update'\n);\n \n\/\/ Add the save action to user profile editing screen update.\nadd_action(\n    'edit_user_profile_update',\n    'wporg_usermeta_form_field_birthday_update'\n);<\/code><\/pre>\n\n\n\n
    Programmatically<\/h3>\n\n\n\n
    This option is suitable for cases where you’re building a custom user area and\/or plan to disable access to the WordPress admin area.<\/p>\n\n\n\n
    The functions available for manipulating User Metadata are: add_user_meta()<\/a><\/code>, update_user_meta()<\/a><\/code>, delete_user_meta()<\/a><\/code> and get_user_meta()<\/a><\/code>.<\/p>\n\n\n\n
    Add<\/h4>\n\n\n\n
    add_user_meta(\n    int $user_id,\n    string $meta_key,\n    mixed $meta_value,\n    bool $unique = false\n);<\/code><\/pre>\n\n\n\n
    Please refer to the Function Reference about add_user_meta()<\/a><\/code> for full explanation about the used parameters.<\/p>\n\n\n\n
    Update<\/h4>\n\n\n\n
    update_user_meta(\n    int $user_id,\n    string $meta_key,\n    mixed $meta_value,\n    mixed $prev_value = ''\n);<\/code><\/pre>\n\n\n\n
    Please refer to the Function Reference about update_user_meta()<\/a><\/code> for full explanation about the used parameters.<\/p>\n\n\n\n
    Delete<\/h4>\n\n\n\n
    delete_user_meta(\n    int $user_id,\n    string $meta_key,\n    mixed $meta_value = ''\n);<\/code><\/pre>\n\n\n\n
    Please refer to the Function Reference about delete_user_meta()<\/a><\/code> for full explanation about the used parameters.<\/p>\n\n\n\n
    Get<\/h4>\n\n\n\n
    get_user_meta(\n    int $user_id,\n    string $key = '',\n    bool $single = false\n);<\/code><\/pre>\n\n\n\n
    Please refer to the Function Reference about get_user_meta()<\/a><\/code> for full explanation about the used parameters.<\/p>\n\n\n\n
    Please note, if you pass only the $user_id<\/code>, the function will retrieve all Metadata as an associative array.<\/p>\n\n\n\n
    You can render User Metadata anywhere in your plugin or theme.<\/p>\n","protected":false},"author":12560283,"featured_media":0,"parent":11084,"menu_order":0,"template":"","meta":{"_crdt_document":"","footnotes":""},"class_list":["post-11088","plugin-handbook","type-plugin-handbook","status-publish","hentry","type-handbook"],"revision_note":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/plugin-handbook\/11088","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/plugin-handbook"}],"about":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/types\/plugin-handbook"}],"author":[{"embeddable":true,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/users\/12560283"}],"version-history":[{"count":29,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/plugin-handbook\/11088\/revisions"}],"predecessor-version":[{"id":144404,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/plugin-handbook\/11088\/revisions\/144404"}],"up":[{"embeddable":true,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/plugin-handbook\/11084"}],"wp:attachment":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/media?parent=11088"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}