README

A Laravel package for generating random strings and collections of unique strings with customizable character sets.

Features

• Generate single random strings or collections of unique strings
• Configurable character sets (alphanumeric, alphabetic, numeric, etc.)
• Exclude specific characters from generation
• Event system for tracking string generation
• Caching support for performance
• Fluent API with method chaining
• Laravel Facade support
• Comprehensive validation and error handling

Installation

You can install the package via composer:

composer require kodooy/laravel-string-generator

The package will automatically register itself via Laravel's package discovery.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=string-generator-config

This will create a config/string-generator.php file where you can customize:

• Default character sets
• Cache settings
• Event configuration
• Maximum attempt limits

Usage

Basic Usage

use Kodooy\StringGenerator\Facades\StringGenerator;

// Generate a single string (default length: 8)
$string = StringGenerator::single();

// Generate a string with custom length
$string = StringGenerator::single(12);

// Generate a collection of unique strings
$strings = StringGenerator::collection(5, 8); // 5 strings, each 8 characters long

Using Different Character Sets

// Alphanumeric (safe characters, excludes similar looking chars)
$string = StringGenerator::alphanumeric()->single(10);

// Alphabetic only
$string = StringGenerator::alpha()->single(10);

// Numeric only
$string = StringGenerator::numeric()->single(6);

// Lowercase only
$string = StringGenerator::lowercase()->single(8);

// Uppercase only
$string = StringGenerator::uppercase()->single(8);

// Custom charset
$string = StringGenerator::charset('xyz123')->single(10);

// Using predefined charset names
$string = StringGenerator::using('alphanumeric_safe')->single(10);

Excluding Characters

// Exclude specific characters
$string = StringGenerator::single(10, 'il1oO0'); // Exclude confusing characters

// With collections
$strings = StringGenerator::collection(5, 8, 'aeiou'); // Exclude vowels

Method Chaining

$string = StringGenerator::alphanumeric()->single(12, 'il1oO0');

$strings = StringGenerator::using('alpha_safe')
    ->collection(10, 6, 'xyz');

Using the Generator Class Directly

use Kodooy\StringGenerator\StringGenerator;

$generator = new StringGenerator();

// Same methods available
$string = $generator->single(8);
$strings = $generator->collection(5, 10);

Universal Generate Method

// Single string (when count is null or 1)
$string = StringGenerator::generate(8);
$string = StringGenerator::generate(8, 1);

// Collection (when count > 1)
$strings = StringGenerator::generate(8, 5); // 5 strings of length 8

Events

The package dispatches events when strings are generated:

• StringGenerated - Fired when a single string is generated
• StringCollectionGenerated - Fired when a collection is generated

// Listen for events
Event::listen(\Kodooy\StringGenerator\Events\StringGenerated::class, function ($event) {
    // $event->string, $event->length, $event->charset, $event->exclude
    Log::info('String generated: ' . $event->string);
});

Exception Handling

The package throws specific exceptions:

use Kodooy\StringGenerator\Exceptions\InsufficientUniqueStringsException;
use Kodooy\StringGenerator\Exceptions\InvalidCharsetException;

try {
    // This might fail if requesting too many unique strings
    $strings = StringGenerator::charset('ab')->collection(100, 2);
} catch (InsufficientUniqueStringsException $e) {
    // Handle the exception
}

Available Character Sets

The package includes several predefined character sets:

• alphanumeric - All letters and numbers
• alphanumeric_safe - Letters and numbers, excluding similar looking characters (i, l, I, o, O, 0)
• alpha - All letters (upper and lowercase)
• alpha_safe - Letters excluding similar looking characters (i, l, I, o, O)
• numeric - Numbers 0-9
• lowercase - Lowercase letters only
• uppercase - Uppercase letters only
• symbols - Special symbols

Testing

Run the tests with:

composer test

Or using Pest directly:

./vendor/bin/pest