# WebLoginPE: Advanced User Management.

## Version 1.3.0

### By Dr. Scotty Delicious, Scientist DFPA.

#### The WebLoginPE API (Application Programming Interface)

WebLoginPE is an Object Oriented PHP script. If you would like to extend WebLoginPE please use this document as a reference to it's API. If you are interested in extending the function of WebLoginPE through MODx Plugins, WebLoginPE invokes a suite of events throughout it's services that you can take advantage of.

Instantiation of the WebLoginPE object has 4 parameters, a Language array (required), a date format (optional), user image settings (optional), and type (optional).

##### Instance Variables

###### LanguageArray

An array of language specific phrases.
@var array
@access public
@see __construct()

###### Report

Holds a message if one was generated.
@var string
@access public
@see FormatMessage()

###### liHomeId

A comma separated list of MODx document IDs to attempt to redirect the user to after login.
@var string
@access public
@see login()
@see LoginHomePage()

###### loHomeId

The MODx document ID to redirect the user to after logout.
@var string
@access public
@see logout()
@see LogoutHomePage()

###### Type

the type of WebLoginPE (simple, register, profile, or taconite)
@var string
@access protected

###### Username

Value of $_POST['username'].
@var string
@access protected

###### Password

Value of $_POST['password'].
@var string
@access protected

###### User

The user object assembled from data queried from the web user tables
@var array
@access protected
@see QueryDbForUser()

###### UserImageSettings

Dimensions for the user image
@var string
@access protected
@see CreateUserImage

###### MessageTemplate

Template for messages returned by WebLoginPE
@var string;
@access public
@see FormatMessage;

###### LoginErrorCount

Number of failed logins
@var string
@access protected
@see Authenticate

###### CustomTable

Full table name of the custom extended user attributes table.
@var string
@access protected
@see CustomTable

###### CustomFields

An array of column names for the extended user attributes table.
@var array
@access protected
@see CustomTable

###### DateFormat

PHP strftime() format for dates in placeholders
@var string
@access protected
@see PlaceHolders

##### Web Access Service Events

###### OnBeforeAddToGroup

Invoked immediately BEFORE a registrant is added to the groups specified in &groups. This event is useful if you need to add the user to an additional group, perhaps a mailing list group based on the value of a checkbox. The parameter passed in this event is an array, $GLOBAL['groups'], which you can modify with a plugin before the user is added.

###### OnBeforeWebLogin

Invoked immediately BEFORE a user logs in. The parameters in this event are 'username', 'password', 'rememberme' and 'stayloggedin'.

###### OnWebAuthentication

Invoked DURING login when authentication is verified. WebLoginPE uses industry standard techniques to authenticate a user, but, if you have your own authentication schematic, or you want to verify more than just "username" and "password" (for example CAPTCHA or retina scan... j/k), you can use a plugin tied to this event. WebLoginPE will first try to pass authentication to this plugin. If there is no response, it will use it's own authentication. Parameters are 'internalKey', 'username', 'form_password', 'db_password', 'rememberme', and 'stayloggedin'.

###### OnWebLogin

Invoked immediately AFTER a user logs in. The parameter is an array including ALL the users attributes and extended attributes.

###### OnBeforeWebSaveUser

Invoked BEFORE user attributes are saved to the DB. This is invoked in both Register() AND SaveUserProfile(). Parameters are 'Attributes' and 'ExtendedFields', so... all the users info.

###### OnWebSaveUser

Invoked AFTER a user is saved to the DB. This is invoked in both Register() AND SaveUserProfile(). Parameters are 'mode' (new | update) and 'user' (an array of ALL the users attributes).

###### OnWebChangePassword

Invoked AFTER a user changes their password. This is invoked in ActivateUser() (when a user forgot their password, gets it reset and sets a new one.), and in SaveUserProfile() IF the user's password is changed. Parameters are 'internalKey', 'username', and 'password' (the NEW password).

###### OnViewUserProfile

