adding api doc
[squirrelmail.git] / plugins / change_password / API
a4b225ee 1 ******************************
2 * Change Password plugin API *
3 ******************************
5Document should explain how to create change_password plugin backends and
6provide details about plugin structure.
8Plugin uses standard SquirrelMail plugin architecture and implements backends
9with two hooks.
11change_password_init hook
13change_password_init hook is used to execute some code before displaying
14change password form. Plugin can use this hook to check if install has all
15required components, or to check if backend is configured correctly, or
16display some messages to end user. Maybe some background information about
17password security and how to choose good password. If backend detects some
18configuration errors that make backend unusable, it can stop execution of the
19script with PHP exit() call.
21change_password_dochange hook
23change_password_dochange hook is used when user submits old and new passwords.
24Plugin checks if old password matches current session password and checks new
25password satisfies requirements set in plugin's configuration. All data is
26provided in array submitted via hook. 'username' key contains user's login
27name, 'curpw' contains current session password, 'newpw' contains new password.
28Function that is attached to plugin should return empty array or array filled
29with error messages. If array is empty - plugin assumes that password was
30changed and updates current session password.
32common strings
34Backends can use constants for some error messages. CPW_CURRENT_NOMATCH
35constant sets 'Your current password is not correct.' error. CPW_INVALID_PW
36constant sets 'Your new password contains invalid characters.' error.
40Backend should check, if current password matches stored password.
41Internal plugin functions only check if password matches the one that
42was used to login into SquirrelMail. Password is validated against IMAP
43server and not against used backend.
45Backend should store only default configuration variables that don't
46have any information specific to developer's server or these variables
47should be set to sane default values.
49Backend's configuration should be controlled with configuration overrides
50that are set config.php. It is recommended to use array with
51configuration overrides and make sure that array is set to empty value
52before loading plugin's configuration file.
54Backend should not use generic function names. It is recommended to use
55'cpw_' prefix.
57If backend must load other SquirrelMail functions, it must use SM_PATH
58constant in include_once() calls and make sure that SM_PATH is defined
59in any case when backend file is loaded. In most cases constant is
60already defined, but some unusual use of php files might cause php
61warnings, if constant is used inside backend functions and not defined
62in backend file.
64Overrides used by backend and backend requirements must be documented
65in README file.