Download the PHP package digitaltunnel/secure-code without Composer

Secure Code

Cryptographically secure random code generator with a fluent API for Laravel.

Generate PINs, voucher codes, serial keys, invite tokens, verification codes, sequential document IDs, and more -- all powered by PHP's random_int() CSPRNG under the hood.

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• Usage
  • Basic Generation
  • Code Length
  • Character Sets
  • Custom Character Pool
  • Prefix & Suffix
  • Separators
  • Case Forcing
  • Exclude Similar Characters
  • Batch Generation
  • Uniqueness Checking
  • Database Uniqueness
  • Max Attempts
  • Presets
  • Pattern-Based Generation
  • Checksum (Luhn & Mod-97)
  • Code Masking
  • Entropy Calculator
  • Code Vault (TTL & Verification)
  • HashId Encoding
  • Export (JSON, CSV, Text)
  • Events
  • Validation Rule
  • Sequential Document IDs
  • Artisan Command
  • Blade Directive
  • Facade
  • Combining Options
• API Reference
• Real-World Examples
• Architecture
• Testing
• Security
• License

Requirements

Installation

The package auto-discovers its service provider and facade. No manual registration needed.

Publish Configuration (optional)

This publishes config/secure-code.php where you can set application-wide defaults.

Publish Migrations (required for Sequential IDs)

This creates the secure_code_sequences table used by the sequential document ID generator. Only needed if you use the sequence() feature.

Quick Start

Configuration

After publishing, edit config/secure-code.php:

All options can be overridden per-call via the fluent API.

Usage

Basic Generation

Code Length

Character Sets

The Charset enum provides 13 predefined character pools:

Available Charsets:

Custom Character Pool

Prefix & Suffix

Prefix and suffix are not counted toward length.

Separators

Separators are inserted after generation and don't affect the random character count.

Case Forcing

Exclude Similar Characters

Remove visually ambiguous characters (0, O, 1, I, l) from the pool:

Batch Generation

When count is 1, a single string is returned (not an array). Codes within a batch are always unique to each other.

Uniqueness Checking

Using a Closure:

Using the UniquenessChecker Interface:

Database Uniqueness

Built-in shorthand for database uniqueness -- no manual closure needed:

Max Attempts

Default: 1000 (configurable in config/secure-code.php).

Presets

Preconfigured templates for common use cases:

You can also use the enum directly and override options:

Available Presets:

Pattern-Based Generation

Define the exact shape of your code using placeholder characters:

Checksum (Luhn & Mod-97)

Append self-validating check digits to generated codes:

Luhn (for numeric codes):

Mod-97 (for alphanumeric codes):

Use directly:

Code Masking

Hide parts of a code for secure display in UIs and logs:

Entropy Calculator

Evaluate the security strength of your code configuration before generating:

Strength levels:

Code Vault (TTL & Verification)

Issue short-lived codes with automatic expiry and brute-force protection -- ideal for email verification, 2FA, and OTP flows:

The vault uses timing-safe comparison (hash_equals) and automatically deletes the code after max failed attempts to prevent brute-force attacks.

HashId Encoding

Encode integer IDs into short, obfuscated strings (reversible):

Export (JSON, CSV, Text)

Generate codes and export them directly:

Events

Opt-in event dispatching for audit logging:

Listen for events in your EventServiceProvider or with closures:

Events are not dispatched by default -- you must call withEvents() to opt in.

Validation Rule

Validate incoming codes against format, length, charset, pattern, or checksum:

Sequential Document IDs

Generate gap-free, duplicate-free sequential document numbers (invoices, orders, receipts, etc.) backed by database-level locking. Safe for heavy concurrent transactions.

Requires migration: Run php artisan vendor:publish --tag=secure-code-migrations && php artisan migrate first.

Basic usage:

Full format with date tokens:

Batch allocation (atomic, contiguous):

Inspect and preview:

Period-based reset:

Custom start value and DB connection:

Format tokens:

How it works under the hood:

• Each call to next() runs an autonomous database transaction with SELECT ... FOR UPDATE
• This acquires an exclusive row lock, preventing concurrent access
• The sequence number is committed immediately, independent of any outer transaction
• No gaps: numbers are contiguous (1, 2, 3, ...)
• No duplicates: row-level locking serializes access
• Deadlock-free: each operation locks exactly one row
• Different sequence keys ('invoice' vs 'order') are fully independent

Tip: For strict isolation from your application's transactions, configure a dedicated database connection in config/secure-code.php under sequences.connection.

Artisan Command

Generate codes from the command line:

Blade Directive

Quick inline generation in Blade templates:

Facade

The package registers a facade automatically:

Combining Options

All methods are chainable and can be freely combined:

API Reference

SecureCode (Static Entry Point)

CodeBuilder (Fluent Builder)

Immutable -- every method returns a new instance:

Additional methods on CodeBuilder:

Support Classes

SequenceBuilder (Fluent Builder)

Immutable -- every method returns a new instance:

Real-World Examples

Email Verification Flow

Gift Card with Self-Validating Checksum

Obfuscated Order URLs

Batch Promo Codes Export

Security Audit with Entropy Check

Two-Factor Authentication

Invoice Numbers (Sequential)

Architecture

Security: All randomness is produced by random_int(), which draws from the OS CSPRNG. The Code Vault uses hash_equals for timing-safe comparison.

Immutability: CodeBuilder clones itself on every fluent call. Safe to store and reuse as templates.

Testing

The package ships with 171 Pest tests covering every feature:

Security

If you discover a security vulnerability, please send an email to [email protected] instead of opening a public issue.

See SECURITY.md for full details on our security policy, supported versions, and best practices.

License

The MIT License (MIT). See LICENSE for details.