====== AUTH_USER_CHANGE ======

---- dataentry event ----
Description:    Intercept user data modifications before they are sent to the auth backend
DefaultAction:  Call createUser, modifyUser or deleteUsers methods of an auth class.
Preventable:    yes
Added_dt:       2008-08-17
----

You can use this event for logging changes to user data, to enforce password security or to prevent unsuitable user names. It is signaled from method ''triggerUserMod'' in [[xref>inc/auth/basic.class.php]]. This method should be called when modifying user data instead of calling createUser, modifyUser or deleteUsers directly.

===== Passed Data =====
An array is passed with the event object. Its exact composition differs between the three different AUTH_USER_CHANGE types (create, modify, delete).
  * $data['type'] - Type of data modification (create, modify, delete)
  * $data['params'] - Parameter array for the createUser, modifyUser or deleteUsers methods of an auth class.

==== Create ====

When a user is created, all of that user's information is sent with the event. These arrays are only index keyed.
<code>
array (
     ['type']   => 'create',
     ['params'] => 
          array (
               [0] => 'username',
               [1] => 'password',
               [2] => 'realname',
               [3] => 'e@mail.com',
               [4] => 
                    array (
                    [0] => 'group1',
                    [1] => 'group2',
               ),
          ),
     ['modification_result'] => 'password',
)
//Example usage:
$event->data['params'][0] = 'username'
$event->data['params'][1] = 'password'
$event->data['params'][4][0] = 'group1'
</code>
==== Modify ====
When a user is modified, only the changed entries are sent with the event. The user's pre-modification username is always accessible. The keys within the ['params'][1] array indicate which field was changed, and the values within the array contain the new information. When writing your plugins to intercept modifications, you will want to check to see which keys are set.
<code>
array (
     ['type']   => 'modify',
     ['params'] => 
     array (
          [0] => 'username',
          [1] => 
               array (
                    ['user'] => 'new_username',
                    ['pass'] => 'new_password',
                    ['name'] => 'new_realname',
                    ['mail'] => 'new_e@mail.com',
                    ['grps'] => 
                         array (
                              [0] => 'group1',
                              [1] => 'group2',
                         ),
               ),
     ),
     ['modification_result'] => true,
)
//Example usage:
$event->data['params'][0] = 'username'
$event->data['params'][1]['user'] = 'new_username'
$event->data['params'][1]['grps'][0] = 'group1'
</code>
==== Delete ====
When a user deleted, the event data generally only contains that user's username. 
<code>
array (
     ['type']   => 'delete',
     ['params'] => 
          array (
               [0] => 
                    array (
                         [0] => 'username',
                    ),
          ),
     'modification_result' => 1,
)
//Example usage:
$event->data['params'][0][0] = 'username'
</code>

''modification_result'' varies between the different event types. It is generally the result from the modification function or false if an event handler has canceled the action and can be used in the AFTER handler to run actions after a user has been successfully been modified.


===== See also =====

  * [[codesearch>AUTH_USER_CHANGE|Code related to this event]] used in any DokuWiki's files, plugins and templates
  * [[devel:Action Plugins]]
  * [[devel:Events]]
  * [[:auth|Authentication Backends]]