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 webusers/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