Actions

J1.5

Difference between revisions of "Plugin/Events/User"

From Joomla! Documentation

< J1.5:Plugin/Events
(5.3.9.2 Parameters)
(Grammar)
(13 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[Category:Development]]
+
{{RightTOC}}
[[Category:Plugins]]
+
==5.3 User Events for Plugin System==
+
  
===5.3.1 Overview===
+
{{Warning|This page is under migration to Joomla 2.5 new plugin trigger methods}}
In a standard installation of Joomla! 1.5 we have several predefined events which, when triggered, call functions in the associated plugins. For more information on plugins,
+
 
look [[plugins:create_plugin|here]].
+
In a standard installation of Joomla! 2.5 we have several predefined events which, when triggered, call functions in the associated plugins.
  
 
The user events are divided into two parts. First we have the events used while  
 
The user events are divided into two parts. First we have the events used while  
 
authentication of a user takes place:
 
authentication of a user takes place:
  *onLoginUser
+
*onUserLogin (on Joomla 1.5: onLoginUser)
  *onLogoutUser
+
*onUserLogout (on Joomla 1.5: onLogoutUser)
  *onAuthenticate
+
*onUserAuthenticate (on Joomla 1.5: onAuthenticate)
  *onAuthenticateFailure
+
*onUserAuthorisationFailure (on Joomla 1.5: onAuthenticateFailure)
 
    
 
    
 
Second we have the events triggered during user management:
 
Second we have the events triggered during user management:
  *onBeforeStoreUser
+
*onUserBeforeSave (on Joomla 1.5: onBeforeStoreUser)
  *onAfterStoreUser
+
*onUserAfterSave (on Joomla 1.5: onAfterStoreUser)
  *onBeforeDeleteUser
+
*onUserBeforeDelete (on Joomla 1.5: onBeforeDeleteUser)
  *onAfterDeleteUser
+
*onUserAfterDelete (on Joomla 1.5: onAfterDeleteUser)
 
+
  
===5.3.2 onLoginUser===
+
==onUserLogin==
====5.3.2.1 Description====
+
===Description===
 
This event is triggered after the user is authenticated against the Joomla! user-base.
 
