README

Overview
Installation
Usage
Testing
Security
Contribution
Changelog
Upgrading
License

Overview

A Laravel package that provides secure codes management system, allowing you to generate n-digit secure codes and manage it's allocation within you existing web app.

Installation

Requirements

The package has been developed and tested to work with the following minimum requirements:

PHP 8.x
Laravel 11.x

Secure-code requires either the BC Math or GMP PHP extensions in order to work.

Install the Package

You can install the package via Composer:

composer require veeqtoh/secure-code

Publish the Config and Migrations

You can then publish the package's config file and database migrations by using the following command:

php artisan vendor:publish --provider="Veeqtoh\SecureCode\Providers\SecureCodeProvider"

Migrate the Database

This package contains a migration file that add a new table to the database: secure_codes. To run this migration, simply run the following command:

php artisan migrate

Usage

Generating Secure Codes

Quick Start

The quickest way to get started with generating a secure code is by using the snippet below.

use Veeqtoh\SecureCode\Classes\CodeGenerator;

$codeGenerator = new CodeGenerator();
$secureCode    = $codeGenerator->generate();

echo "Generated code: $code";

Validation

By default, the secure code is not validated against any condition. The library however, comes with three (3) inbuilt validation classes that checks for;

Palindrome.
Repeated characters.
Sequence length.

These validation classes can be initialized and passed down to the code generator class in an array on it's constructor as shown below;

use Veeqtoh\SecureCode\Classes\CodeGenerator;

// Define specific validation rules.
$validators = [
    new NoPalindromeValidator(),
    new RepeatingCharactersValidator(),
    new MinimumUniqueCharactersValidator(),
  ];

// Generate a secure n-digit code.
$codeGenerator = new CodeGenerator();
$secureCode    = $codeGenerator->generate();

echo "Generated code: $code";

You may wish to define a custom validation yourself for more control. You can

Custom Validation

To achieve this, you must write a class that implements the library's base validation interface as follows;

Defining your custom validation class

declare(strict_types=1);

namespace Your\Custom\Class\Namespace;

use Veeqtoh\SecureCode\Contracts\CodeValidator;

class YourCustomValidatorValidator implements CodeValidator
{

  public function isValid(string $code): bool
  {
      return 'your custom rule';
  }

}

To use your custom rule, simply initialize and include it in the validators array as shown above.

Customizing Configs

Tailor the package to to your needs with customizable configuration options:

Database Connection: Specify a custom database connection if needed.
Code Generation Rules: Define code length and constraints like character repetition and unique characters limit.
Code Format: Choose from numeric, alphanumeric, or mixed formats for generated codes.
Code Characters: Customize character sets for different code formats.
Config Validation: Optionally validate configuration for safety.
Eloquent Factories: Define factories for testing purposes. With these options, you can configure the system to align with your security standards and requirements.

Note: The code length cannot be more than 19.

Facade

If you prefer to use facades in Laravel, you can choose to use the provided SecureCode facade instead of instantiating the CodeGenerator class manually.

Using the Secure Code Manager

The code manager provides functionality to manage generated access codes, including allocation, resetting, and destruction.

Allocating a Code

To allocate a code to an owner, you can use the allocateCode method:

use Veeqtoh\DoorAccess\Classes\CodeManager;

$manager = new CodeManager();
$code    = $manager->allocateCode('generated-code', 'owner-id');

echo "Allocated code: $code";

Resetting a Code

To reset a code and make it available for reallocation, you can use the resetCode method:

use Veeqtoh\DoorAccess\Classes\CodeManager;

$manager = new CodeManager();
$success = $manager->resetCode('allocated-code');

if ($success) {
    echo "Code reset successfully";
} else {
    echo "Failed to reset code";
}

Destroying a Code

To permanently destroy a code, you can use the destroyCode method:

use Veeqtoh\DoorAccess\Classes\CodeManager;

$manager = new CodeManager();
$success = $manager->destroyCode('code-to-destroy');

if ($success) {
    echo "Code destroyed successfully";
} else {
    echo "Failed to destroy code";
}

Config Validation

By default, the values defined in the secure-code.php config file are validated as the library contains a validator that is used to ensure that your values are safe to use. To disable the config validation, you can set the following option in the config:

'validate_config' => false,

Custom Database Connection

By default, Secure code will use your application's default database connection. But there may be times that you'd like to use a different connection. For example, you might be building a multi-tenant application that uses a separate connection for each tenant, and you may want to store the Secure codes in a central database.

To do this, you can set the connection name using the connection config value in the config/secure-code.php file like so:

'connection' => 'custom_database_connection_name',

Helper Methods

Find by code

To find the SecureCode model that corresponds to a given code, you can use the ->findByCode() method.

For example, to find the SecureCode model of a code that has the code abc123, you could use the following:

$secureCode = \Veeqtoh\SecureCode\Models\SecureCode::findByCode('abc123');

Find by Owner

To find the SecureCode models that belongs to a given owner ID, you can use the ->findByOwnerId() method.

For example, to find all of the SecureCode models of owners that belongs to john doe, you could use the following:

$secureCodes = \Veeqtoh\SecureCode\Models\SecureCode::findByOwnerId('john doe');

Model Factories

The package comes with model factories included for testing purposes.

use Veeqtoh\SecureCode\Models\SecureCode;

Testing

To run the package's unit tests, run the following command:

vendor/bin/pest

Security

If you find any security related issues, please contact me directly at victorjohnukam@gmail.com to report it.

Contribution

If you wish to make any changes or improvements to the package, feel free to make a pull request.

Note: A contribution guide will be added soon.

Changelog

Check the CHANGELOG to get more information about the latest changes.

Upgrading

Check the UPGRADE guide to get more information on how to update this library to newer versions.

License

The MIT License (MIT). Please see License File for more information.

Support Me

If you've found this package useful, please consider sponsoring this project. It will encourage me to keep maintaining it.

veeqtoh / secure-code

Maintainers

Details