https://github.com/sqids/sqids-perl

Official Perl port of Sqids. Generate short unique IDs from numbers.
https://github.com/sqids/sqids-perl

hashids id id-generator perl perl5 short-id short-url sqids uid unique-id unique-id-generator

Last synced: about 1 month ago
JSON representation

Official Perl port of Sqids. Generate short unique IDs from numbers.

• Host: GitHub
• URL: https://github.com/sqids/sqids-perl
• Owner: sqids
• License: mit
• Created: 2023-06-24T15:29:56.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-06T22:10:11.000Z (7 months ago)
• Last Synced: 2024-09-29T18:41:49.424Z (about 2 months ago)
• Topics: hashids, id, id-generator, perl, perl5, short-id, short-url, sqids, uid, unique-id, unique-id-generator
• Language: Perl
• Homepage: https://sqids.org/perl
• Size: 20.5 KB
• Stars: 9
• Watchers: 3
• Forks: 4
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

        
[![Actions Status](https://github.com/sqids/sqids-perl/actions/workflows/test.yml/badge.svg)](https://github.com/sqids/sqids-perl/actions)

# 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](https://sqids.org/perl) (_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](https://sqids.org/)

## 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](https://metacpan.org/pod/Class%3A%3ATiny)):

    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](https://sqids.org)

# LICENSE

Copyright (C) Matthew Somerville. MIT.

# AUTHOR

Matthew Somerville