# \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 ) ) { ... }

To directly access the API object use the property `MS_Plugin::$api`. Note: Before `ms_active` is called `MS_Plugin::$api` will return false. This should only be used in rare cases when you know that the API is available; it's better to use the action `ms_init` for API access.

    // Same as above.
    if ( MS_Plugin::$api ) { ... }

## Summary

Methods
Properties
Constants
get_member()
get_current_member()
get_membership()
get_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

File
  controller/class-ms-controller-api.php
Package
  Membership2\Controller
Class hierarchy
  \MS_Controller
  \MS_Controller_Api

## Tags

since |

## Properties

### $settings

    $settings : \MS_Model_Settings

A reference to the Membership2 settings object.

#### Type

\MS_Model_Settings

#

## Tags

since |
api |

## Methods

### 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.

#

## Tags

since | 1.0.0
api |

### get_current_member()

    get_current_member() : \MS_Model_Member

Returns the Member object of the current user.

#### Returns

\MS_Model_Member —

The Member model.

#

## Tags

since | 1.0.0
api |

### get_membership()

    get_membership(integer  $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 | $membership_id | A specific membership ID.

#### Returns

\MS_Model_Membership —

The membership object.

#

## Tags

since | 1.0.0
api |

### get_subscription()

    get_subscription(integer  $user_id, integer  $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 | $membership_id | A specific membership ID.

#### Returns

\MS_Model_Relationship|false —

The subscription object.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.1.0

### register_payment_gateway()

    register_payment_gateway(string  $id, string  $class)

Create your own payment gateway and hook it up with Memberhip 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.

#

## Tags

since | 1.0.1.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### class-ms-controller-api.php