\MS_Controller_Api

Exposes the public API.

The simplest way to use the API is via an WordPress action ms_init that runs some code as soon as the API becomes available:

// Run some code as early as possible.
add_action( 'ms_init', 'my_api_hook' );
function my_api_hook( $api ) {
    $memberships = $api->list_memberships();
}

Recommended implementation structure

class My_Membership2_Implementation {
    protected $api = null;

    // Function is always executed. Will create 1 Implementation object.
    static public function setup() {
        static $Inst = null;
        if ( null === $Inst ) {
            $Inst = new My_Membership2_Implementation();
        }
    }

    // Function set up the api hook.
    private function __construct() {
        add_action( 'ms_init', array( $this, 'init' ) );
    }

    // Function is only run when Membership2 is present + active.
    public function init( $api ) {
        $this->api = $api;
        // The main init code should come here now!
    }

    // Add other event handlers and helper functions.
    // You can use $this->api in other functions to access the API object.
}
My_Membership2_Implementation::setup();

We also add the WordPress filter ms_active to check if the plugin is enabled and loaded. As long as this filter returns false the API cannot be used:

// Check if the API object is available.
if ( apply_filters( 'ms_active', false ) ) { ... }

Different ways to access the M2 API object:

// 1. Our recommendation:
add_action( 'ms_init', 'my_api_hook' );
function my_api_hook( $api ) {
}

// 2. Use a procedural approach. Use in init hook or later!
$api = ms_api();

// 3. Not recommended: Direct access to the `$api` property:
$api = MS_Plugin::$api;

// 4. Not recommended: Singleton access:
$api = MS_Controller_Api::instance();

Summary

Methods
Properties
Constants
instance()
admin_init()
get_member()
get_current_member()
get_membership()
get_membership_id()
get_subscription()
add_subscription()
list_memberships()
detect_membership()
register_payment_gateway()
debug()
$settings
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Properties

$settings

$settings : \MS_Model_Settings

A reference to the Membership2 settings object.

Type

\MS_Model_Settings

Methods

instance()

instance() : \MS_Controller_Api

Returns the singleton object.

Returns

\MS_Controller_Api

admin_init()

admin_init() 

Maintain compatibility with MS_Controller interface.

get_member()

get_member(integer  $user_id) : \MS_Model_Member|false

Returns either the current member or the member with the specified id.

If the specified user does not exist then false is returned.

// Useful functions of the Member object:
$member->has_membership( $membership_id )
$member->get_subscription( $membership_id )

Parameters

integer $user_id

User_id

Returns

\MS_Model_Member|false —

The Member model.

get_current_member()

get_current_member() : \MS_Model_Member

Returns the Member object of the current user.

Returns

\MS_Model_Member

The Member model.

get_membership()

get_membership(integer|string  $membership_id) : \MS_Model_Membership

Returns a single membership object.

Other plugins can store and accuess custom settings for each membership:

// Create a custom value in the membership
$membership->set_custom_data( 'the_key', 'the_value' );
$membership->save(); // Custom data is now saved to database.

// Access and delete the custom value
$value = $membership->get_custom_data( 'the_key' );
$membership->delete_custom_data( 'the_key' );
$membership->save(); // Custom data is now deleted from database.

Parameters

integer|string $membership_id

The membership-ID or name/slug.

Returns

\MS_Model_Membership

The membership object.

get_membership_id()

get_membership_id(string  $name_or_slug) : integer|false

Returns the membership-ID that matches the specified Membership name or slug.

If multiple memberships have the same name then the one with the lowest ID (= the oldest) will be returned.

Name or slug are case-IN-sensitive ('slug' and 'SLUG' are identical) Wildcards are not allowed, the string must match exactly.

Parameters

string $name_or_slug

The Membership name or slug to search.

Returns

integer|false —

The membership ID or false.

get_subscription()

get_subscription(integer  $user_id, integer|string  $membership_id) : \MS_Model_Relationship|false

Returns a single subscription object of the specified user.

If the user did not subscribe to the given membership then false is returned.

Each subscription also offers custom data fields (see the details in get_membership() for details)

Parameters

integer $user_id

The user ID.

integer|string $membership_id

The membership-ID or name/slug.

Returns

\MS_Model_Relationship|false —

The subscription object.

add_subscription()

add_subscription(integer  $user_id, integer|string  $membership_id) : \MS_Model_Relationship|null

Add a new subscription for the specified user.

If the membership is free the subscription instantly is ACTIVE. Otherwise the subscription is set to PENDING until the user makes the payment via the M2 checkout page.

Parameters

integer $user_id

The User-ID.

integer|string $membership_id

The membership-ID or name/slug.

Returns

\MS_Model_Relationship|null —

The new subscription object.

list_memberships()

list_memberships(boolean  $list_all = false) : array<mixed,\MS_Model_Membership>

Returns a list of all available Memberships.

Parameters

boolean $list_all

If set to true then also private and internal Memberships (e.g. Guest Membership) are included. Default is false which returns only memberships that a guest user can subscribe to.

Returns

array<mixed,\MS_Model_Membership> —

List of all available Memberships.

detect_membership()

detect_membership() : false|\MS_Model_Membership

Tries to determine the currently displayed membership.

Detection logic:

  1. If a valid preferred value was specified then this value is used.
  2. Examine REQUEST data and look for membership/subscription/invoice.
  3. Check currently logged in user and use the top-priority subscription.
  4. If no membership could be detected the response value is bool FALSE.

Returns

false|\MS_Model_Membership

The detected Membership or false.

register_payment_gateway()

register_payment_gateway(string  $id, string  $class) 

Create your own payment gateway and hook it up with Membership 2 by using this function!

Creating your own payment gateway requires good php skills. To get you started follow these steps:

  1. Copy the folder "/app/gateway/manual" to the "wp-contents/plugins" folder, and name it "membership-mygateway"

  2. Rename all files inside the "membership-mygateway" and replace the term "manual" with "mygateway"

  3. Edit all files, rename the class names inside the files to "_Mygateway" (replacing "_Manual")

  4. In class MS_Gateway_Mygateway make following changes:

    • Set the value of const ID to "mygateway"

    • Change the assigned name in function "after_load"

    • Add a plugin header to the file, e.g. /*

      • Plugin name: Membership 2 Mygateway
      • /
    • Add the following line to the bottom of the file: add_action( 'ms_init', 'mygateway_register' ); function mygateway_register( $api ) { $api->register_payment_gateway( MS_Gateway_Mygateway::ID, 'MS_Gateway_Mygateway' ) }

Now you have created a new plugin that registers a custom payment gateway for Membership 2! Implementing the payment logic is up to you - you can get a lot of insight by reviewing the existing payment gateways.

Parameters

string $id

The ID of the new gateway.

string $class

The Class-name of the new gateway.

debug()

debug(mixed  $data) 

Membership2 has a nice integrated debugging feature. This feature can be helpful for other developers so this API offers a simple way to access the debugging feature.

Also note that all membership objects come with the built-in debug function $obj->dump() to quickly analyze the object.

// Example of $obj->dump() usage
$user = MS_Plugin::$api->current_member();
$user->dump();

Parameters

mixed $data

The value to dump to the output stream.