hash_ids initial commit

LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ivan Akimov
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,117 @@
+
+# hash-ids
+
+A tiny class to generate YouTube-like hashes from one or many ids.
+
+## Contents
+
+* **README.md** - documentation and examples
+* **LICENSE**
+* **lib/**
+	* **hash_ids.php** - main `hash_ids` class for PHP 5.4 and higher
+	* **hash_ids.php-5-3.php** - `hash_ids` class for PHP 5.3 (using regular array notation)
+
+## What's it for?
+
+Generating **unique hashes** is beneficial when you do not want to expose your database ids in the URL. It's even more helpful when you do not have to look up in the database what record belongs to what hash.
+
+Instead of storing these hashes in the database and selecting by them, you could encode primary ids and select by those - which is faster. Providing a unique `salt` value to the constructor will make your hashes unique also.
+
+Hashes look similar to what YouTube, Bitly, and other popular websites have: `p9`, `pZsCB`, `qKuBQuxc`. They are case-sensitive, include alphanumeric characters and a dash.
+
+## What's different?
+
+With this class you could encode several ids into one hash. If you have several objects to keep track of, you could use for example `user_id`, `univesity_id` and `class_id` -- passing *all three ids* at the same time and getting back *one hash*.
+
+There is no limit to how many ids you can encode into one hash. The more ids you provide and the bigger the numbers, the longer your hash will be.
+
+## Sample Usage
+
+### Encoding:
+
+To encode a single number:
+
+	require_once('lib/hash_ids.php');
+	$hash_ids = new hash_ids('this is my salt');
+
+	$hash = $hash_ids->encode(12345);
+
+`$hash` is now going to be:
+
+	8dL
+
+To encode multiple numbers into one hash:
+
+	require_once('lib/hash_ids.php');
+	$hash_ids = new hash_ids('this is my salt');
+
+	$hash = $hash_ids->encode(683, 94108, 123, 5);
+
+`$hash` is now going to be:
+
+	eWS8M81rhic
+
+
+### Decoding:
+
+Hash decoding is done using the same salt value:
+
+	require_once('lib/hash_ids.php');
+	$hash_ids = new hash_ids('this is my salt');
+
+	$first_hash = $hash_ids->decode('8dL');
+	var_dump($first_hash);
+
+	$second_hash = $hash_ids->decode('eWS8M81rhic');
+	var_dump($second_hash);
+
+Output will be:
+
+	array(1) {
+		[0]=>
+		int(12345)
+	}
+	array(4) {
+		[0]=>
+		int(683)
+		[1]=>
+		int(94108)
+		[2]=>
+		int(123)
+		[3]=>
+		int(5)
+	}
+
+## Security
+
+The primary purpose of this hash function is to make ids look different. It's not meant or tested to be used primarily as a security algorithm.
+
+Having said that, this class does try to make these hashes un-guessable and unique.
+
+Let's for example look at the following code:
+
+	require_once('lib/hash_ids.php');
+	$hash_ids = new hash_ids('this is my salt');
+
+	$hash = $hash_ids->encode(5, 5, 5, 5);
+
+`$hash` will be:
+
+	hu8fhU8
+
+You don't see any repeating patterns that might show there's 4 identical numbers in the hash.
+
+Same with incremented numbers:
+
+	require_once('lib/hash_ids.php');
+	$hash_ids = new hash_ids('this is my salt');
+
+	$hash = $hash_ids->encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
+
+`$hash` will be :
+
+	7f41mUmf2U816fbiqip
+
+## Bonus
+
+Since these hashes are most likely to be used in user-visible places, like the url, created hashes will not include basic curse words by design, like the f-bomb or "#2".

lib/hash-ids.php

@@ -0,0 +1,158 @@
+<?php
+
+	// hash-ids 0.1.0
+	// (c) 2012 Ivan Akimov
+	// hash-ids may be freely distributed under the MIT license.
+
+	class hash_ids {
+
+		private $salt;
+		private $alphabet = '-23456789abcdeghjklmnopqrtvwxyzABCDEGHJKLMNOPQRTVWXYZ';
+		private $separators = 'fF10uUsSiI';
+
+		function __construct($salt = '') {
+
+			$this->salt = $salt;
+			$this->alphabet_length = strlen($this->alphabet);
+
+			if (strlen($this->salt))
+				$this->alphabet = $this->_shuffle($this->alphabet, $this->salt);
+
+		}
+
+		function encode() {
+			return call_user_func_array([$this, '_encode'], func_get_args());
+		}
+
+		function decode($hash) {
+			return $this->_decode($hash);
+		}
+
+		private function _encode() {
+
+			$ret = '';
+			$alphabet = $this->alphabet;
+
+			$args = func_get_args();
+			foreach ($args as $i => $arg) {
+
+				if ($i) {
+					$params = array_slice($args, 0, $i);
+					$ret .= call_user_func_array([$this, '_get_separator'], $params);
+				}
+
+				$hash = $this->_hash($arg, $alphabet);
+				$ret .= $hash;
+
+				$alphabet = $this->_shuffle($alphabet, $this->salt . $hash);
+
+			}
+
+			return $ret;
+
+		}
+
+		private function _decode($hash) {
+
+			$ret = [];
+			$alphabet = $this->alphabet;
+
+			$hash = trim($hash);
+			if ($hash) {
+
+				$separator_array = str_split($this->separators);
+				$hash_spaces = str_replace($separator_array, ' ', $hash);
+				$hash_array = explode(' ', $hash_spaces);
+
+				foreach ($hash_array as $i => $sub_hash) {
+
+					$id = $this->_unhash($sub_hash, $alphabet);
+					$ret[] = $id;
+
+					if ($i + 1 < sizeof($hash_array))
+						$alphabet = $this->_shuffle($alphabet, $this->salt . $sub_hash);
+
+				}
+
+			}
+
+			$validate = call_user_func_array([$this, 'encode'], $ret);
+			if ($validate != $hash)
+				$ret = [];
+
+			return $ret;
+
+		}
+
+		private function _shuffle($alphabet, $salt) {
+
+			$ret = '';
+			$alphabet_array = str_split($this->alphabet);
+			$sorting_array = str_split(md5($salt));
+
+			$i = 0;
+			while ($alphabet_array) {
+
+				$alphabet_size = sizeof($alphabet_array);
+				$pos = hexdec($sorting_array[$i]);
+
+				if ($pos >= $alphabet_size)
+					$pos = ($alphabet_size - 1) % $pos;
+
+				$ret .= $alphabet_array[$pos];
+				unset($alphabet_array[$pos]);
+				$alphabet_array = array_merge($alphabet_array);
+
+				$i++;
+				$i %= sizeof($sorting_array);
+
+			}
+
+			return $ret;
+
+		}
+
+		private function _hash($input, $alphabet) {
+
+			$ret = '';
+			$alphabet_length = strlen($alphabet);
+
+			do {
+				$rem = $input % $alphabet_length;
+				$ret = $alphabet[$rem] . $ret;
+			} while ((int)$input = $input / $alphabet_length);
+
+			return $ret;
+
+		}
+
+		private function _unhash($input, $alphabet) {
+
+			$ret = 0;
+			$alphabet_length = strlen($alphabet);
+			$input_chars = str_split($input);
+
+			foreach ($input_chars as $i => $char) {
+				$pos = strpos($alphabet, $char);
+				$ret += $pos * pow($alphabet_length, (strlen($input) - $i - 1));
+			}
+
+			return $ret;
+
+		}
+
+		private function _get_separator() {
+
+			$args = func_get_args();
+			$sum = $this->alphabet_length;
+
+			foreach ($args as $arg)
+				$sum += $arg;
+
+			$i = $sum % (strlen($this->separators) - 1);
+			return $this->separators[$i];
+
+		}
+
+	}
+