NAME

Sqids - generate short unique identifiers from numbers

SYNOPSIS

    use Sqids;
    my $sqids = Sqids->new;

    # encode/decode a single number
    my $id = $sqids->encode(123);         # 'UKk'
    my $num = $sqids->decode('UKk');      # 123

    # or a list or arrayref
    $id = $sqids->encode(1, 2, 3);        # '86Rf07'
    $id = $sqids->encode([1, 2, 3]);      # '86Rf07'
    my @nums = $sqids->decode('86Rf07');  # (1, 2, 3)

    # also get results in an arrayref
    my $nums = $sqids->decode('86Rf07');  # [1, 2, 3]

DESCRIPTION

Sqids (pronounced "squids") is a small library that lets you generate unique IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.

Features:

• Encode multiple numbers - generate short IDs from one or several non-negative numbers

• Quick decoding - easily decode IDs back into numbers

• Unique IDs - generate unique IDs by shuffling the alphabet once

• ID padding - provide minimum length to make IDs more uniform

• URL safe - auto-generated IDs do not contain common profanity

• Randomized output - Sequential input provides nonconsecutive IDs

• Many implementations - Support for 40+ programming languages

Use-cases

Good for:

• Generating IDs for public URLs (eg: link shortening)

• Generating IDs for internal systems (eg: event tracking)

• Decoding for quicker database lookups (eg: by primary keys)

Not good for:

• Sensitive data (this is not an encryption library)

• User IDs (can be decoded revealing user count)

Getting started

Install Sqids via:

    cpanm Sqids

METHODS

new

    my $sqids = Sqids->new();

Make a new Sqids object. This constructor accepts a few options, either as a hashref or a list (using Class::Tiny):

    my $sqids = Sqids->new(
        alphabet => 'abcdefg',
        min_length => 4,
        blocklist => ['word'],
    );

alphabet

You can randomize IDs by providing a custom alphabet:

    my $sqids = Sqids->new({
      alphabet => 'FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE',
    });
    my $id = $sqids->encode(1, 2, 3); # "B4aajs"
    my $numbers = $sqids->decode($id); # [1, 2, 3]

min_length

Enforce a minimum length for IDs:

    my $sqids = Sqids->new( min_length => 10 );
    my $id = $sqids->encode(1, 2, 3); # "86Rf07xd4z"
    my $numbers = $sqids->decode($id); # [1, 2, 3]

blocklist

Prevent specific words from appearing anywhere in the auto-generated IDs:

    my $sqids = Sqids->new( blocklist => ['86Rf07'] );
    my $id = $sqids->encode([1, 2, 3]); # "se8ojk"
    my $numbers = $sqids->decode($id); # [1, 2, 3]

encode

    my $id = $sqids->encode($n1, [$n2, ...]);

Encode a single number (or a list of numbers, or a single arrayref of numbers) into a string.

decode

    my @numbers = $sqids->decode($id);

Decode an id into its number (or numbers). Returns a list in list context, or a scalar (one number) or arrayref (multiple numbers) in scalar context.

Note: Because of the algorithm's design, multiple IDs can decode back into the same sequence of numbers. If it's important to your design that IDs are canonical, you have to manually re-encode decoded numbers and check that the generated ID matches.

SEE ALSO

Sqids

LICENSE

Copyright (C) Matthew Somerville. MIT.

AUTHOR

Matthew Somerville <matthew@mysociety.org>

cpanm Sqids

perl -MCPAN -e shell
install Sqids