Plugin/Events/User

From Joomla! Documentation

< Plugin‎ | Events
Revision as of 19:16, 30 June 2018 by Dextercowley (talk | contribs)
Other languages:
English • ‎Nederlands • ‎español • ‎français

In a standard installation of Joomla! we have several predefined User events which, when triggered, call functions in the associated plugins.

onUserAuthorisation[edit]

Description[edit]

This event authorises that a particular user should be able to login. The system triggers this event after the user has been authenticated and before he has been signed in the website. It is possible to be triggered by plugin types User and Authentication.

Parameters[edit]

  • $user - an object JAuthenticationResponse
  • $options - an associative array containing these keys: ["remember"] => bool, ["return"] => string, ["entry_url"] => string, ["action"] => string

Return Value[edit]

JAuthenticationResponse or NULL (NULL if you would like to miss the authorisation)

Used in files[edit]

  • libraries/joomla/user/authentication.php

Example[edit]

onUserAuthorisationFailure[edit]

Description[edit]

The system triggers this event when the user has been authenticated but he has not been authorised to login. You should only use this event in User plugins.

Parameters[edit]

Return Value[edit]

void (it does not return any value or object)

Used in files[edit]

  • libraries/cms/application/cms.php

onUserLogin[edit]

Description[edit]

This event is triggered after the user is authenticated against the Joomla! user-base.

If you need to abort the login process (authentication), you will need to use onUserAuthenticate instead.

Parameters[edit]

  • $user - an associative array of JAuthenticationResponse type (see link for array keys)
  • $options - an associative array containing these keys: ["remember"] => bool, ["return"] => string, ["entry_url"] => string

Return Value[edit]

Boolean

Used in files[edit]

  • libraries/joomla/application/application.php
  • plugins/user/joomla.php

Example[edit]

  • plugins/user/example.php

onUserLogout[edit]

Description[edit]

This event is triggered before the user is logged out of the system.

If any plugin returns false, the global logout fails and the onUserLogoutFailure event is fired; if it succeeds, onUserAfterLogout event is triggered instead.

NOTE: as of 3.3.6, returning false does not work correctly, because stock components perform their logout operation during the onUserLogout event. So even if your plugin returns false, the stock ones have already run anyway. Thus, the user will be "mostly" logged out even if you return false. There is no actual way to cleanly abort logout.

Parameters[edit]

  • $credentials - an associative array containing these keys: ["username"] => string, ["id"] => int
  • $options - an associative array containing this key: ["clientid"] => int

Return Value[edit]

Boolean

Used in files[edit]

  • libraries/cms/application/cms.php
  • plugins/user/joomla/joomla.php
  • plugins/system/logout.php
  • plugins/system/remember/remember.php

Example[edit]

  • plugins/user/example.php

onUserLoginFailure[edit]

Description[edit]

This event is triggered whenever a user authentication request is failed by any plugin.

Parameters[edit]

Two parameters. The credentials array for the user (see onAuthenticate), and the JAuthenticationResponse that caused the failure.

Return Value[edit]

Unknown. The return value appears to be ignored in any case.

Used in file[edit]

  • libraries/joomla/application/user/authentication.php

onUserAfterLogin[edit]

Description[edit]

This event is triggered whenever a user is successfully logged in.

Parameters[edit]

Options is array with:

  • remember
  • return
  • entry_url
  • action
  • user - JUser Object
  • responseType

Return Value[edit]

Boolean

Used in files[edit]

  • libraries/legacy/application/application.php
  • libraries/cms/application/cms.php
  • plugins/authentication/cookie/cookie.php

onUserBeforeSave[edit]

Description[edit]

This event is triggered before an update of a user record.

The old and new user parameters are provided; commonly-used members are: username, name, email, password, password_clear.

The password array entry is the hashed password value. If the user has just changed the password, you may retrieve the cleartext password from $newUser['password_clear']. (It will be set to "" if the password has not been changed.)

Parameters[edit]

  • $oldUser - An associative array of the columns in the user table (current values).
  • $isnew - Boolean to identify if this is a new user (true - insert) or an existing one (false - update)
  • $newUser - An associative array of the columns in the user table (new values).

