README

"Not all who wander are lost" - but all who need tokens shall find them here.

Generate memorable, human-readable token names inspired by Tolkien's Legendarium. Perfect for friendly resource identifiers, human-readable labels, memorable names for non-security-critical purposes, or any scenario where you need unique names that are easy to read and remember.

Why Arda Tokens?

Memorable: elvish-gandalf is easier to remember than a7b2c9d4e5f6
Readable: Easy to communicate verbally or spot in logs
Unique: Up to 825+ million combinations with hex suffixes
Secure: Uses random_int() and random_bytes() for cryptographically secure randomness
Simple: One static class, zero dependencies, zero configuration

Requirements

PHP 8.3 or higher

Installation

composer require wllcdev/arda-tokens

Quick Start

use Wllcdev\ArdaTokens\Arda;

// Generate a token
$token = Arda::token();  // "precious-frodo"

That's it! No configuration needed.

Usage

Generating Tokens

use Wllcdev\ArdaTokens\Arda;

// Default: no suffix
Arda::generate();     // "elvish-gandalf"
Arda::token();        // "hobbitish-shire" (alias)

// With suffix (1-4 characters)
Arda::generate(1);    // "golden-ring-f"
Arda::generate(2);    // "shadowy-mordor-4e"
Arda::generate(3);    // "mithril-aragorn-a3f"
Arda::generate(4);    // "starlit-galadriel-8f2a" (max)

// Invalid suffix length throws exception
Arda::generate(5);    // InvalidArgumentException
Arda::generate(-1);   // InvalidArgumentException

Checking Capacity

Calculate how many unique tokens can be generated:

use Wllcdev\ArdaTokens\Arda;

// Base capacity (no suffix)
Arda::capacity();              // 12,600
Arda::capacityWithSuffix(0);   // 12,600 (same as capacity())

// With hex suffix
Arda::capacityWithSuffix(1);   // 201,600
Arda::capacityWithSuffix(2);   // 3,225,600
Arda::capacityWithSuffix(3);   // 51,609,600
Arda::capacityWithSuffix(4);   // 825,753,600

Token Format

Tokens follow the pattern: {adjective}-{noun}[-{hex}]

Suffix Length	Example	Unique Combinations
0 (default)	`precious-ring`	12,600
1	`elvish-frodo-a`	201,600
2	`mithril-gandalf-3f`	3,225,600
3	`hobbitish-shire-a2b`	51,609,600
4 (max)	`ancient-mordor-f3a1`	825,753,600

Security Considerations

This package generates human-readable token names and is designed for:

Friendly identifiers for API tokens
Memorable names for resources
Human-readable labels
Non-security-critical naming

This package is NOT suitable for:

Session IDs (use PHP's session_regenerate_id())
Authentication tokens (use random_bytes() or dedicated libraries)
CSRF tokens (use framework-provided CSRF protection)
Password reset tokens
Any security-critical random values

Why?

The maximum entropy provided is ~30 bits (with 4-char suffix), which is below the OWASP-recommended minimum of 64 bits for security-sensitive applications.

Suffix Length	Unique Combinations	Entropy (bits)
0 (default)	12,600	~13.6
1	201,600	~17.6
2	3,225,600	~21.6
3	51,609,600	~25.6
4 (max)	825,753,600	~29.6

What Makes It Secure for Its Purpose?

Uses PHP's cryptographically secure random_int() and random_bytes()
Follows OWASP recommendations for secure random number generation
No sensitive information embedded in tokens

API Reference

`Arda::generate(int $suffixLength = 0): string`

Generates a random token name.

Parameter	Type	Default	Description
`$suffixLength`	`int`	`0`	Length of hex suffix (0-4).

Returns: string - The generated token name.

Throws:

InvalidArgumentException if $suffixLength is not between 0 and 4.
RuntimeException if secure random generation fails.

`Arda::token(int $suffixLength = 0): string`

Alias of generate().

`Arda::capacity(): int`

Returns the total number of unique combinations without a hex suffix.

Returns: int - Number of unique adjective-noun combinations (12,600).

`Arda::capacityWithSuffix(int $suffixLength = 3): int`

Returns the total number of unique combinations with a hex suffix.

Parameter	Type	Default	Description
`$suffixLength`	`int`	`3`	Length of hex suffix (0-4).

Returns: int - Total unique combinations. Returns same as capacity() when $suffixLength is 0.

Throws: InvalidArgumentException if $suffixLength is not between 0 and 4.

Word Lists

The generator includes 90 adjectives and 140 nouns from Tolkien's Legendarium:

Adjectives: precious, elvish, mithril, hobbitish, dwarven, entish, rohirric, gondorian, starlit, moonlit, shadowy, ancient, forgotten, blessed, cursed, hidden, wandering, faithful, valiant...

Nouns:

Characters: frodo, gandalf, aragorn, legolas, gimli, gollum, bilbo, arwen, galadriel, elrond, saruman, sauron...
Creatures: hobbit, balrog, nazgul, ent, orc, eagle, shelob, smaug, warg, dragon...
Places: shire, mordor, gondor, rohan, rivendell, lothlorien, moria, isengard, mirkwood, erebor...
Objects: ring, palantir, silmaril, sting, anduril, phial, lembas, pipeweed...
Concepts: fellowship, quest, journey, adventure, doom, hope, shadow, flame...

Development

This project uses DevContainers for development.

Getting Started

Clone the repository
Open in VS Code (or any DevContainer-compatible editor)
Reopen in Container when prompted
Dependencies will be installed automatically

Commands

# Run tests
composer test

# Check code style
composer lint:check

# Fix code style
composer lint

# Run static analysis
composer analyse

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

wllcdev / arda-tokens

Maintainers

Package info

Statistics

Security