This event is triggered after the user is authenticated against the Joomla! user-base.
<del>If one plugin returns false, the entire authentication process fails.</del> (needs verification)
 
  
====5.3.2.2 Parameters====
+
If you need to abort the login process (authentication), you will need to use [http://docs.joomla.org/Reference:User_Events_for_Plugin_System#5.3.4_onAuthenticate onAuthenticate] instead.
  * $user - an associative array of [http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html JAuthenticateResponse] type (see link for array keys)
+
  * $options - an associative array containing these keys: ["remember"] => bool, ["return"] => string, ["entry_url"] => string
+
  
====5.3.2.3 Return Value====
+
===Parameters===
Boolean
+
* $user - an associative array of [http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html JAuthenticateResponse] type (see link for array keys)
====5.3.2.4 Used in files====
+
* $options - an associative array containing these keys: ["remember"] => bool, ["return"] => string, ["entry_url"] => string
  *libraries/joomla/application/application.php
+
  *plugins/user/joomla.php
+
====5.3.2.5 Examples====
+
  *plugins/user/example.php
+
  
 +
===Return Value===
 +
Boolean
 +
===Used in files===
 +
*<tt>libraries/joomla/application/application.php</tt>
 +
*<tt>plugins/user/joomla.php</tt>
 +
===Examples===
 +
*<tt>plugins/user/example.php</tt>
  
===5.3.3 onLogoutUser===
+
==onUserLogout==
====5.3.3.1 Description====
+
===Description===
 
This event is triggered before the user is logged out of the system. <del>If one plugin
 
This event is triggered before the user is logged out of the system. <del>If one plugin
 
returns false, the global logout fails.</del> (needs verification)
 
returns false, the global logout fails.</del> (needs verification)
  
====5.3.3.2 Parameters====
+
===Parameters===
  * $credentials - an associative array containing these keys: ["username"] => string, ["id"] => int
+
* $credentials - an associative array containing these keys: ["username"] => string, ["id"] => int
  * $options - an associative array containing this key: ["clientid"] => int
+
* $options - an associative array containing this key: ["clientid"] => int
  
====5.3.3.3 Return Value====
+
===Return Value===
 
Boolean
 
Boolean
====5.3.3.4 Used in files====
+
===Used in files===
  *libraries/joomla/application/application.php
+
*<tt>libraries/joomla/application/application.php</tt>
  *plugins/user/joomla.php
+
*<tt>plugins/user/joomla.php</tt>
====5.3.3.5 Examples====
+
===Examples===
  *plugins/user/example.php
+
*<tt>plugins/user/example.php</tt>
  
 
+
==onUserAuthenticate==
===5.3.4 onAuthenticate===
+
===Description===
====5.3.4.1 Description====
+
 
This event is triggered to verify that a set of login credentials is valid.
 
This event is triggered to verify that a set of login credentials is valid.
====5.3.4.2 Parameters====
+
===Parameters===
 
Array of credentials. Structure:\\
 
Array of credentials. Structure:\\
 
['username']\\
 
['username']\\
Line 66: Line 62:
 
Alternative authentication mechanisms can supply additional credentials.
 
Alternative authentication mechanisms can supply additional credentials.
  
====5.3.4.3 Return Value====
+
===Return Value===
 
An array of [[references:joomla.framework:user:jauthenticateresponse|JAuthenticateResponse]] objects detailing the results of each called plugin, including success or failure.
 
An array of [[references:joomla.framework:user:jauthenticateresponse|JAuthenticateResponse]] objects detailing the results of each called plugin, including success or failure.
====5.3.4.4 Used in files====
+
===Used in files===
  *libraries/joomla/application/user/authentication.php
+
*<tt>libraries/joomla/application/user/authentication.php</tt>
  *plugins/authentication/gmail.php
+
*<tt>plugins/authentication/gmail.php</tt>
  *plugins/authentication/joomla.php
+
*<tt>plugins/authentication/joomla.php</tt>
  *plugins/authentication/ldap.php
+
*<tt>plugins/authentication/ldap.php</tt>
====5.3.4.5 Examples====
+
===Examples===
  *plugins/authentication/example.php
+
*<tt>plugins/authentication/example.php</tt>
  
 
+
==onUserLoginFailure==
===5.3.5 onLoginFailure===
+
===Description===
====5.3.5.1 Description====
+
 
This event is triggered whenever a user authentication request is failed by any plugin.
 
This event is triggered whenever a user authentication request is failed by any plugin.
====5.3.5.2 Parameters====
+
===Parameters===
 
Two parameters. The credentials array for the user (see onAuthenticate), and the
 
Two parameters. The credentials array for the user (see onAuthenticate), and the
 
[[references:joomla.framework:user:jauthenticateresponse|JAuthenticateResponse]] that caused the failure.
 
[[references:joomla.framework:user:jauthenticateresponse|JAuthenticateResponse]] that caused the failure.
====5.3.5.3 Return Value====
+
===Return Value===
 
Unknown. The return value appears to be ignored in any case.
 
Unknown. The return value appears to be ignored in any case.
====5.3.5.4 Used in files====
+
===Used in files===
  *libraries/joomla/application/user/authentication.php
+
*<tt>libraries/joomla/application/user/authentication.php</tt>
  
 
+
==onUserBeforeSave==
===5.3.6 onBeforeStoreUser===
+
===Description===
====5.3.6.1 Description====
+
 
This event is triggered before an update of a user record.
 
This event is triggered before an update of a user record.
  
 
Password in $user array is already hashed at this point. You may retrieve the cleartext password using $_POST['password'].
 
Password in $user array is already hashed at this point. You may retrieve the cleartext password using $_POST['password'].
  
====5.3.6.2 Parameters====
+
===Parameters===
  * $user - An associative array of the columns in the user table (current values).
+
* $user - 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)
+
* $isnew - Boolean to identify if this is a new user (true - insert) or an existing one (false - update)
 
Note; You can retrieve the values that are about to get updated with JFactory::getUser();
 
Note; You can retrieve the values that are about to get updated with JFactory::getUser();
  
====5.3.6.3 Return Value====
+
===Return Value===
 
None
 
None
====5.3.6.4 Used in files====
+
===Used in files===
  *libraries/joomla/user/user.php
+
*<tt>libraries/joomla/user/user.php</tt>
====5.3.6.5 Examples====
+
===Examples===
  *plugins/user/example.php
+
*<tt>plugins/user/example.php</tt>
  
===5.3.7 onAfterStoreUser===
+
==onUserAfterSave==
====5.3.7.1 Description====
+
===Description===
 
This event is triggered after an update of a user record, or when a new user has been stored in the database.
 
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'].
 
Password in $user array is already hashed at this point. You may retrieve the cleartext password using $_POST['password'].
  
====5.3.7.2 Parameters====
+
===Parameters===
  * $user - An associative array of the columns in the user table.
+
* '''$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)
+
* '''$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
+
* '''$success''' - Boolean to identify if the store was successful
  * $msg - Error message if store failed
+
* '''$msg''' - Error message if store failed
Note; The old values that was just updated, is not available here/afterwards. In that case use onBeforeStoreUser()
+
Note: The old values that were just updated are not available here or afterwards. In case you need the old values, use onBeforeStoreUser().
  
====5.3.7.3 Return Value====
+
===Return Value===
 
None
 
None
====5.3.7.4 Used in files====
+
===Used in files===
  *libraries/joomla/user/user.php
+
*<tt>libraries/joomla/user/user.php</tt>
====5.3.7.5 Examples====
+
===Examples===
  *plugins/user/example.php
