webiik/attempts

The Attempts provides common interface for user actions monitoring.

1.0 2019-03-28 17:39 UTC

Requires

• php: >=7.2

MIT

• Jiri Mihal

• attempts

README

Attempts

The Attempts provides common interface for user actions monitoring.

Installation

composer require webiik/attempts

Example

The following example expects you have already written your custom storage.

// Instatiate Attempts
$attempts = new \Webiik\Attempts\Attempts();

// Set storage (you have to write your own storage)
$attempts->setStorage(function() {
    return new \Webiik\Attempts\YourCustomStorage();
});

// Store user login attempt
$attempts->write('login', $attempts->getIp());

// Get user login attempts within the last hour
$startTimestamp = time() - 60 * 60;
$loginAttempts = $attempts->readByIp('login', $attempts->getIp(), $startTimestamp);

if(count($loginAttempts) > 10) {
    // E.g. Temporary prevent user to log in
}

// Delete expired login attempts with probability 2/100
$attempts->delete('login', $startTimestamp, 2);

Configuration

setStorage

setStorage(callable $factory): void

setStorage() sets storage factory. Storage writes, reads and deletes user attempts. Every storage must implement StorageInterface. Take a look at StorageInterface to get more info. Keep on mind you have to write your own storage. For example, you can write storage that uses MySQL database to write, read and delete user attempts.

$attempts->setStorage(function() {
    return new \Webiik\Attempts\YourCustomStorage();
});

User Identifier

getIp

getIp(): string

getIp() returns user IP address.

$ip = $attempts->getIp();

Attempts

write

write(string $label, string $ip, string $hash = ''): void

write() writes user attempt to storage.

Parameters

• label label representing user action e.g. login
• ip user IP address (simple user identifier)
• hash advanced user identifier e.g. hash from user IP, OS, browser language and installed fonts

$attempts->write('login', $ip, $hash);

read

read(string $label, string $ip, string $hash, int $startTimestamp = 0): array

read() reads user attempts from storage by label, hash and ip starting from startTimestamp.

$startTimestamp = time() - 60 * 60;
$loginAttempts = $attempts->read('login', $ip, $hash, $startTimestamp);

readByIp

readByIp(string $label, string $ip, int $startTimestamp = 0): array

readByIp() reads user attempts from storage by label and ip starting from startTimestamp.

$startTimestamp = time() - 60 * 60;
$loginAttempts = $attempts->readByIp('login', $ip, $startTimestamp);

readByHash

readByHash(string $label, string $hash, int $startTimestamp = 0): array

readByHash() reads user attempts from storage by label and hash starting from startTimestamp.

$startTimestamp = time() - 60 * 60;
$loginAttempts = $attempts->readByHash('login', $hash, $startTimestamp);

delete

delete(string $label, int $timestamp, int $probability = 1): void

delete() deletes user attempts from storage by the specific label, older than the timestamp, with default probability 1/100.

$olderThanTimestamp = time() - 60 * 60;
$attempts->delete('login', $olderThanTimestamp);

deleteAll

deleteAll(int $timestamp, int $probability = 1): void

deleteAll() deletes user attempts from storage older than the timestamp, with default probability 1/100.

$olderThanTimestamp = time() - 60 * 60;
$attempts->delete($olderThanTimestamp);

Resources

• Webiik framework
• Report issue