Development

High Level Overview

The Social Connect plugin does most of the work for you. But it still allows Elgg developers to interact with the authentication and registration processes so that customization is possible and easy. First of all we will look at a simple diagram to explain how the plugin interacts with the other elements involved in user access.

Following is a detailed explanation of how user access into Elgg unfolds when you have installed the Social Connect plugin

1. The end-user selects one of the available providers from the list of enabled ones (you can configure these in the Social Connect settings). This can happen on either the login page/dropbox or the registration page. The Social Connect plugin takes over and will deal with the request.
2. The Social Connect plugin contacts the provider selected by the end-user in a pop-up window. The user will have to authenticate with the provider (unless they have selected to store credentials on the browser) and if it is the first time that Social Connect is requesting access for that user, they will also have to agree to give Social Connect access to their profile. This authorization request will only be necessary once. Subsequent requests to login with the provider will automatically be authorized.
3. If authentication with the provider succeeds and the user authorizes Social Connect to access their profile, profile information is returned to the plugin. If anything fails along the way or the user denies access, the plugin will receive the error from the provider and notify the user, ending the process. Otherwise, the plugin looks at the user profile to determine whether it had already connected that profile with an Elgg user. If so, it simply logs the user in, if not it will create a new profile or update an existing one, before logging the user in. More detail on what happens at this level is provided in the next section.
4. At this point the plugin is ready to respond to Elgg. The outcome of the processing will be
   
   1. either the registration of a new user,
   2. or the connection of an existing user to the profile supplied by the provider,
   3. or the login of an existing user that had already used the plugin before.

In any case, the pop-up window is closed and the Elgg page reloaded.

Internals

When a user decides to login or register with the Social Connect plugin, the authenticate.php page is executed in a pop-up window and in the following diagram you can see a visual representation of what goes on inside that page. This diagram is basically a zoom into the "social connect" box from the high level overview picture seen above. The points at which developers can intervene by registering for the Social Connect hook and/or event are represented in solid blue colour.

This image can feel quite crowded, so here's a step-by-step description of what happens in it.

1. The authenticate.php script is invoked in a pop-up window. It checks that the provider requested is enabled and that the required configuration parameters are all there.
2. Depending on the outcome of the previous checks, two paths are possible:
   
   1. (2A) If the set up of the provider was ok, we proceed to the step 3.
   2. (2B) If there are any problems, an error message is displayed and execution terminates here. If debug mode is enabled, a form allows users to send feedback to HybridAuth.
3. The actual provider is invoked, with a request to authenticate the user and return their profile.
4. The provider responds.
5. Depending on the response from the provider, two paths are possible:
   
   1. (5A) If the provider successfully returned a user profile, we move on to step 6.
   2. (5B) If the provider returned an error, the error is displayed and execution terminates here. If debug mode is enabled, a form allows users to send feedback to HybridAuth.
6. The Social Connect plugin verifies whether a setting already exists in the Elgg database for the current profile.
7. Depending on whether a user setting exists for this provider or not, two paths are possible:
   
   1. (7A) If the setting exists, the user has already logged in with this provider before and the corresponding Elgg user is retrieved, The 'social_connect','user' hook is then invoked with a mode of 'login' to allow developers to do something with the detected Elgg user and connected profile. Depending on the response from the hook, we may move on to either 8A1 or 8AX.
   2. (7B) If the setting does not exist, this is the first time this provider has been connected by this user. The 'social_connect','user' hook is then invoked with a mode of 'connect' to allow developers to do something with the connected profile. The Elgg user variable is set to null. Depending on the response from the hook, we may move on to either 8B1, 8B2, 8B3, or 8BX.
8. The response from the hook call in step 7 and the mode of the plugin determine what happens next:
   
   1. if the mode is 'login':
      
      1. (8A1) if the hook returns true, the plugin logins the detected user, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.
      2. (8AX) if the hook returns false, developers do not want login to continue or have handled login themselves. The popup is closed and the Elgg page is refreshed, but the plugin takes no further actions. Plugin execution terminates here.
   2. if the mode is 'connect':
      
      1. (8B1) if the hook returns true, the plugin registers a new user for this profile. The 'social_connect','user' event is then triggered with a mode of 'register' to notify developers of the newly created Elgg user from the connected profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.
      2. (8B2) if the hook returns 'email', the plugin proceeds to verify the presence of an email address in the connected profile and can proceed to either 9A1 or 9A2 depending on whether an email address was found or not.
      3. (8B3) if the hook returns 'emailOnly', the plugin proceeds to verify the presence of an email address in the connected profile and can proceed to either 9B1 or 9BX depending on whether an email address was found or not.
      4. (8BX) if the hook returns false, developers do not want social connection to continue or have handled the connection themselves. The popup is closed and the Elgg page is refreshed, but the plugin takes no further actions. Plugin execution terminates here.
