Hash Compat Laravel Package

Getting Started

indigophp/hash-compat is a tiny polyfill package: it backports PHP 5.6’s hash_equals() (and related hash_* helpers where missing) to older PHP runtimes by registering global functions through Composer’s autoload.files mechanism.

Minimal steps:

1. Install it only in a legacy application that still runs on PHP < 5.6:

   composer require indigophp/hash-compat
   

2. Confirm the polyfill is being loaded by Composer. Inspect vendor/composer/autoload_files.php — you should see an entry pointing at the package’s bootstrap file.
3. Verify at runtime:

   var_dump(function_exists('hash_equals')); // true on PHP 5.3+ once loaded
   

4. First use case: replace timing-unsafe string comparison in token/MAC/password checks:

   // before
   if ($providedToken === $expectedToken) { ... }
   
   // after
   if (hash_equals($expectedToken, $providedToken)) { ... }
   

Where to look first:

• composer.json — the autoload.files entry is the whole integration surface.
• The src/ bootstrap file — it wraps each function definition in if (!function_exists(...)), so it is inert on modern PHP.
• Your framework’s bootstrap — this package has no service provider, facade, or config; it is a global-function shim only.

Because the package is archived (last release 2015), treat “getting started” as “deciding whether you still need it.” On PHP 5.6+ it is dead weight; on PHP 5.3–5.5 it is a legitimate small dependency.

Implementation Patterns

Timing-safe comparisons behind a compatibility boundary. In a legacy codebase targeting multiple PHP versions, centralize sensitive comparisons in one helper so the dependency is swappable:

final class SecureCompare
{
    public static function equals($known, $user)
    {
        return hash_equals($known, $user);
    }
}

This keeps call sites clean and makes it trivial to drop the polyfill once the minimum PHP version is bumped.

Composer-only integration. There is nothing to register. Add the requirement, run composer dump-autoload, and the functions exist. No config publishing, no provider, no middleware.

Framework usage (Laravel). Laravel 5.1 still supported PHP 5.5.9, where hash_equals() is not native. If your app or a dependency calls hash_equals() (e.g., MAC verification in encryption/token flows), this package is a valid stopgap. Prefer it over hand-rolled == comparisons.

Conditional loading in a monorepo. If only some services need legacy support, keep the dependency in the specific legacy package’s composer.json rather than the root, so modern services never load the file.

Test matrix pattern. Add PHP 5.4/5.5 and PHP 7.x to CI. The polyfill guards on function_exists, so the same code path should pass on both. Assert hash_equals behavior (equal strings, differing lengths, non-string inputs) rather than the polyfill’s internals.

Migration pattern. When you finally raise the PHP floor to 5.6+, remove the package — the native function wins automatically because the polyfill never defines itself. This makes removal safe in either order: pull the dependency, or leave it until a cleanup pass.

Gotchas and Tips

• Archived and unmaintained. No security patches, no PHP 8 compatibility work. Do not introduce it into new projects; PHP 8.1+ even deprecates passing non-string arguments to string functions, so type discipline matters more now than when this was written.
• Duplicate polyfills. Other packages (e.g., Symfony polyfills) also define hash_equals conditionally. The function_exists guard usually prevents fatal redeclaration errors, but load order matters: whichever bootstrap runs first wins. If behavior differs, inspect autoload_files.php ordering.
• Invisible on modern PHP. Because the functions already exist, the polyfill silently no-ops on PHP 5.6+. This masks whether the dependency is actually doing anything — a good reason to remove it during upgrades rather than carry it forever.
• No namespacing. These are global functions. You cannot alias, mock, or autoload them lazily in the usual PSR-4 sense; they are side effects of requiring the package.
• Argument semantics. hash_equals($known, $user) is not symmetric in intent — always pass the trusted value first and the user-supplied value second, and both must be strings. Passing null or arrays will misbehave or error.
• Debugging checklist. If hash_equals is “missing”: run composer dump-autoload, confirm autoload.files contains the package, and check for a custom autoloader bypassing Composer.
• Not a general hashing library. It does not provide password hashing, KDFs, or algorithms. Pair it with password_hash/password_verify (or a dedicated polyfill for those) rather than assuming it covers crypto needs.
• Extension points: effectively none. There is no configuration, no interface to implement, and no events. The only “extension point” is your own wrapper helper around the global functions.
• Dependency hygiene. Given the low star count and archival status, audit its bootstrap file before shipping — it is small enough to read end-to-end in a minute, which is the safest thing you can do with an abandoned polyfill.

Bottom line: a pragmatic one-line backport for hash_equals() in PHP 5.3–5.5 era apps. On any modern Laravel project it should be treated as removable legacy baggage, not a day-to-day tool.