Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jenssegers/optimus

🤖 Id obfuscation based on Knuth's multiplicative hashing method for PHP.
https://github.com/jenssegers/optimus

hashids ids laravel obfuscation optimus transformations

Last synced: about 2 months ago
JSON representation

🤖 Id obfuscation based on Knuth's multiplicative hashing method for PHP.

Lists

README 

        
# Optimus id transformation



[![Packagist](https://badgen.net/packagist/v/jenssegers/optimus)](https://packagist.org/packages/jenssegers/optimus)

[![Downloads](https://badgen.net/packagist/dt/jenssegers/optimus)](https://packagist.org/packages/jenssegers/optimus/stats)

[![Build](https://github.com/jenssegers/optimus/workflows/tests/badge.svg)](https://github.com/jenssegers/optimus/actions) 

[![Coverage](http://img.shields.io/coveralls/jenssegers/optimus.svg)](https://coveralls.io/r/jenssegers/optimus?branch=master)



With this library, you can transform your internal id's to obfuscated integers based on Knuth's integer hash. It is similar to Hashids, but will generate integers instead of random strings. It is also super fast.










## Installation



Install using composer:



```bash

composer require jenssegers/optimus

```



If you will be running your code on a 32 bit system or will be working with large prime numbers it is suggested that you install the [GMP extension](http://php.net/manual/en/book.gmp.php). 

For debian/ubuntu you can install the extension with one of these commands:



```bash

apt-get install php7.4-gmp

apt-get install php8.0-gmp

apt-get install php8.1-gmp

```



## Usage



To get started you will need 3 things;



 - Large prime number lower than `2147483647`

 - The inverse prime so that `(PRIME * INVERSE) & MAXID == 1`

 - A large random integer lower than `2147483647`



Luckily for you, I have included a console command that can do all of this for you. To get started, just run the following command:



```bash

> php vendor/bin/optimus spark



Prime: 2123809381

Inverse: 1885413229

Random: 146808189

```



If you prefer to choose your own prime number (from [this list](http://primes.utm.edu/lists/small/millions/) for example), you can pass it to the command to calculate the remaining numbers:



```bash

> php vendor/bin/optimus spark 1580030173



Prime: 1580030173

Inverse: 59260789

Random: 1163945558

```



Using those numbers, you can start creating instances of `Optimus($prime, $inverted, $random)`:



```php

use Jenssegers\Optimus\Optimus;



new Optimus(1580030173, 59260789, 1163945558);

```



**NOTE**: Make sure that you are using the same constructor values throughout your entire application!



## Encoding and decoding



To encode id's, use the `encode` method:



```php

$encoded = $optimus->encode(20); // 1535832388

```



To decode the resulting `1535832388` back to its original value, use the `decode` method:



```php

$original = $optimus->decode(1535832388); // 20

```



## Framework Integrations



### Laravel



This is an example service provider which registers a shared Optimus instance for your entire application:



```php

app->singleton(Optimus::class, function ($app) {

            return new Optimus(1580030173, 59260789, 1163945558);

        });

    }

}

```



Once you have created the service provider, add it to the providers array in your `config/app.php` configuration file:



```

App\Providers\OptimusServiceProvider::class,

```



Laravel's automatic injection will pass this instance where needed. Example controller:



```php

decode($id);

    }

}

```



More information: https://laravel.com/docs/5.3/container#resolving



**Third-party integrations**



* An integration with Laravel is provided by the [propaganistas/laravel-fakeid](https://packagist.org/packages/propaganistas/laravel-fakeid) package.

* Laravel Optimus with multiple connections provided by the [cybercog/laravel-optimus](https://github.com/cybercog/laravel-optimus) package.

* An integration with Silex 2 is provided by the [jaam/silex-optimus-provider](https://packagist.org/packages/jaam/silex-optimus-provider) package.

* An integration with Laravel is provided by the [elfsundae/laravel-hashid](https://github.com/ElfSundae/laravel-hashid) package.

* A PSR-15 middleware provided by the [icanhazstring/optimus-middleware](https://github.com/icanhazstring/optimus-middleware) package.



## Security contact information



To report a security vulnerability, follow [these steps](https://tidelift.com/security).



## License



The [MIT](https://opensource.org/licenses/MIT) License.