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. You could also define your own PHP functions here and they'll be visible to all your AppGini application pages.

The following hook functions are defined in this file:

• child_records_config()
• login_ok()
• login_failed()
• member_activity()
• sendmail_handler()

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 member 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
	file_put_contents($logFile, "$date,$time,$username,$ip\n", FILE_APPEND);

	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 = '[email protected]';

	// 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;

		case 'profile':
			break;

		case 'password':
			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.
  • 'profile': Means the member made changes to his profile.
  • 'password': Means the member changed his password.
• $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: [email protected]" // 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: [email protected]" // the "From" address the user will see
			);
			break;

		case 'profile':
			break;

		case 'password':
			break;

	}
}

This hook function was added in AppGini 5.62, and is called whenever an email is sent using the sendmail() AppGini function. If you open the generated hooks/__global.php file in a text editor, you can see this function defined as follows:

function sendmail_handler(&$pm){

}

Parameters:

• $pm is a PHPMailer object, passed by reference. Please refer to PHPMailer project on Github for more details.

Return value:
None.

This hook function was added in AppGini 22.14, and can be used to modify the default configuration of the child records section in the detail view.

If you open the generated hooks/__global.php file in a text editor, you can see this function defined as follows:

function child_records_config($childTable, $childLookupField, &$config) {

}

Parameters:

• $childTable The current child table name.
• $childLookupField The name of the lookup field in the child table that is linked to the parent table
• $config The configuration array for displaying child records for the current user, passed by reference. The default configuration, is stored in the $pcConfig array defined in the generated parent-children.php file.

Return value:
None.