MS_Controller_Api

Exposes the public API.

Defined (1)

The class is defined in the following location(s).

/app/controller/class-ms-controller-api.php  
  1. class MS_Controller_Api extends MS_Hooker { 
  2.  
  3. /** 
  4. * A reference to the Membership2 settings object. 
  5. * @since 1.0.0 
  6. * @api 
  7. * @var MS_Model_Settings 
  8. */ 
  9. public $settings = null; 
  10.  
  11. /** 
  12. * Stores a list of custom payment gateways. 
  13. * @since 1.0.1.0 
  14. * @internal 
  15. * @var array 
  16. */ 
  17. protected $gateways = array(); 
  18.  
  19. /** 
  20. * Returns the singleton object. 
  21. * @since 1.0.1.2 
  22. * @return MS_Controller_Api 
  23. */ 
  24. static public function instance() { 
  25. static $Inst = null; 
  26.  
  27. if ( null === $Inst ) { 
  28. $Inst = new MS_Controller_Api(); 
  29.  
  30. return $Inst; 
  31.  
  32. /** 
  33. * Private constructor: Singleton pattern. 
  34. * @since 1.0.0 
  35. * @internal 
  36. */ 
  37. protected function __construct() { 
  38. $this->settings = MS_Plugin::instance()->settings; 
  39.  
  40. /** 
  41. * Simple check to allow other plugins to quickly find out if 
  42. * Membership2 is loaded and the API was initialized. 
  43. * Example: 
  44. * if ( apply_filters( 'ms_active', false ) ) { ... } 
  45. * @since 1.0.0 
  46. */ 
  47. add_filter( 'ms_active', '__return_true' ); 
  48.  
  49. /** 
  50. * Make the API controller accessible via static property. 
  51. * Example: 
  52. * $api = MS_Plugin::$api; 
  53. * Alternative: 
  54. * $api = apply_filters( 'ms_api', false ); 
  55. * @since 1.0.0 
  56. */ 
  57. MS_Plugin::set_api( $this ); 
  58.  
  59. /** 
  60. * Notify other plugins that Membership2 is ready. 
  61. * @since 1.0.0 
  62. */ 
  63. do_action( 'ms_init', $this ); 
  64.  
  65. /** 
  66. * Maintain compatibility with MS_Controller interface. 
  67. * @since 1.0.1.2 
  68. */ 
  69. public function admin_init() { } 
  70.  
  71. /** 
  72. * Returns either the current member or the member with the specified id. 
  73. * If the specified user does not exist then false is returned. 
  74. * // Useful functions of the Member object: 
  75. * $member->has_membership( $membership_id ) 
  76. * $member->get_subscription( $membership_id ) 
  77. * @since 1.0.0 
  78. * @api 
  79. * @param int $user_id User_id 
  80. * @return MS_Model_Member|false The Member model. 
  81. */ 
  82. public function get_member( $user_id ) { 
  83. $user_id = absint( $user_id ); 
  84. $member = MS_Factory::load( 'MS_Model_Member', $user_id ); 
  85.  
  86. if ( ! $member->is_valid() ) { 
  87. $member = false; 
  88.  
  89. return $member; 
  90.  
  91. /** 
  92. * Returns the Member object of the current user. 
  93. * @since 1.0.0 
  94. * @api 
  95. * @return MS_Model_Member The Member model. 
  96. */ 
  97. public function get_current_member() { 
  98. $member = MS_Model_Member::get_current_member(); 
  99.  
  100. return $member; 
  101.  
  102. /** 
  103. * Returns a single membership object. 
  104. * Other plugins can store and accuess custom settings for each membership: 
  105. * // Create a custom value in the membership 
  106. * $membership->set_custom_data( 'the_key', 'the_value' ); 
  107. * $membership->save(); // Custom data is now saved to database. 
  108. * // Access and delete the custom value 
  109. * $value = $membership->get_custom_data( 'the_key' ); 
  110. * $membership->delete_custom_data( 'the_key' ); 
  111. * $membership->save(); // Custom data is now deleted from database. 
  112. * @since 1.0.0 
  113. * @api 
  114. * @param int|string $membership_id The membership-ID or name/slug. 
  115. * @return MS_Model_Membership The membership object. 
  116. */ 
  117. public function get_membership( $membership_id ) { 
  118. if ( ! is_numeric( $membership_id ) ) { 
  119. $membership_id = $this->get_membership_id( $membership_id ); 
  120.  
  121. $membership = MS_Factory::load( 'MS_Model_Membership', intval( $membership_id ) ); 
  122.  
  123. return $membership; 
  124.  
  125. /** 
  126. * Returns the membership-ID that matches the specified Membership name or 
  127. * slug. 
  128. * If multiple memberships have the same name then the one with the lowest 
  129. * ID (= the oldest) will be returned. 
  130. * Name or slug are case-IN-sensitive ('slug' and 'SLUG' are identical) 
  131. * Wildcards are not allowed, the string must match exactly. 
  132. * @since 1.0.1.2 
  133. * @param string $name_or_slug The Membership name or slug to search. 
  134. * @return int|false The membership ID or false. 
  135. */ 
  136. public function get_membership_id( $name_or_slug ) { 
  137. global $wpdb; 
  138. $res = false; 
  139.  
  140. $sql = " 
  141. SELECT ID 
  142. FROM {$wpdb->posts} p 
  143. INNER JOIN {$wpdb->postmeta} m ON m.post_id = p.ID AND m.meta_key = %s 
  144. WHERE 
  145. p.post_type = %s 
  146. AND ( m.meta_value = %s OR p.post_name = %s ) 
  147. ORDER BY ID 
  148. ;"; 
  149.  
  150. MS_Factory::select_blog(); 
  151. $sql = $wpdb->prepare( 
  152. $sql,  
  153. 'name',  
  154. MS_Model_Membership::get_post_type(),  
  155. $name_or_slug,  
  156. $name_or_slug 
  157. ); 
  158.  
  159. $ids = $wpdb->get_col( $sql ); 
  160. MS_Factory::revert_blog(); 
  161.  
  162. if ( is_array( $ids ) && count( $ids ) ) { 
  163. $res = reset( $ids ); 
  164.  
  165. return $res; 
  166.  
  167. /** 
  168. * Returns a single subscription object of the specified user. 
  169. * If the user did not subscribe to the given membership then false is 
  170. * returned. 
  171. * Each subscription also offers custom data fields 
  172. * (see the details in get_membership() for details) 
  173. * @since 1.0.0 
  174. * @api 
  175. * @param int $user_id The user ID. 
  176. * @param int|string $membership_id The membership-ID or name/slug. 
  177. * @return MS_Model_Relationship|false The subscription object. 
  178. */ 
  179. public function get_subscription( $user_id, $membership_id ) { 
  180. $subscription = false; 
  181.  
  182. $membership = $this->get_membership( $membership_id ); 
  183.  
  184. $member = MS_Factory::load( 'MS_Model_Member', $user_id ); 
  185. if ( $member && $member->has_membership( $membership->id ) ) { 
  186. $subscription = $member->get_subscription( $membership->id ); 
  187.  
  188. return $subscription; 
  189.  
  190. /** 
  191. * Add a new subscription for the specified user. 
  192. * If the membership is free the subscription instantly is ACTIVE. 
  193. * Otherwise the subscription is set to PENDING until the user makes the 
  194. * payment via the M2 checkout page. 
  195. * @since 1.0.1.2 
  196. * @param int $user_id The User-ID. 
  197. * @param int|string $membership_id The membership-ID or name/slug. 
  198. * @return MS_Model_Relationship|null The new subscription object. 
  199. */ 
  200. public function add_subscription( $user_id, $membership_id ) { 
  201. $subscription = null; 
  202. $membership = $this->get_membership( $membership_id ); 
  203.  
  204. $member = MS_Factory::load( 'MS_Model_Member', $user_id ); 
  205. if ( $member ) { 
  206. $subscription = $member->add_membership( $membership->id, '' ); 
  207.  
  208. // Activate free memberships instantly. 
  209. if ( $membership->is_free() ) { 
  210. $subscription->add_payment( 0, MS_Gateway_Free::ID, 'free' ); 
  211.  
  212. return $subscription; 
  213.  
  214. /** 
  215. * Returns a list of all available Memberships. 
  216. * @since 1.0.0 
  217. * @api 
  218. * @param bool $list_all If set to true then also private and internal 
  219. * Memberships (e.g. Guest Membership) are included. 
  220. * Default is false which returns only memberships that a guest user 
  221. * can subscribe to. 
  222. * @return MS_Model_Membership[] List of all available Memberships. 
  223. */ 
  224. public function list_memberships( $list_all = false ) { 
  225. $args = array( 
  226. 'include_base' => false,  
  227. 'include_guest' => true,  
  228. ); 
  229. $list = MS_Model_Membership::get_memberships( $args ); 
  230.  
  231. if ( ! $list_all ) { 
  232. foreach ( $list as $key => $item ) { 
  233. if ( ! $item->active ) { unset( $list[$key] ); } 
  234. elseif ( $item->private ) { unset( $list[$key] ); } 
  235.  
  236. return $list; 
  237.  
  238. /** 
  239. * Tries to determine the currently displayed membership. 
  240. * Detection logic: 
  241. * 1. If a valid preferred value was specified then this value is used. 
  242. * 2. Examine REQUEST data and look for membership/subscription/invoice. 
  243. * 3. Check currently logged in user and use the top-priority subscription. 
  244. * 4. If no membership could be detected the response value is bool FALSE. 
  245. * @since 1.0.1.0 
  246. * @return false|MS_Model_Membership The detected Membership or false. 
  247. */ 
  248. public function detect_membership() { 
  249. $result = false; 
  250.  
  251. $membership_id = apply_filters( 'ms_detect_membership_id', $membership_id ); 
  252. if ( $membership_id ) { 
  253. $result = MS_Factory::load( 'MS_Model_Membership', $membership_id ); 
  254.  
  255. return apply_filters( 'ms_detect_membership_result', $result, $membership_id ); 
  256.  
  257. /** 
  258. * Create your own payment gateway and hook it up with Membership 2 by using 
  259. * this function! 
  260. * Creating your own payment gateway requires good php skills. To get you 
  261. * started follow these steps: 
  262. * 1. Copy the folder "/app/gateway/manual" to the "wp-contents/plugins" 
  263. * folder, and name it "membership-mygateway" 
  264. * 2. Rename all files inside the "membership-mygateway" and replace the 
  265. * term "manual" with "mygateway" 
  266. * 3. Edit all files, rename the class names inside the files to 
  267. * "_Mygateway" (replacing "_Manual") 
  268. * 4. In class MS_Gateway_Mygateway make following changes: 
  269. * - Set the value of const ID to "mygateway" 
  270. * - Change the assigned name in function "after_load" 
  271. * - Add a plugin header to the file, e.g. 
  272. * /** 
  273. * * Plugin name: Membership 2 Mygateway 
  274. * * / 
  275. * - Add the following line to the bottom of the file: 
  276. * add_action( 'ms_init', 'mygateway_register' ); 
  277. * function mygateway_register( $api ) { 
  278. * $api->register_payment_gateway( 
  279. * MS_Gateway_Mygateway::ID,  
  280. * 'MS_Gateway_Mygateway' 
  281. * ) 
  282. * } 
  283. * Now you have created a new plugin that registers a custom payment gateway 
  284. * for Membership 2! Implementing the payment logic is up to you - you can 
  285. * get a lot of insight by reviewing the existing payment gateways. 
  286. * @since 1.0.1.0 
  287. * @api 
  288. * @param string $id The ID of the new gateway. 
  289. * @param string $class The Class-name of the new gateway. 
  290. */ 
  291. public function register_payment_gateway( $id, $class ) { 
  292. $this->gateways[$id] = $class; 
  293. $this->add_action( 'ms_model_gateway_register', '_register_gateways' ); 
  294.  
  295. /** 
  296. * Internal filter callback function that registers custom payment gateways. 
  297. * @since 1.0.1.0 
  298. * @internal 
  299. * @param array $gateways List of payment gateways. 
  300. * @return array New list of payment gateways. 
  301. */ 
  302. public function _register_gateways( $gateways ) { 
  303. foreach ( $this->gateways as $id => $class ) { 
  304. $gateways[$id] = $class; 
  305.  
  306. return $gateways; 
  307.  
  308. /** 
  309. * Membership2 has a nice integrated debugging feature. This feature can be 
  310. * helpful for other developers so this API offers a simple way to access 
  311. * the debugging feature. 
  312. * Also note that all membership objects come with the built-in debug 
  313. * function `$obj->dump()` to quickly analyze the object. 
  314. * // Example of $obj->dump() usage 
  315. * $user = MS_Plugin::$api->current_member(); 
  316. * $user->dump(); 
  317. * @since 1.0.0 
  318. * @api 
  319. * @param mixed $data The value to dump to the output stream. 
  320. */ 
  321. public function debug( $data ) { 
  322. lib3()->debug->enable(); 
  323. // Intended debug output, leave it here. 
  324. lib3()->debug->dump( $data ); 
  325.