LocalHero Org

Helping Organisations get organised!

MCP Abilities

Part of LH Profile Page

Create or Fill User

lh-profile-page/create-or-fill-user Idempotent

Creates a user (unclaimed role, current site) from name, email, core user fields (user_url, nickname, display_name, description) and profile fields, or – when existing_user is fill_missing and the email (or a registered email alias) already belongs to an account – fills only what that account is missing. The email is lowercased before lookup and creation. unclaimed is the only role it assigns: an existing user with no account on the current site is added with it, and one with an account but no role on the site is given it; a user who already has a role on the site keeps it. Never overwrites an existing value, except that a nickname or display name still set to a placeholder (an email address or the login) counts as empty; the address (street_address, town, postcode) is filled as one unit only when all three are empty. user_nicename cannot be set. Invalid values are reported per field and never stored. No membership or group changes for existing users. For an existing user, action is unchanged when nothing was or would be filled and the user already had a role on the site. dry_run defaults to true: set it to false to write. Requires promote_users.

Parameter Type Required Default Description
email string Yes Email address. Lowercased, then used as the login for a new user, and to find an existing one (including registered email aliases).
first_name string No First name. For an existing user, only filled if currently empty.
last_name string No Last name. For an existing user, only filled if currently empty.
user_url string No Website, e.g. a supplier’s site. http or https only; a bare domain such as example.com is given https://. At most 100 characters. For an existing user, only filled if currently empty.
nickname string No Nickname. For an existing user, only filled if currently empty or still a placeholder (an email address or the login).
display_name string No Display name, e.g. a supplier’s trading name. For a new user it replaces the name built from first_name and last_name; for an existing user it is only filled if currently empty or still a placeholder (an email address or the login). At most 250 characters.
description string No Biographical info. Line breaks are kept and HTML is removed. For an existing user, only filled if currently empty.
group_id integer No Optional BuddyPress group to add a NEW user to. Ignored for existing users.
existing_user string No "refuse" What to do when the email already belongs to an account: refuse (return an error, change nothing) or fill_missing. One of: refuse, fill_missing.
dry_run boolean No true When true (the default) nothing is written; the result reports what would happen.
fields object No Profile fields. Each is only filled if the user currently has no value for it; the address (street_address, town, postcode) is filled as one unit, only when all three are empty. Invalid values are reported per field and never stored.

Search Users by Profile Fields

lh-profile-page/search-users Read-only Idempotent

Searches WordPress users on the current site by user ID and any combination of account and profile fields: id (exact user IDs; always a restriction on top of the other fields), email, user_login and display_name (partial), phone (primary and secondary, partial match against digits only, tolerant of spacing/formatting, stored values are E.164), first_name/last_name (partial), gender (exact match, one of: Male, Female, Organisation, Robot – case-sensitive, no other values are ever stored), country/state_province/town/street_address (partial), postcode (exact), and birthdate_before/birthdate_after (single date bounds, not arrays, forming an inclusive range). Every other field parameter accepts an array of values OR-ed together within that field; match_mode controls whether the fields combine with AND (default) or OR across each other. Page with limit and offset. Each result includes the user’s login and their roles on the current site. Results are always restricted to users with an account on the current site. Other active plugins can add search parameters and result fields; the input and output schemas list them. Requires promote_users.

Parameter Type Required Default Description
id array of integer No Exact user IDs. Always a restriction on top of the other fields, whatever match_mode is.
phone array of string No Phone numbers, matched against primary and secondary phone by digits only, so spacing and a leading 0 do not matter.
email array of string No Partial matches on the account email.
user_login array of string No Partial matches on the username.
first_name array of string No Partial matches on first name.
last_name array of string No Partial matches on last name.
display_name array of string No Partial matches on display name.
gender array of string No Exact gender values, case-sensitive.
country array of string No Partial matches on country.
state_province array of string No Partial matches on state or province.
town array of string No Partial matches on town.
postcode array of string No Exact postcodes.
street_address array of string No Partial matches on street address.
birthdate_before string No Born on or before this date, Y-m-d. A single date, not an array.
birthdate_after string No Born on or after this date, Y-m-d. A single date, not an array.
match_mode string No "all" all (the default) requires every field given to match; any requires at least one. One of: all, any.
limit integer No 20 Users to return, 1 to 100. Default 20.
offset integer No 0 Users to skip, for paging. Default 0.
is_member boolean No Membership of this site (LH Membership): true for members of any member type, false for users who are not members. A hard restriction whatever match_mode is.
member_type array of string No LH Membership member type slugs, OR-ed: members of any of these types. A hard restriction whatever match_mode is. An unknown slug returns an error listing the member types on this site.

Set User Roles

lh-profile-page/set-user-roles Idempotent

Adds and removes roles for one user on the current site. Only roles the caller could assign in wp-admin are accepted, and never a privileged role: one whose capabilities include promote_users, edit_users, manage_options or install_plugins (such as administrator). A user who already holds a privileged role, a super admin and the calling account are refused, as is a user with no account on the current site (use create-or-fill-user to add one). A change that would leave the user with no role is refused. Every role is checked before anything is written, so one refused role changes nothing. Roles already held (in add) or not held (in remove) are reported and left alone, so repeating a call is safe. dry_run defaults to true: set it to false to write. Returns roles before and after. Requires promote_users, plus promote_user on the target user.

Parameter Type Required Default Description
user_id integer Yes The user whose roles on the current site change.
add array of string No Role slugs to add, e.g. author.
remove array of string No Role slugs to remove.
dry_run boolean No true When true (the default) nothing is written; the result reports what would happen.

If you like this plugin please consider making a donation to further development