Return Value[edit]

Boolean. Whether the user-save should proceed or not. Any plugin that returns false aborts the save.

Used in file[edit]

  • libraries/joomla/user/user.php

Example[edit]

  • plugins/user/example.php

onUserAfterSave[edit]

Description[edit]

This event is triggered after an update of a user record, or when a new user has been stored in the database.

Password in $user array is already hashed at this point. You may retrieve the cleartext password using $_POST['password'].

Parameters[edit]

  • $user - An associative array of the columns in the user table.
  • $isnew - Boolean to identify if this is a new user (true - insert) or an existing one (false - update)
  • $success - Boolean to identify if the store was successful
  • $msg - Error message if store failed

Note: The old values that were just updated are not available here or afterwards. In case you need the old values, use onBeforeStoreUser().

Return Value[edit]

None

Used in file[edit]

  • libraries/joomla/user/user.php

Example[edit]

  • plugins/user/example.php

onUserBeforeDelete[edit]

Description[edit]

The event is triggered when a user is about to be deleted from the system.

Parameters[edit]

  • $user - An associative array of the columns in the user table.

Return Value[edit]

None. If you want to prevent the user from being deleted, you may abort the delete by redirecting back to the User Manager. For example:

		if ($this->deleteNotAllowed($data))
		{
			$url = JRoute::_('index.php?option=com_users&view=users', false);
			$msg = JText::sprintf('PLG_USER_DELETE_NOT_ALLOWED', $data['username']);
			$app = Factory::getApplication();
			$app->enqueueMessage($msg, 'error');
			$app->redirect($url);
		}

Used in files[edit]

  • libraries/joomla/user/user.php
  • plugins/user/joomla.php

Example[edit]

  • plugins/user/example.php

onUserAfterDelete[edit]

Description[edit]

The event is triggered after a user has been deleted from the system.

Parameters[edit]

  • $user - An associative array of the columns in the user table.
  • $succes - Boolean to identify if the deletion was successful
  • $msg - Error message if delete failed (JError object detailing the error, if any)

Return Value[edit]

None.

Used in files[edit]

  • libraries/joomla/user/user.php
  • plugins/user/joomla.php

Example[edit]

  • plugins/user/example.php

Order of execution[edit]

To modify Joomla! login process upon your needs (e.g. creating AJAX output for login), it may be useful to know the order of the events to be fired.

Wrong credentials CORRECT CREDENTIALS and the user is not blocked (is activated) CORRECT CREDENTIALS and the user is blocked (is not activated)
onUserAuthenticate
returns
TRUE or FALSE
	 |
	 |
	\ /
onUserLoginFailure
onUserAuthenticate
returns
TRUE or FALSE
	 |
	 |
	\ /
onUserLogin	returns FALSE -> END
returns TRUE
	 |
	 |
	\ /
onUserAfterLogin
onUserAuthenticate
returns
TRUE or FALSE
	 |
	 |
	\ /
onUserLogin
returns
TRUE or FALSE
	 |
	 |
	\ /
	END

Example idea Let's assume you want to preform Ajax login. You have already overriden a mod_login form so it's posted to Joomla! via an AJAX call. You added a field named ajax to the form. So when the form is posted and authentication is failed, your custom plugin must return some JSON data.

public function onUserLoginFailure($response)
{
	$input  = JFactory::getApplication()->input;

	// If a non-ajax form was posted, we do not modify the behavior
	if (!$input->post->get('ajax', false))
	{
		return;
	}

	$app = JFactory::getApplication();
	$task_failed = false; 

	// Fill this array with the data you want to return, e.g. $response['status'] may be useful
	// Check libraries/joomla/user/authentication.php for available status codes 
	$data = array('status' => $response['status']);
        
        // At least here in the plugin it's a must to send proper headers
        JFactory::getApplication()->setHeader('Content-Type', 'application/json', true)->sendHeaders();
	echo new JResponseJson($data, $response['error_message'], $task_failed);

	// Closing app is a must here to return JSON immideately
	$app->close();
}