Properties

$userLogInAttemptsRemaining

$userLogInAttemptsRemaining : integer

Type

integer

Methods

create()

create(array  $userCredentials) 

CRUD Alias for the register() method. See the documentation for register() to learn about this method.

Parameters

array $userCredentials

read()

read(mixed  $uidOrEmailOrArrayCriteria) : array<mixed,mixed>

CRUD wrapper for various user fetching methods.

Use it as a universal user fetching tool. It responds to 3 types of criteria: array (supply arbitrary params as key => value), integer (user id, aka UID), or string (user email address which has been activated). This method will always return data for only one user, thus the usage of UID is recommended.

Example #1 - Fetch using array params:

\NAuthentication\Auth::read([
    'first_name' => 'John',
    'last_name' => 'Olliver',
    // optionally, more fields
]);

Example #2 - Fetch using user ID:

\NAuthentication\Auth::read(5);

Example #3 - Fetch using activated (confirmed) email address:

\NAuthentication\Auth::read([email protected]');

Parameters

mixed $uidOrEmailOrArrayCriteria

User identifier(s).

Throws

\NAuthentication\NAuthException

Returns

array<mixed,mixed> —

Returns associative array containing user data.

update()

update(  $userId, array  $profileData) 

CRUD Alias for the updateProfile() method. See the documentation for updateProfile() to learn about this method.

Parameters

$userId
array $profileData

delete()

delete(  $userId) 

CRUD Alias for the deleteUser() method. See the documentation for deleteUser() to learn about this method.

Parameters

$userId

register()

register(array<mixed,string>  $userData) : string|integer

Account registration method.

Validates the input received and inserts it into the database. By default, this method will also send the activation email, and require the user to activate (verify the email address) its account before being able to log in. If $Account_Activation_Required is set to false in the Config file, then this method will not send the activation email, but it will instead activate the account automatically, and, will instead of the activation token, return user id.

Example:

// assumes $_POST is coming from a registration form, and can look something like this:
$_POST = array(
    'email' => [email protected]'
    'password' => 'my_password_456'
    // optionally, more fields
);

\NAuthentication\Auth::register($_POST);

Parameters

array<mixed,string> $userData

Supplied user credentials to insert into the database records. This will usually be email address and password. Passed as an array, where field names are array indexes, and field values are array values.

Throws

\NAuthentication\NAuthException

Returns

string|integer —

By default, returns user's activation token which was sent to the supplied email address. The token is to be used in activate() method. If $Account_Activation_Required is set to false in the Config file, user ID (UID) will be returned instead.

generateAntiReplayToken()

generateAntiReplayToken() : string

Generates replay attack countermeasure token.

This token can be (and should be, but is not mandatory) used as a part of the register form, to prevent replaying the input. If you using a system like reCAPTCHA, there's no need to use this method.

Returns

string —

Token

verifyAntiReplayToken()

verifyAntiReplayToken(  $token) : boolean

Verifies replay attack countermeasure token.

Verifies token generated by generateAntiReplayToken() method.

Parameters

$token

Token generated by generateAntiReplayToken() method.

Throws

\NAuthentication\NAuthException

Returns

boolean —

Returns true if the verification succeeds. An exception is thrown otherwise.

activate()

activate(string  $token) : integer

Account activation method.

Checks the token against the database and activates the account.

Example:

// $_GET['token'] can be something like this:
$_GET['token'] = 'b7cd84650df6a88246b137334d38c58257e2250798dba486112539254eaa795d02365ed9f0411ddb1a162ad01c61efb7bcde';

\NAuthentication\Auth::activate($_GET['token']);

Parameters

string $token

Token generated by the register() method.

Throws

\NAuthentication\NAuthException

Returns

integer —

User ID (UID).

resendActivationEmail()

resendActivationEmail(string  $token) : string

Resend activation email message

In case previous activation email message wasn't delivered (as signaled by the user, by, for instance clicking on a Resend Activation Email link), resend it. Expects an already created activation token previously returned by register() or this method.

Example:

// $registrationToken can be something like this:
$registrationToken = '24506af4d9cfb1dd2daab5f77f7ee2272afb88c33c672802865c414ede9d12dc7e4eb78e910431f6ea6374fd41e8fbcd3c25';

\NAuthentication\Auth::resendActivationEmail($registrationToken);

Parameters

string $token

Account activation token returned by register() or this method.

Throws

\NAuthentication\NAuthException

Returns

string —

Returns the activation token sent to the user's email address.

logIn()

logIn(array  $criteria) 

Alias for the authenticate() method. See the documentation for authenticate() to learn about this method.

Parameters

array $criteria

authenticate()

authenticate(array<mixed,string>  $criteria, boolean  $rememberMe = false) : array<mixed,mixed>

Authenticates (logs in) a user

Validates given criteria against database records, and logs in the user by initializing session and setting a cookie. Most commonly you'll feed the function with email address and password in an array, but other fields can be used as well (for instance, first name, last name, and so on). Passed as an array, where field names are array indexes, and field values are array values (key => value).

Example:

//$_POST can be something like this:
$_POST = array(
    'email' => [email protected]',
    'password' => 'user_password456'
);

\NAuthentication\Auth::authenticate($_POST);

Parameters

array<mixed,string> $criteria

A set of criteria to match against the database.

boolean $rememberMe

(Optional) If true, a long-lasting cookie will be implanted. Otherwise, a session cookie will be set. Defaults to false.

Throws

\NAuthentication\NAuthException

Returns

array<mixed,mixed> —

User data stored in the database.

logInRemainingAttempts()

logInRemainingAttempts() : integer

Returns remaining login attempts for current user.

Can be used in conjuction with logIn() or authenticate() methods to check how much log in attempts the current user has. This, for example, makes you able to implement the "You have X retries left before being locked out for 30 minutes." feature.

Returns

integer

isLoggedIn()

isLoggedIn() : boolean

Checks whether the user is logged in (in other words, authenticated).

This method should be used at every member-only page. Session fields set in Config::$Session_Fields are checked.

Example:

\NAuthentication\Auth::isLoggedIn();

Returns

boolean —

Returns true is user is logged in(authenticated), false otherwise.

logOut()

logOut() : void

Logs the user out.

This method behaves in two different ways. If you use the library session name ($Use_Library_Session_Name property inside Config), and therefore, library cookie name, upon logging out, the cookie and the session be destroyed. If you don't use the library session name, then the cookie and session are not destroyed, UNLESS there are no more session fields after unsetting uid and email fields. In both cases, logged out users won't be able to access members-only sections before logging in again.

Example:

\NAuthentication\Auth::logOut();

deauthenticate()

deauthenticate() 

Alias for the logOut() method.

passwordReset()

passwordReset(string  $email) : string

Initiates the password reset process.

Expects email address, checks if it exists and is confirmed (activated), and sends an email message containing password reset link. Generates a token (embedded in the password reset link sent by email) to be used in passwordResetNewPassword() method.

Example:

// $_POST['email'] can be something like this:
$_POST['email'] = [email protected]';

\NAuthentication\Auth::passwordReset($_POST['email']);

Parameters

string $email

Email address.

Throws

\NAuthentication\NAuthException

Returns

string —

Password reset token.

resendPasswordResetEmail()

resendPasswordResetEmail(string  $token) : string

Resend password reset message.

In case previous password reset email message wasn't delivered (as signaled by the user, by, for instance, clicking on a Resend Password Reset Email), resend it. Expects an already created token returned by a call to passwordReset() or this method.

Example:

// $token will be something this:
$token = '6b505e521c023c7a8e2748dfafc25bcb56df6d2014d1d0ba1594c7a55120dafb132297df3c677ffc7fae92dd1df00905eec0';

\NAuthentication\Auth::resendPasswordResetEmail($token);

Parameters

string $token

Password reset token returned by passwordReset() or previous call to this method.

Throws

\NAuthentication\NAuthException

Returns

string —

Returns the password reset token sent to the user's email address.

passwordResetNewPassword()

passwordResetNewPassword(string  $newPassword, string  $token) : integer

Finalizes the password reset process.

Expects a new account password and token generated by passwordReset() method, and changes the user password.

Example:

// $_POST['password'] can be something this:
$_POST['password'] = 'new_user_password456';
// $_POST['token'] can be something like this:
$_POST['token'] = '854712c4f2758e507bf01a2a83cae4ea4419603ba7f078c2ceb1b6586d87d53ff0991321f7a4a24495d94d392d86f6ab0955';

\NAuthentication\Auth::passwordResetNewPassword($_POST['password'], $_POST['token']);

Parameters

string $newPassword

New user password.

string $token

Token generated by passwordReset() method (embedded in password reset link).

Throws

\NAuthentication\NAuthException

Returns

integer —

User ID (UID).

changePassword()

changePassword(integer  $userId, string  $oldPassword, string  $newPassword) : integer

Enables users to change their password

Expects user's ID (UID), user's old password, and user's desired, new password. Usually placed inside Account Dashboard page.

Example:

// $_SESSION['uid'] can be something like this:
$_SESSION['uid'] = 10;
// $_POST['current_password'] can be something like this:
$_POST['current_password'] = "my_current_password456";
// $_POST['new_password'] can be something like this:
$_POST['new_password'] = "new_password567";

\NAuthentication\Auth::changePassword($_SESSION['uid'], $_POST['current_password'], $_POST['new_password']);

Parameters

integer $userId

User ID (UID)

string $oldPassword

Old user password

string $newPassword

New user password.

Throws

\NAuthentication\NAuthException

Returns

integer —

User ID (UID).

updateProfile()

updateProfile(integer  $userId, array<mixed,mixed>  $profileData) : array<mixed,mixed>

Enables user to change their profile data.

Expects user's ID (UID) and new profile data. This method obeys the $Editable_Fields directive in Config file.

Example:

// $_SESSION['uid'] can be something like this:
$_SESSION['uid'] = 10;
// $_POST can be something like this:
$_POST = array(
    'first_name' => 'Joe',
    'last_name'  => 'Steward',
    'city'       => 'Sydney'
);

\NAuthentication\Auth::updateProfile($_SESSION['uid'], $_POST);

Parameters

integer $userId

User's ID (UID)

array<mixed,mixed> $profileData

Supplied user data.

Throws

\NAuthentication\NAuthException

Returns

array<mixed,mixed> —

Updated user data.

getUserByUID()

getUserByUID(integer  $uid) : array<mixed,mixed>

Fetches user data that matches supplied UID.

Expects UID, returns user's data stored in database.

Example:

// The UID doesn't have to be currently logged in user. In any case, $_SESSION['uid'] can look something like this:
$_SESSION['uid'] = 50;

\NAuthentication\Auth::getUserById($_SESSION['uid']);

Parameters

integer $uid

User ID (UID)

Throws

\NAuthentication\NAuthException

Returns

array<mixed,mixed> —

User data stored in database.

getUserByEmail()

getUserByEmail(string  $email, boolean|null  $activated = true, boolean|null  $socialAccount = false) : array<mixed,mixed>

Fetches user data that matches supplied email address.

Expects email address, returns user's data stored in database. Supports is user activated? and is social account? filters. They're optional and can have a value true, false or null (null will omit the filter completely).

Example:

// $emailAddress can look something like this:
$emailAddress = [email protected]';

\NAuthentication\Auth::getUserByEmail($emailAddress);

Parameters

string $email

User's email

boolean|null $activated

(Optional) Fetch user account with activated email address. Defaults to true. Can be set to null too, which will skip this filter.

boolean|null $socialAccount

(Optional) Fetch user account logged in via social methods. Defaults to false. Can be set to null too, which will skip this filter.

Throws

\NAuthentication\NAuthException

Returns

array<mixed,mixed> —

User data stored in database.

userExists()

userExists(array<mixed,mixed>  $criteria) : boolean

Checks if user exists.

Checks whether there's a user in the database that matches the supplied set of criteria.

Example:

$userSearchCriteria = [
    'first_name' => 'Bill',
    'last_name'  => 'Gates',
    'photo'      => 'https://microsoft.com/assets/images/bill-and-jobs-bff.bmp'
];

\NAuthentication\Auth::userExists($userSearchCriteria);

Parameters

array<mixed,mixed> $criteria

The data of user being sought.

Throws

\NAuthentication\NAuthException

Returns

boolean —

Returns true is any user matches the supplied criteria; false otherwise.

deleteUser()

deleteUser(integer  $userId) : boolean

Delete an user.

Delete an user matching the user ID (UID).

Example:

// $UID can be something like this:
$UID = 10;

\NAuthentication\Auth::deleteUser($UID);

Parameters

integer $userId

User ID.

Throws

\NAuthentication\NAuthException

Returns

boolean —

Returns true is user has been deleted; false otherwise (when, for instance, supplied UID doesn't exist in database).

sendEmail()

sendEmail(string  $destination, string  $subject, string  $messageBody) : array|boolean

Sends email using either AWS SES or PHP's mail() function.

This method is used by the library to dispatch registration, activation, and password change links. It can be used outside of the library as well. Both HTML and plaintext messages are supported. $Use_SES directive in Config file controls whether AWS SES or PHP's mail() function is going to be used.

Example:

\NAuthentication\Auth::sendEmail([email protected]', 'Howdy, friend?', "Just wanted to say hai. \n -Steve");

Parameters

string $destination

Destination email address.

string $subject

Message subject.

string $messageBody

Message body.

Throws

\NAuthentication\NAuthException

Returns

array|boolean —

In case AWS SES is used, response array is returned; otherwise, true or false is returned, depending if the email was sent.

registeredAccountsCount()

registeredAccountsCount() : integer

Returns the registered accounts count.

Returns

integer

tablesCleanUp()

tablesCleanUp() : boolean

Makes sure library-related tables are kept fit.

This method is called internally by register() method. In other words, you don't need to call it manually.

Returns

boolean

addIPToLog()

addIPToLog(  $type,   $email,   $token) 

Parameters

$type
$email
$token

isIPWithinRetriesLimit()

isIPWithinRetriesLimit(  $type,   $email) 

Parameters

$type
$email

getTokenFromLogs()

getTokenFromLogs(  $type,   $email) 

Parameters

$type
$email

deleteFromLogs()

deleteFromLogs(  $type,   $ip) 

Parameters

$type
$ip

getUserByParams()

getUserByParams(array  $params) 

Parameters

array $params

retryResend()

retryResend(  $type,   $token) 

Parameters

$type
$token

insertTokenToDatabase()

insertTokenToDatabase(  $uid,   $type) 

Parameters

$uid
$type

composeEmailMessage()

composeEmailMessage(  $type,   $token) 

Parameters

$type
$token