+
*<tt>plugins/user/example.php</tt>
  
 
+
==onUserBeforeDelete==
===5.3.8 onBeforeDeleteUser===
+
===Description===
====5.3.8.1 Description====
+
 
The event is triggered when a user is about to be deleted from the system.
 
The event is triggered when a user is about to be deleted from the system.
====5.3.8.2 Parameters====
+
===Parameters===
  * $user - An associative array of the columns in the user table.
+
* $user - An associative array of the columns in the user table.
  
====5.3.8.3 Return Value====
+
===Return Value===
 
None.
 
None.
====5.3.8.4 Used in files====
+
===Used in files===
  *libraries/joomla/user/user.php
+
*<tt>libraries/joomla/user/user.php</tt>
  *plugins/user/joomla.php
+
*<tt>plugins/user/joomla.php</tt>
====5.3.8.5 Examples====
+
===Examples===
  *plugins/user/example.php
+
*<tt>plugins/user/example.php</tt>
  
 
+
==onUserAfterDelete==
===5.3.9 onAfterDeleteUser===
+
===Description===
====5.3.9.1 Description====
+
 
The event is triggered after a user has been deleted from the system.
 
The event is triggered after a user has been deleted from the system.
====5.3.9.2 Parameters====
+
===Parameters===
  * $user - An associative array of the columns in the user table.
+
* $user - An associative array of the columns in the user table.
  * $succes - Boolean to identify if the deletion was successful
+
* $succes - Boolean to identify if the deletion was successful
  * $msg - Error message if delete failed ([[references:joomla.framework:utilities:jerror|JError]] object detailing the error, if any)
+
* $msg - Error message if delete failed ([http://api.joomla.org/Joomla-Framework/Error/JError.html JError] object detailing the error, if any)
  
====5.3.9.3 Return Value====
+
===Return Value===
 
None.
 
None.
====5.3.9.4 Used in files====
+
===Used in files===
  *libraries/joomla/user/user.php
+
*<tt>libraries/joomla/user/user.php</tt>
  *plugins/user/joomla.php
+
*<tt>plugins/user/joomla.php</tt>
====5.3.9.5 Examples====
+
===Examples===
  *plugins/user/example.php
+
*<tt>plugins/user/example.php</tt>
 +
 
 +
<noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude>

Revision as of 08:16, 26 April 2013

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

Contents

Stop hand nuvola.svg.png
Warning!

This page is under migration to Joomla 2.5 new plugin trigger methods


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

The user events are divided into two parts. First we have the events used while authentication of a user takes place:

  • onUserLogin (on Joomla 1.5: onLoginUser)
  • onUserLogout (on Joomla 1.5: onLogoutUser)
  • onUserAuthenticate (on Joomla 1.5: onAuthenticate)
  • onUserAuthorisationFailure (on Joomla 1.5: onAuthenticateFailure)

Second we have the events triggered during user management:

  • onUserBeforeSave (on Joomla 1.5: onBeforeStoreUser)
  • onUserAfterSave (on Joomla 1.5: onAfterStoreUser)
  • onUserBeforeDelete (on Joomla 1.5: onBeforeDeleteUser)
  • onUserAfterDelete (on Joomla 1.5: onAfterDeleteUser)

onUserLogin

Description

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 onAuthenticate instead.

Parameters

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

Return Value

Boolean

Used in files

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

Examples

  • plugins/user/example.php

onUserLogout

Description

This event is triggered before the user is logged out of the system. If one plugin returns false, the global logout fails. (needs verification)

Parameters

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

Return Value

Boolean

Used in files

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

Examples

  • plugins/user/example.php

onUserAuthenticate

Description

This event is triggered to verify that a set of login credentials is valid.

Parameters

Array of credentials. Structure:\\ ['username']\\ ['password']\\ Alternative authentication mechanisms can supply additional credentials.

Return Value

An array of JAuthenticateResponse objects detailing the results of each called plugin, including success or failure.

Used in files

  • libraries/joomla/application/user/authentication.php
  • plugins/authentication/gmail.php
  • plugins/authentication/joomla.php
  • plugins/authentication/ldap.php

Examples

  • plugins/authentication/example.php

onUserLoginFailure

Description

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

Parameters

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

Return Value

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

Used in files

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

onUserBeforeSave

Description

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

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

Parameters

  • $user - 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)

Note; You can retrieve the values that are about to get updated with JFactory::getUser();

Return Value

None

Used in files

  • libraries/joomla/user/user.php

Examples

  • plugins/user/example.php

onUserAfterSave

Description

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

  • $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

None

Used in files

  • libraries/joomla/user/user.php

Examples

  • plugins/user/example.php

onUserBeforeDelete

Description

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

Parameters

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

Return Value

None.

Used in files

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

Examples

  • plugins/user/example.php

onUserAfterDelete

Description

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

Parameters

  • $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

None.

Used in files

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

Examples

  • plugins/user/example.php