The access API is a handful of PHP functions that give a user an access group, take it away, and read what the user holds and may open. WooCommerce, registration and the Members screen call the same functions.
Use them when access comes from something Smart Members doesn't know about: another cart, an invite code, a partner's system. They ship in the free plugin and are available from plugins_loaded on.
smartmembers_grant()
smartmembers_grant( int $user_id, int|string $group, array $context = array() ): Grant|WP_Error
$group is an ID or the exact name. Returns a SmartMembers\Access\Grant, or a WP_Error saying why nothing was written.
$context key | What it does |
|---|---|
source | Who granted it. Default manual. Used by revoke. |
source_object, source_id | The object in your system. With source, makes the call idempotent. |
started_at | MySQL datetime; default now. Drip counts from it. |
expires_at | MySQL datetime (UTC), or null for never. Empty uses the group's Membership length. |
trial_until | Without a status, stores the grant as trial. |
status | Default active. |
tied_to | External object the grant lives and dies with, such as a subscription. |
actor | The person responsible. Defaults to the current user. |
A live grant from the same source object is returned as is, so a retried webhook cannot grant twice. Otherwise smartmembers_should_grant may veto, the group's rules run (active, availability dates, member caps), the row is written, roles sync and smartmembers_access_granted fires.
// Error codes
invalid_user // user ID was 0 or negative
group_not_found // no group with that ID or name
grant_vetoed // smartmembers_should_grant returned false
group_inactive // the group is switched off
group_not_yet_available // outside the group's availability dates
group_no_longer_available
group_full // member cap reached
group_user_limit_reached // per-user cap reached
grant_held // revoked by another source; not revived automatically
member_not_found, grant_failed, grant_raced // database write failed
$grant = smartmembers_grant( $user_id, 672, array(
'source' => 'gift-form',
'source_object' => 'entry',
'source_id' => (string) $entry_id,
'expires_at' => gmdate( 'Y-m-d H:i:s', strtotime( '+30 days' ) ),
) );
if ( is_wp_error( $grant ) ) {
error_log( $grant->get_error_code() . ': ' . $grant->get_error_message() );
return;
}
smartmembers_revoke()
smartmembers_revoke( int $user_id, int|string $group, array $context = array() ): bool
Returns true when at least one live grant was revoked, and fires smartmembers_access_revoked for each.
$context key | What it does |
|---|---|
source | Only revoke grants from this source. Left out, or manual, revokes every grant for the group. |
source_object, source_id, tied_to | Narrow to one object. |
reason | expired marks it expired; anything else, cancelled. Default revoked. |
quiet | True skips the "access ended" email. |
Warning: A bare smartmembers_revoke( 42, 672 ) removes every Reader grant Rosa holds, including one she bought. Pass the source you granted with.
smartmembers_revoke( $user_id, 672, array(
'source' => 'gift-form',
'source_object' => 'entry',
'source_id' => (string) $entry_id,
'reason' => 'gift_cancelled',
) );
smartmembers_get_grants()
Every grant a user holds, live or not; an empty array for a blocked user. is_live() says whether a grant opens content now.
smartmembers_get_grants( int $user_id ): Grant[]
// Grant properties: id, user_id, access_group_id, status, source, source_object,
// source_id, tied_to, started_at, expires_at, paused_at, trial_until, seat_of, actor.
// Methods: is_live(), to_array().
foreach ( smartmembers_get_grants( 42 ) as $grant ) {
printf( "%d %s %s\n", $grant->access_group_id, $grant->source, $grant->is_live() ? 'live' : 'ended' );
}
// 671 registration live
// 672 manual live
Checking access
// Full answer. $object_type: 'post', 'url' (pass the path) or 'archive'. 0 = visitor.
smartmembers_check_access( int $user_id, string $object_type = 'post', int|string $object_id = 0 ): AccessResult
// Yes or no. null = current user. Note the argument order.
smartmembers_can_access( ?int $user_id, int|string $object_id, string $object_type = 'post' ): bool
// Live grant for any of the groups (IDs or names, case-insensitive).
smartmembers_user_holds_group( int $user_id, array $groups ): bool
// The refusal HTML Smart Members would show.
smartmembers_restriction_message( AccessResult $result, int $post_id = 0 ): string
// Member rather than staff (manage_options or edit_posts is never a member).
smartmembers_user_is_member( ?int $user_id = null ): bool
// Feature available on this site. Unknown slugs return false.
smartmembers_capability_available( string $slug ): bool
// AccessResult: allowed, reason, unlocks_at, required_groups, rule_id, mode, message
// reason: public | granted | no_group | expired | paused | dripping | denied | logged_out
// mode: hide | hide_content | redirect
smartmembers_check_access( 0, 'post', 1595 );
// allowed: false, reason: logged_out, required_groups: [672], mode: hide_content
A dripping result means the member holds the group but the post is not open yet; unlocks_at holds the date, and the page shows it instead of the group's redirect or substitute page.
Blocking and caches
// Refuse every group without deleting grants. Fires smartmembers_user_blocked.
smartmembers_block_user( int $user_id, ?int $actor = null ): bool
// Restore everything, dates and sources included. Fires smartmembers_user_unblocked.
smartmembers_unblock_user( int $user_id ): bool
smartmembers_user_is_blocked( int $user_id ): bool
// Grant and revoke call this already; use it after writing grants another way.
smartmembers_flush_access_cache( ?int $user_id = null )
Behaviour to know about
- Staff see everything. Test with a member ID or 0.
- Expiry takes effect on read. Within the hour,
smartmembers_expire_grantsrevokes the grant with reasonexpired, andsmartmembers_access_revokedfires. - The member login and registration pages are always open, even under a whole-site rule.
- Don't write rules directly. Filter them with
smartmembers_compiled_access_rules. - From another server, receive the call in a WordPress plugin and call
smartmembers_grant()there.