README

该库接受一个字符串值，并从中生成整数哈希码。如果你想要从一个在调用中保持一致的值计算出一个“随机”整数，这个库非常有用。PHP可以访问大量的哈希函数，但它们的输出几乎总是字符串。这个库将这些哈希函数和一些额外的逻辑封装成了一个简单的面向对象接口。

安装

composer require mcordingley/hash-bin

快速开始

use mcordingley\HashBin\BinStrategies\Modulo;
use mcordingley\HashBin\HashBin;
use mcordingley\HashBin\Hashers\IntegerInterpreters\Unpack;
use mcordingley\HashBin\Hashers\Sip24;

// Use library defaults.
$hashBin = HashBin::make();

// Or use other options.
$hashBin = new HashBin(new Sip24($key, new Unpack), new Modulo);

// From 0 to 15, inclusive.
$first = $hashBin->bin('test', 15);

// From 5 to 15, inclusive.
$second = $hashBin->binRange('test', 5, 15);

API

使用开始于HashBin类。你可以通过new操作符或make静态工厂方法创建一个新的实例。make将为你提供一个配置，以适应大多数用例，除非有其他原因，否则你应该将其作为首选。默认值可能在未来的版本中发生变化，但这不会被视为破坏性更改，所以如果你依赖于在版本之间不更改bin输出，请通过构造函数方法显式设置你的配置。

除了上面描述的bin和binRange方法之外，HashBin还提供了setBase(string $base)方法来设置一个通用的基础值，以混合到后面的值中。这样做是为了让不同的HashBin实例提供不同的输出集。

HashBin构造函数接受两个参数，一个Hasher和一个BinStrategy。Hasher负责将提供的字符串转换为整数值。BinStrategy然后将该整数约束到指定的范围内。

整数解释器

整数解释器被一些哈希器用于将二进制字符串转换为整数。Unpack是唯一提供的解释器，其构造函数不接受任何参数。

哈希器

CRC32是默认的哈希器实现，使用CRC32哈希函数直接将字符串转换为整数。它非常快，但如果提供了用户生成的值，则无法保证没有冲突。它的构造函数不接受任何参数。这个哈希器应该是你的默认选择。

如果你需要一些针对潜在冲突的加密加固，请使用Sip24。这个哈希器需要libsodium存在，无论是通过PHP 7.2或更高版本还是通过安装sodium_compat库。它使用SipHash-2-4来计算其哈希值。SipHash是一个适用于短输入的键控哈希函数。它的构造函数需要一个长度为SODIUM_CRYPTO_SHORTHASH_KEYBYTES的密钥和一个整数解释器。密钥应该是一个在库使用之间持续存在的原始二进制字符串。理想情况下，密钥应该使用random_bytes方法生成：random_bytes(SODIUM_CRYPTO_SHORTHASH_KEYBYTES)。将密钥编码为十六进制（bin2hex）或基64（base64_encode），并在使用前将其解码。

Native封装了PHP中的hash函数，并允许使用该方法支持的任何哈希算法。由于此方法返回字符串而不是整数，因此还必须提供IntegerInterpreter来将二进制字符串转换为整数，因此构造函数签名如下：new Native('algo', new Unpack)。请注意，只使用输出中的足够位来构造整数，因此即使底层哈希函数具有防冲突性，输出的bin也不是。

分类策略

该库提供了两种分类策略：Multiply和Modulo。

乘法 是推荐实现，并在 HashBin::make() 中使用。它的构造函数接受一个单一的可选参数。默认值是推荐值，除非有特定原因，否则应使用此值。此实现提供了良好的综合特性。

取模 使用模运算符来限制整数的范围。它的缺点是它会使范围内的较低值相对于较高值略微偏重，但同时也提供了给定输入的相对可预测的输出值。