Invoked EACH TIME a user's profile is viewed. This event could be useful for tracking profile hits. Parameters are 'internalKey' (the internalKey of the user who's profile is being viewed), 'username' (that user's username), 'viewerKey' (the internalKey of the viewer), 'viewername' (the username of the viewer).

###### OnWebDeleteUser

Invoked When a user account/profile is deleted. You could have a plugin bound to this event that emails the administrator when a user is deleted??? Parameters are 'internalKey', 'username', and 'timestamp'.

###### OnBeforeWebLogout

Invoked BEFORE a logged in user logs out. Parameters are 'userid' (the internalKey, kept for backwards compatibility with Raymond's original weblogin snippet), 'internalKey' (duh...), and 'username'.

###### OnWebLogout

Invoked AFTER a logged in user logs out. Same parameters as "OnBeforeWebLogout", just fired AFTER logout.

##### Public Methods

###### __construct( array $LanguageArray ) & WebLoginPE()

WebLoginPE Class Constructor
@param array $LanguageArray An array of language specific strings.
@return void
@author Scotty Delicious

###### FormatMessage( string $message )

Sets a value for $this->Report which is set in the placeholder [+wlpe.message+].
This function is public and can be used to format a message for the calling script.
@param string $message
@return void
@author Scotty Delicious

###### Login( string $type, string $liHomeId )

Perform all the necessary functions to establish a secure user session with permissions
@param string $type If type = 'taconite' do not call $this->LoginHomePage().
@param string $liHomeId Comma separated list of MODx document ID's to attempt to redirect to after login.
@return void
@author Scotty Delicious

###### AutoLogin()

AutoLogin checks for a user cookie and logs the user in automatically
@return void
@author Scotty Delicious

###### Logout()

Destroy the user session and redirect or refresh.
@param string $type If type = 'taconite' do not call $this->LogoutHomePage().
@param int $loHomeId MODx document ID to redirect to after logout.
@return void
@author Scotty Delicious

###### CustomTable( string $table, string $fields )

Custom table checks for the specified extended user attributes table and creates it if it does not exist.
It also checks for custom column names and inserts them into the extended user attributes table if they do not exist.
@param string $table The name of the custom table (Default is "web_user_attributes_extended")
@param string $fields A comma separated list of column names for the custom table.
@return void
@author Scotty Delicious

###### Register( string $regType, string $groups, string $regRequired, string $notify, string $notifyTpl, string $notifySubject )

Inserts a new user into the database.
@param string $regType 'instant' or 'verify'
@param string $groups which webgroup('s) should the new user be added to.
@param string $regRequired Comma separated list of required fields.
@param string $notify Comma separated list of emails to notify of new registrations.
@param string $notifyTpl Template for email notification message.
@param string $notifySubject Subject line for email notification.
@return void
@author Raymond Irving
@author Scotty Delicious

###### PruneUsers( int $pruneDays )

Removes non-activated user accounts older than the number of days specified in $pruneDays.
@param int $pruneDays The number of days to wait before removing non-activated users.
@return void
@author Scotty Delicious

###### Template( string $chunk )

Template takes a template parameter and checks to see if it is a chunk.
If it is a chunk, returns the contents of the chunk, if it is not a chunk,
tries to find a file of that name (or path) and gets its contents. If it
is not a chunk or a file, returns the value passed as the parameter $chunk.
@param string $chunk The name of a chunk to get.
@return string HTML block.
@author Scotty Delicious

###### SaveUserProfile()

Updates the relevant tables for a given internalKey.
@return void
@author Scotty Delicious

###### RemoveUserProfile()

Deletes the table entries in the relevant tables for a given internalKey.
@return void
@author Scotty Delicious

###### ViewAllUsers( string $userTemplate )

View all users stored in the web_users table.
@param string $userTemplate HTML template to display each web user.
@return string HTML block containing all the users
@author Scotty Delicious

###### ViewUserProfile( string $username )

ViewUserProfile displays sets the placeholders for the attributes of another site user
@param string $username The username of the other user's profile to view
@return void
@author Scotty Delicious

###### SendMessageToUser()

SendMessageToUser allows site users to send email messages to each other.
@return void.
@author Scotty Delicious

###### ResetPassword()

Sets a random password | random key in the web_users.cachepwd field,
then sends an email to the user with instructions and a URL to activate.
@return void
@author Raymond Irving
@author Scotty Delicious

###### ActivateUser()

Activates the user after they have requested to have their password reset.
@return void
@author Raymond Irving
@author Scotty Delicious

###### PlaceHolders( string $dateFormat, array $inputHandler, string $UserImageSettings, string $MessageTemplate )

Sets place holders using the MODx method setPlaceholder() for fields in web_user_attributes.
@param string $dateFormat The strftime() format set in the calling script.
@param array $inputHandler An array of inputs to... uhh... handle?
@param string $UserImageSettings The specifications for the user image.
@param string $MessageTemplate The template for $this->Report.
@return void
@author Scotty Delicious

###### RegisterScripts( string $customJs )

Uses the MODx regClientStartupScript() method to load the jQuery scripts for taconite.
Optionally, it can load a custom js file (passed as a parameter.) if needed.
@param string $customJs URL to a custom javascript file to be loaded.
@return void
@author Scotty Delicious

##### Protected Methods

###### OnBeforeWebLogin()

Invokes the MODx event OnBeforeWebLogin.
@return void
@author Scotty Delicious

###### Authenticate()

Authenticates the user or sets failure counts on error.
@return void
@author Scotty Delicious

###### OnBeforeWebLogout()

Invokes the MODx event OnBeforeWebLogout
@return void
@author Scotty Delicious

###### OnWebLogout()

Invokes the MODx event OnWebLogout
@return void
@author Scotty Delicious

###### UserDocumentGroups()

Find the web groups that this user is a member of.
@return void
@author Raymond Irving
@author Scotty Delicious

###### LoginHomePage()

Redirect user to specified login page ($this->liHomeId).
$this->liHomeId is an array, each document ID is queried.
The user is redirected to the first page that they have permission to view.
If $this->liHomeId is empty, refresh the current page.
@return void
@author Raymond Irving
@author Scotty Delicious

###### LogoutHomePage()

Redirect user to specified logout page ($this->loHomeId).
If $this->loHomeId is empty, refresh the current page.
@return void
@author Raymond Irving
@author Scotty Delicious

###### SessionHandler( string $directive )

Starts the user session on login success. Destroys session on error or logout.
@param string $directive ('start' or 'destroy')
@return void
@author Raymond Irving
@author Scotty Delicious

###### QueryDbForUser( string $Username )

Queries the web_users table for $_POST['username'].
@param string $Username The username of the user to query for.
@return void
@author Raymond Irving
@author Scotty Delicious

###### UserIsBlocked()

Queries the web_user_attributes table to see if this user should
be blocked. If the user IS blocked, prevent them from logging in.
@return void
@author Raymond Irving
@author Scotty Delicious

###### MakeDateForDb( string $date )

Returns a UNIX timestamp for the string provided.
@param string $date A date in the format MM-DD-YYY
@return int Returns a UNIX timestamp for the date provided.
@author Scotty Delicious

###### CreateUserImage()

Creates an image for the user profile from a user uploaded image.
This image is renamed to the username and moved to the webloginpe/userimages/ folder.
The URL to this image is returned to be stored in the web_user_attributes table.
@return string A URL to the user image created.
@author Scotty Delicious

###### StringForGenderInt( int $genderInt )

Returns a string ('Male', 'Female', or 'Unknown') for the integer $genderInt (integer stored in web_user_attributes).
@param int $genderInt (0, 1, or 2)
@return string (0 = 'Unknown', 1 = 'Male', 2 = 'Female')
@author Scotty Delicious

###### StringForCountryInt( int $countryInt )

Returns a string (the name of the country) for the integer $countryInt (integer stored in web_user_attributes).
@param int $countryInt
@return string The name of the country
@author Scotty Delicious

###### ValidateEmail( string $Email )

Validate an email address by regex and MX reccord
@param string $Email An email address.
@return void
@author Scotty Delicious

###### GeneratePassword( int $length )

Generate a random password of a specified number of characters. [a-z][A-Z][2-9].
@param int $length
@return void
@author Raymond Irving
@author Scotty Delicious

###### FetchAll( data source $ds )

Fetch all rows in a data source recursively
@param string $ds A data source.
@return array $all An array of the data source
@author Scotty Delicious

Home Parameters Views (Templates) Working with Forms Placeholders API

© 2007 Scotty Delicious.