Creating New Integration Plugins

From AMember Pro Manual

Jump to: navigation, search

This chapter requies serious PHP programming expirience. We recommend you to contact support@cgi-central.net for suggestion, if you not sure that you have such knowledge.

Contents

[edit] What is the integration plugin?

Integration plugin is an add-on for aMember which allows you to maintain third-party members database or solve other tasks. It consists from several PHP files. This guide will show you how to create such a plugin and test it.

You will need text editor and FTP client to create a plugin.

[edit] Creating plugin template

  1. Copy folder amember/plugins/protect/plugin_template/ to some other folder, lets say some_your_plugin_name;
  2. Rename plugin_template.inc.php to some_your_plugin_name.inc.php;
  3. In the plugin files, replace all occurrences of plugin_template to some_your_plugin_name (of course, without quotes).
  4. Now please open some_your_plugin_name.inc.php with your favorite text editor and lets write some code.

[edit] Understanding user record

First, let us explain: member record is an array, usually we name it $member in the code. It contains the following fields, for example:

  • $member['login']
  • $member['pass']
  • $member['name_f']
  • $member['name_l']
  • $member['email']

Also, there is a special "field" named data ($member['data']). It contains all additional fields (fields which you've added with using of add_member_field() function. So, if you added field phone, there will be defined a varaible $member['data']['phone'] .

[edit] What is user status?

aMember always holds and maintains user status in several fields. Because member can have several subscriptions for different products in the same time, we maintain 2 status fields:

[edit] $member['data']['status']

This field is an associative array. Keys are product IDs, and values are status value for this product.

  • 0 means that subscription for this product is not active (never paid, or expired).
  • 1 means that subscription is active (paid and not-expired). This field should be used for most calculations in plugins.

[edit] $member['status']

This field is mostly for usage in aMember code, but you can use it as well. It is status of entire member record and it can have the following values:

  • 0 - never paid (user never had completed subscriptions);
  • 1 - paid and active (user have at least one completed and active subscription);
  • 2 - expired (all user subscriptions have been expired).

[edit] How to setup a plugin hook

A plugin hook can be set with this line of code: 

setup_plugin_hook('subscription_added',   'plugin_template_added');

It means that for every new product subscription_added, aMember will run function plugin_template_added. There can be several hooks called for the same event.

[edit] Plugin hooks - member status

These hooks called when changes made to aMember database and you need to update your third-party members database.

[edit] subscription_added($member_id, $product_id, $member)

This hook will be called when user subscription status $member['data']['status'] changed to active (1) for product with ID = $product_id. In this case, you have to add (or update) member record in your database, or execute some other actions regarding this event. Please note - because user may have subscriptions for several products, your database may already hold this customer record. Then you should update it with new password, for example and you should unlock customer record if necessary. It is important to understand this hook is not necessary called for every payment. It is called only when user status for product changes. So, when user already have active subscription for product, and he orders this product again, this hook will not be called. If you need to call a function for every member payment, have a look to "finish_waiting_payment" plugin hook.

[edit] subscription_updated($member_id, $oldmember,$newmember)

This hook will be called when user (or admin) updates profile. You should update customer profile in your database accordingly, if such profile exists in your database. New info will be stored in $newmember variable, and old info will be in $oldmember variable. $oldmember will help you to find existing user record in your database. Don't forget - login can be changed too!

Also, if you need to use member status fields in this function, use it from $oldmember variable - these fields are empty in newmember variable.

[edit] subscription_deleted($member_id, $product_id, $member)

This function will be called when user subscriptions status for $product_id becomes NOT-ACTIVE. It may happen if user payment expired, marked as "not-paid" or deleted by admin. This function is an opposite for subscription_added. Be careful here - user may have active subscriptions for another products and he may be should still in your database - check $member['data']['status'] variable to be sure that user has no other subscriptions allowing his to access your application.

[edit] subscription_removed($member_id, $member)

This function will be called when admin (or aMember) completely deletes member profile from aMember database with all related payments and other info. Your plugin should delete user profile from database (if your application allows it!), or it should just disable member access to your application if application doesn't allow profiles deletion.

[edit] subscription_rebuild(&$members)

This function will be called when admin clicks on aMember CP -> Rebuild Db link. This function allows admin to ensure that third-party members databases are synchronised with aMember members Db. aMember sends a short list of members. Each key is a member login, each record is an assotiative array with the following fields: 

array(
         'pass' => 'MEMBER PASSWORD',
         'product_id' => array('LIST','OF',
         'ID OF PRODUCTS','WHICH MEMBER IS SUBSCRIBED FOR')
      )

[edit] Plugin hooks - signup helpers

[edit] subscription_check_uniq_login($login, $email, $pass)

This hooks allows you to check if user is exists in third-party database before he can signup using http://www.yoursite.com/amember/signup.php form. By default, aMember plugins do the following checks :

  • if user with the same username , email and password is exists, allow signup
  • if username is the same, but email or password is different - don't allow signup

For example, it won't allow "hackers" to get access to existing, but not-paid forum account. Function should return 1 if user is allowed to signup, and 0 if user is not allowed to signup.

[edit] fill_in_signup_form(&$vars)

This hook is rarely used, hovewer it offers you great ability to pre-fill signup form in amember with info received from third-party database, if user is logged-in in third-party application. For example, if user is logged-in in Invision Board, this function may automatically fill-in username and email fields in aMember signup form. To do it, you have to determine if user is logged-in in third-party application, get user info from third-party database and save this info to $vars array.

Retrieved from "http://manual.amember.com/Creating_New_Integration_Plugins"
Personal tools