Documentation

Users
in package

Application

User Login class

IMPORTANT: Requires a data source. See UsersDataSourceMySQLi.class.php for code which provides this for MySQLi

Users encapsulates a basic login and authentication package. It provides a login screen, authentication, the ability to edit oneself, and for users with the admin flag set, the ability to edit others.

It also allows a user to be disabled.

Users was designed to be extensible, adding new fields by the calling program, modifying the HTML elements, etc...

$configuration


    protected
        array<string|int, string>
    $configuration
     = array(
    /*
     * what to use for html input fields
     * These are passed to sprintf, with label, fieldname, title, placeholder and current value, in that order
     */
    'screens' => array('login form' => "<h1>Login</h1>
<form class='login_form' action='%s' method='post'>
%s
<input type='submit' value='Login'></form>
", 'edit form' => "<form class='login_form' action='%s' method='post'>
%s
<input type='submit' name='btnUpdate' value='Update'>
</form>", 'loginScreen' => "<div class='login_field'>
<input class='login_field' type='text' name='username' placeholder='Username' required autofocus>
</div>
<div class='login_field'>
<input class='login_field' type='password' name='password' placeholder='Password' required>
</div>", 'adminScreen' => "<input type='hidden' name='doAdmin' value='1'>
", 'validateScript' => ''),
    'html input fields' => array('text' => "<div class='login_field'>
<label>%s
<input class='login_field' type='text' name='%s' title='%s' placeholder='%s' value='~~%s~~'>
</label>
</div>", 'password' => "<div class='login_field'>
<label>%s
<input class='login_field' type='password' name='%s' title='%s' placeholder='%s'>
</label>
</div>", 'boolean' => "<div class='login_field'>
<label>%s
<input class='login_field' type='checkbox' name='%s' title='%s' value='1' %s ~~%s~~>
</label>
</div>", 'textarea' => "<div class='login_field'>
<label>%s
<textarea class='login_field' name='%s' title='%s' placeholder='%s'>~~%s~~</textarea>
</label>
</div>"),
    'input prefix' => 'admin_',
    // prefix the name with this in a form
    'tables' => array('users' => array(
        'table' => '_users',
        // table name for user records
        'id' => '_user_id',
        // ID column name
        'display' => array(
            // fields which are displayed to select
            'login',
        ),
        'form test' => 'login',
        // field to test if form submitted
        'fields' => array('login' => array(
            'label' => 'Username',
            // login name column name
            'html type' => 'text',
            'filter' => '/^[a-zA-Z0-9_]+$/',
            'instructions' => 'Username can only contain alpha numerics and an underscore',
            'hint' => 'Change User Name',
            'unique' => 	rue,
        ), 'pass' => array(
            'label' => 'Password',
            // password column name
            'html type' => 'password',
            'instructions' => 'Leave blank to keep same password',
            'hint' => 'Change Password',
        ), 'admin' => array('label' => 'isAdmin', 'html type' => 'boolean', 'restrict' => 	rue, 'instructions' => 'If checked, user will be able to add/edit users'), 'enabled' => array('label' => 'Enabled', 'html type' => 'boolean', 'restrict' => 	rue, 'instructions' => 'Uncheck to disable log in')),
    )),
)

Contains the configuration for the class

May be modified by the calling program. Must be replicated in userDataSource class

$data


    protected
        array<string|int, string>
    $data
     = array()

Contains the information for the current logged in user

$errors


    protected
        array<string|int, string>
    $errors
     = array()

Contains errors that can occur

$workingOn


    protected
        array<string|int, string>
    $workingOn
     = array()

During administration, contains the record being modified

__construct()

constructor for an instance of the class


    public
                __construct([array<string|int, string> $customFields = array() ]) : mixed

Anything in $customFields will be recursively merged with $configuration, overwriting as necessary.

Parameters

$customFields : array<string|int, string> = array(): array to merge into $configuration

Return values

mixed —

admin()

Sets up the admin function which allows users to edit themselves and, optionally, others


    public
                admin(usersDataSource $connection[, mixed $nextScript = null ]) : string

This should be called the first time, then repeatedly called until it is done (it returns the string "Updated", "Failed" or "No changes".

The first iteration returns an edit screen displaying the users information for them to edit. It will display an HTML INPUT for each field that is not restricted. The user can then edit the chosen entries and press the button, which will call the script again, and update the record.

If the user has the admin right, the Edit screen also displays a list of all users as an unsigned list of anchors. If the user clicks on one of those, it will choose that user, load their data and allow the user to edit that users record. NOTE: this is the only way to edit fields with the restrict flag set.

Parameters

$connection : usersDataSource: A connection to the data source
$nextScript : mixed = null

Return values

string —

This may be an HTML table or a single screen

allUsersHTML()

Get all users from data source and put them in an HTML list


    public
                allUsersHTML(usersDataSource $connection[, string $nextPage = null ]) : string

Will retrieve the ID and login name of all users, putting them in a list of anchors to allow an admin to select one for editing

Parameters

$connection : usersDataSource: A connection to the data source
$nextPage : string = null: The URL of the page to be used in the link

Return values

string —

an unordered list (UL) containing links with names

clearErrors()

clears the errors array


    public
                clearErrors() : mixed

Return values

mixed —

editScreen()

Creates an edit screen for display to user


    public
                editScreen(mixed $connection) : string

This function will create an edit screen which, when displayed to the user, allows them to edit a users record. The record is stored in $this->workingOn

Function will go through each field in the users table and call makeHTMLField for it, unless the field is restricted and the user is editing their own entry. It will also create a hidden input field with the users ID

NOTE: this will not create the form; the form is created someplace else

Parameters

$connection : mixed

Return values

string —

HTML containing all of the INPUT records a user can edit

errors()

getter for $this->errors


    public
                errors() : string

Return values

string —

html div containing one paragraph for every error

HTML()

Main display function.


    public
                HTML(usersDataSource $connection[, string $nextScript = null ]) : string

This function should be called to perform the login. It performs all functions needed to log in and validate, but once logged in, will return an empty string.

Parameters

$connection : usersDataSource: A connection to the data source
$nextScript : string = null: The url to be run when logged in

Return values

string —

A (possibly empty) HTML div

isAdmin()

getter for isAdmin


    public
                isAdmin() : bool

Return values

bool —

true if user is an admin, false if not

logOut()

Logs user out of system


    public
                logOut([string $nextScript = null ]) : mixed

destroys itself ($_SESSION['user'], then session, then calls $nextScript by doing a header call.

Parameters

$nextScript : string = null: URL of next script to call

Return values

mixed —

name()

getter for login name


    public
                name() : string

Return values

string —

user name

addEdit()


    protected
                addEdit(mixed $connection) : mixed

Parameters

$connection : mixed

Return values

mixed —

emptyWorkingOn()

Creates a variable designed to replace $this->workingOn


    protected
                emptyWorkingOn() : array<string|int, string>

Initializes all fields to something non-null and sets id to -1

Return values

array<string|int, string> —

An array initialized with all records needed

getNextScript()

Simple helper script to calculate next script to call


    protected
                getNextScript([string $nextScript = null ]) : string

Returns one of three URL strings, in order of precedence $nextScript $configuration['screens']['validateScript'] PHP_SELF

Parameters

$nextScript : string = null: URL to call

Return values

string —

URL

initWorkingOn()


    protected
                initWorkingOn(mixed $connection, mixed $id) : mixed

Parameters

$connection : mixed
$id : mixed

Return values

mixed —

logInScreen()

Creates the fields needed for a login screen


    protected
                logInScreen([string $nextScript = null ]) : string

Populates %s's in 'login form' with values for $nextScript and 'loginScreen'

Parameters

$nextScript : string = null: URL to call form

Return values

string —

HTML code for display

makeHTMLField()

Creates an HTML field for display


    protected
                makeHTMLField(string $field, array<string|int, string> $record, string $value) : string

Retrieves the template for the record type, then populates it from $record, $value and $field. The template MUST have %s's in the following order for an HTML INPUT field label= name= title= placeholder= value

Knows how to handle INPUT types TEXT, TEXTAREA, PASSWORD and special html type boolean, which is checkboxes.

Parameters

$field : string: name of the field to populate
$record : array<string|int, string>: Record from $configuration[...][fields]
$value : string: the current value to put in INPUT

Return values

string —

An HTML INPUT entity

validate()

Validates a connection and, on success, populates $data


    protected
                validate(string $username, string $password, usersDataSource $connection) : mixed

Function will validate the username and password passed in, using data connection $connection. On success, populates class member $data with the values from the database (only those listed in $configuration)

On Failure, appends $error with a failure string

Parameters

$username : string: The username to be matched in database
$password : string: The password (unencrypted) the user entered
$connection : usersDataSource: A connection to the data source

Return values

mixed —

Users in package Application

Tags

Table of Contents

Properties

$configuration

$data

$errors

$workingOn

Methods

__construct()

Parameters

Return values

admin()

Parameters

Return values

allUsersHTML()

Parameters

Return values

clearErrors()

Return values

editScreen()

Parameters

Return values

errors()

Return values

HTML()

Parameters

Return values

isAdmin()

Return values

logOut()

Parameters

Return values

name()

Return values

addEdit()

Parameters

Return values

emptyWorkingOn()

Return values

getNextScript()

Parameters

Return values

initWorkingOn()

Parameters

Return values

logInScreen()

Parameters

Return values

makeHTMLField()

Parameters

Return values

validate()

Parameters

Return values

Users
in package

Application