9. The mode of the plugin at this stage is 'connect'. Depending on the response from the hook and whether an email address was present in the connected profile, the following paths are possible:
   
   1. the hook returned 'email':
      
      1. (9A1) if the profile does not offer an email address or the offered email address did not correspond to any of the existing Elgg users, the plugin registers a new user for this profile. The 'social_connect','user' event is then triggered with a mode of 'register' to notify developers of the newly created Elgg user from the connected profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.
      2. (9A2) if the profile offers an email address which corresponds to one of the existing Elgg users, the plugin simply connects the existing user to the connected profile, without any new registrations. The 'social_connect','user' event is then triggered with a mode of 'email' to notify developers of the newly created connection between an Elgg user and the provider's profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.
   2. the hook returned 'emailOnly':
      
      1. (9B1) if the profile offers an email address which corresponds to one of the existing Elgg users, the plugin simply connects the existing user to the connected profile, without any new registrations. The 'social_connect','user' event is then triggered with a mode of 'email' to notify developers of the newly created connection between an Elgg user and the provider's profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.
      2. (9BX) if the profile does not offer an email address or the offered email address did not correspond to any of the existing Elgg users, the plugin fails with an error message. The popup is closed and the main Elgg page is refreshed. Plugin execution terminates here. This is useful if you do not want new registrations to come from the Social Connect plugin, but are happy to allow existing users to connect via other social networks once registered.

Developing with Social Connect

If you are a developer who would like to interact with the functionality of the Social Connect plugin, you can develop your own Elgg plugin and register for the Social Connect hook and/or event like this

// register a handler for the social_connect event
elgg_register_event_handler('social_connect', 'user', 'yourplugin_social_connect_event');
// register a handler for the social_connect hook
elgg_register_plugin_hook_handler('social_connect', 'user', 'yourplugin_social_connect_hook');

Both the hook and the event receive an associate array from the Social Connect plugin with the following structure

// the arguments for social connect events and hooks
$args = array(
	'mode' => null,
	'userid' => $user_uid,
	'provider' => $provider,
	'user' => null,
	'profile' => $user_profile,
);

The value of $args['userid'] is set to the unique identifier of the current profile in the provider directory.

The $args['profile'] value instead is the HybridAuth object representing the complete provider profile for the user. The amount of information available in the profile depends on the provider and is detailed in the HydridAuth documentation.

The key $args['provider'] finally contains the configuration array for the current provider the user is connecting with.

The above keys are always set in both hook and event invocations. The other values are populated into this structure according to the explanations below.

The Social Connect hook

The hook is invoked when the provider has successfully returned a user profile and after the plugin has verified whether that profile has already been connected to Elgg.

The signature of the callback method is as follows

function yourplugin_social_connect_hook($event, $object_type, $proceed, $args) { }

The $args variable contains the data of the structure described above. The $proceed variable is initially set to true.

• If the profile has already been connected to an existing Elgg user, the $args['mode'] value is set to 'login' and $args['user'] is set to the associated ElggUser instance.
• If this profile has never been used in Elgg before, instead, the $args['mode'] value is set to 'connect' and $args['user'] is null.

The method should return a boolean value. The $proceed value is set to true initially, but you can decide to return false if you have handled the rest of the process yourself in this method or if you need to return an error for whatever reason.

• If the hook handler returned true, the plugin continues with the social connection process.
• If the hook handler returned false, the plugin closes the popup window, refreshes the underlying Elgg page and terminates execution.

When in 'connect' mode, the handler can also return 'email' or 'emailOnly' instead of a boolean value. With either string, the plugin will check whether the profile has an email address instead of proceeding immediately with the registration of a new user. If an email address is provided and the email address is already registered with Elgg, then the plugin will associate the new provider profile with the existing Elgg user (the mode of the plugin switches to 'email'). If an email address was not found or the retrieved email address does not exist in Elgg, then the outcome depends on the string.

• If the hook handler returned 'email', the plugin will proceed to register a new user as normal.
• If the hook handler returned 'emailOnly', the plugin will terminate with an error (and close the popup window and refresh the Elgg page...)

When it registers a new user, the plugin changes its mode to 'register', whether it's because the hook handler returned true or because no registered email address matched the current profile.

The Social Connect event

The event handler is invoked only when the hook was in 'connect' mode.

The signature of the callback method is as follows

function yourplugin_social_connect_event($event, $object_type, $args) { }

The event is triggered after the hook has returned a non-false value in 'connect' mode. It tells the developer what happened in the connection process.

The mode in the $args parameter can be one of the following

• 'register': a new Elgg user has been registered into the system. The new user is available in the $args['user'] variable.
• 'email': an existing Elgg user has been connected to the current profile because they have the same email address. The associated user is available in the $args['user'] variable.

You can use this event to populate the Elgg user object with more information from the provider profile or any other source. The plugin itself will only populate the following fields out of the box

• username
• name
• email
• password (auto generated)
• avatar