Download the PHP package fatkulnurk/radix-converter without Composer

Radix Converter PHP

A type-safe library to convert numbers into short strings and back. Perfect for URL shorteners, unique IDs, and compact representations.

Packagist

Table of Contents

• What Does This Do?
• Requirements
• Installation
• Quick Start
• Built-in Converters
  • Base62 Strategy
  • Alphanumeric Upper Strategy
  • Alphanumeric Lower Strategy
  • Alpha Only Strategy
  • Hex Strategy (Custom)
• Common Use Cases
  • URL Shortener
  • Different Converter Types
  • Error Handling
• Custom Converters
• For Laravel Users
• More Examples
• CI/CD
• License

What Does This Do?

This library converts numbers like 12345 into short strings like "3d7" and back. This is useful for:

• Creating short URLs (like bit.ly/3d7)
• Generating compact unique IDs
• Making numbers easier to read and share

Installation

Run this command in your terminal:

Requirements

• PHP 8.5 or higher

Quick Start

Here's the simplest way to use it:

Built-in Converters

The library comes with 5 built-in converters:

How Each Strategy Works

All converters extend AbstractBaseConverter which uses the radix (base-N) algorithm:

Encoding (number → string):

1. Divide the number by the base
2. Use the remainder to pick a character from the charset
3. Repeat with the quotient until it becomes 0
4. Read the result from last to first

Decoding (string → number):

1. Start with 0
2. For each character, multiply result by base and add the character's position value
3. Return the final number

1. Base62 Strategy (Most Compact)

• Charset: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ (62 chars)
• Base: 62
• Best for: URL shorteners, compact unique IDs

Example calculation for 12345:

• 12345 ÷ 62 = 199 remainder 7 → charset[7] = "7"
• 199 ÷ 62 = 3 remainder 13 → charset[13] = "d"
• 3 ÷ 62 = 0 remainder 3 → charset[3] = "3"
• Result: "3d7"

2. Alphanumeric Upper Strategy

• Charset: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ (36 chars)
• Base: 36
• Best for: Case-insensitive identifiers, easier to read

3. Alphanumeric Lower Strategy

• Charset: 0123456789abcdefghijklmnopqrstuvwxyz (36 chars)
• Base: 36
• Best for: Easy typing, lowercase-only systems

4. Alpha Only Strategy

• Charset: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ (52 chars)
• Base: 52
• Best for: When numbers must be excluded from identifiers

5. Hex Strategy (Custom)

• Charset: 0123456789abcdef (16 chars)
• Base: 16
• Best for: Standard hexadecimal conversion

Common Use Cases

1. URL Shortener

Convert database IDs into short codes for URLs:

2. Different Converter Types

3. Error Handling

The library will throw errors if you try to:

• Encode negative numbers
• Decode empty strings
• Decode invalid characters

Custom Converters

You can create your own converter for any base system.

Using the Built-in Hex Converter

Creating Your Own Converter

For Laravel Users

Laravel Octane / Swoole Warning

If you use Laravel Octane or Swoole, do NOT use CustomConverterRegistry because it keeps data between requests, which can cause problems.

Instead, use ConverterManager:

Using in Laravel Controllers

More Examples

The library includes example files you can run:

CI/CD

This project uses GitHub Actions for continuous integration. The workflow is configured in .github/workflows/ci.yml.

How It Works

The CI pipeline runs automatically on:

• Every push to main or master branches
• Every pull request targeting main or master branches

Workflow Steps

Running Tests Locally

Before pushing your changes, run tests locally:

Customizing the Workflow

To test on multiple PHP versions, edit .github/workflows/ci.yml:

License

MIT License - free to use in your projects.