Global hooks

Global hook functions are defined in the generated hooks/__global.php file. This file contains hook functions that get called when a new member signs up, when a member signs in successfully and when a member fails to sign in.

The following hook functions are defined in this file:

• login_ok()
• login_failed()
• member_activity()

This hook function is called when a member successfully signs in. It can be used for example to redirect members to specific pages rather than the home page, or to save a log of members' activity, … etc. If you open the generated hooks/__global.php file in a text editor, you can see this function defined as follows:

function login_ok($memberInfo, &$args){

	return '';
}

Parameters:

• $memberInfo is an array containing details of the member who signed in. Please refer to memberInfo for more details.
• $args is currently not used but is reserved for future uses.

Return value:
A string containing the URL to redirect the member to. It can be a relative or absolute URL. If the return string is empty, the member is redirected to the homepage (index.php), which is the default behavior.


Example:
Let's add code to save a log of members' login activity. Each time a memeber signs in, we'll record his username, IP address, login date and time into a log file. Here's how the hook function looks like after adding this code:

function login_ok($memberInfo, &$args){
	// the log file where we'll save member activity
	$logFile='members.log';

	// the member details we'll be saving into the file
	$username=$memberInfo['username'];
	$ip=$memberInfo['IP'];
	$date=date('m/d/Y');
	$time=date('h:i:s a');

	// open the log file and append member login details
	if(!$fp=@fopen($logFile, 'a')) return '';
	fwrite($fp, "$date,$time,$username,$ip\n");
	fclose($fp);

	return '';
}

This hook function is called when a login attempt fails. It can be used for example to log login errors. If you open the generated hooks/__global.php file in a text editor, you can see this function defined as follows:

function login_failed($attempt, &$args){

}

Parameters:

• $attempt is an associative array containing details of the failed login attempt, as follows:
  • $attempt['username']: the username used during the failed login attempt.
  • $attempt['password']: the password used during the failed login attempt.
  • $attempt['IP']: the IP of the user who tried to log in.
• $args is currently not used but is reserved for future uses.

Return value:
None.


Example:
To notify the admin when a user fails to log in, we can add this code into the login_failed() hook function:

function login_failed($attempt, &$args){
	// email of admin
	$adminEmail='admin@domain.com';

	// someone trying to log as admin?
	if($attempt['username']=='admin'){

		// send the email
		@mail(
			$adminEmail, // email recipient
			"Failed login attempt", // email subject
			"Someone from {$attempt['IP']} tried to log in ".
			"as admin using the password {$attempt['password']}.", // message
			"From: $adminEmail"
		);
	}
}

This hook function is called when a new member signs up. If you open the generated hooks/__global.php file in a text editor, you can see this function defined as follows:

function member_activity($memberInfo, $activity, &$args){
	switch($activity){
		case 'pending':
			break;

		case 'automatic':
			break;

	}
}

Parameters:

• $memberInfo is an array containing details of the member who signed in. Please refer to memberInfo for more details.
• $activity A string that contains one of the following values:
  • 'pending': Means the member signed up through the signup form and awaits admin approval.
  • 'automatic': Means the member signed up through the signup form and was approved automatically.
• $args is currently not used but is reserved for future uses.

Return value:
None.


Example:
This example sends a welcome email to new users who were automatically approved, and a 'please wait' email for new users pending approval.

function member_activity($memberInfo, $activity, &$args){
	switch($activity){
		case 'pending':
			// send 'please wait' email to new user
			@mail(
				$memberInfo['email'], // email recipient
				"Thank you for signing up at our website!", // subject
				
				"Dear {$memberInfo['username']}, \n\n".
				"We'll review and approve your new account within a few hours.\n\n".
				"Thank you.", // message

				"From: support@domain.com" // the "From" address the user will see
			);
			break;

		case 'automatic':
			// send 'welcome' email to new user
			@mail(
				$memberInfo['email'], // email recipient
				"Thank you for signing up at our website!", // subject
				
				"Dear {$memberInfo['username']}, \n\n".
				"You can now log into our website from this page:\n".
				"http://www.domain.com/appgini\n\n".
				"Thank you.", // message

				"From: support@domain.com" // the "From" address the user will see
			);
			break;

	}
}