PHPackages                             mordilion/huffman-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mordilion/huffman-php

ActiveLibrary[Utility & Helpers](/categories/utility)

mordilion/huffman-php
=====================

PHP-Library for using the Huffman-Algorithm in PHP

v3.1.0(3mo ago)325.8k↓68.8%2MITPHPPHP >=8.1CI passing

Since Oct 30Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/mordilion/HuffmanPHP)[ Packagist](https://packagist.org/packages/mordilion/huffman-php)[ RSS](/packages/mordilion-huffman-php/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (10)Dependencies (5)Versions (19)Used By (0)

HuffmanPHP
==========

[](#huffmanphp)

A PHP library for string compression using the Huffman coding algorithm with URL-safe base conversion.

[![CI](https://github.com/mordilion/HuffmanPHP/actions/workflows/ci.yml/badge.svg)](https://github.com/mordilion/HuffmanPHP/actions/workflows/ci.yml) [![PHP](https://camo.githubusercontent.com/854124dd57cfd3aad3184fca9760bf1f33a5ec1e5d080cfbe8aa4e3337ba46e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e302d3838393242462e737667)](https://php.net/) [![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE) [![Packagist](https://camo.githubusercontent.com/9be454d9265d021adb934a8dcfeceaa20c4cdec92c6b6c82c4d521b917837317/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f7264696c696f6e2f687566666d616e2d7068702e737667)](https://packagist.org/packages/mordilion/huffman-php)

Features
--------

[](#features)

- Huffman coding compression for strings
- Character-level and whole-word compression modes
- URL-safe output using configurable alphabets (Base10 to Base65)
- Automatic GMP/BCMath detection for base conversion
- Built-in result caching for repeated operations
- PHP 8.0+ with strict typing

Requirements
------------

[](#requirements)

- PHP >= 8.0
- One of these extensions for compressed output:
    - `gmp` (recommended, faster)
    - `bcmath` (fallback)

Installation
------------

[](#installation)

```
composer require mordilion/huffman-php
```

Usage
-----

[](#usage)

### Basic Encoding

[](#basic-encoding)

Character-level encoding compresses individual characters based on their frequency. The default output uses Base65 (URL-safe alphabet) when compression is enabled.

```
use Mordilion\HuffmanPHP\Dictionary;
use Mordilion\HuffmanPHP\Huffman;

// Build a dictionary from sample text
$text = 'This is a Text to compress with the Huffman-Algorithm'; // 53 chars

$dictionary = new Dictionary([$text]);
$huffman = new Huffman($dictionary);

// Encode to binary
$binary = $huffman->encode($text);
// => '10000010101000011011010000110110010101110000101100010111001111010100110001001010100100001100100101100110011011000010010011001010111100101101101100000100000000011000111001001011111111110111011110010001101000100010011001011001' (289 chars)

// Encode with compression (URL-safe Base65, default)
$compressed = $huffman->encode($text, true);
// => '3QGgsnulxJqC2QweIz-V6SWj~pYoqYfA005HCR' (38 chars from 53)

// Decode
$decoded = $huffman->decode($binary);           // original text
$decoded = $huffman->decode($compressed, true);  // original text
```

### Custom Alphabets

[](#custom-alphabets)

Use different character sets to encode compressed output. Smaller alphabets produce longer output but may be more suitable for restricted character sets.

```
$huffman = new Huffman($dictionary, Huffman::ALPHABET_BASE26_LOWER);

$compressed = $huffman->encode($text, true);
// => 'mtxhycztntclyrustzsjioonyevmiijcdwrxqflkwsymxtsb' (48 chars)

$decoded = $huffman->decode($compressed, true); // original text
```

### Whole-Word Mode

[](#whole-word-mode)

Treat each input array element as an atomic token instead of breaking it into individual characters. This produces superior compression when the input has repeating words or phrases.

```
$text = 'A Text with multiple Text Segments, to demonstrate the compression with multiple Text Segments'; // 94 chars

// Split into words and add space as a separate token
$tokens = array_merge(array_unique(explode(' ', $text)), [' ']);

$dictionary = new Dictionary($tokens, Dictionary::MAX_LENGTH_WHOLE_WORDS);
$huffman = new Huffman($dictionary);

$compressed = $huffman->encode($text, true);
// => '27thCP8gJKOciDUU' (16 chars from 94)

$decoded = $huffman->decode($compressed, true); // original text
```

API Reference
-------------

[](#api-reference)

### Dictionary

[](#dictionary)

**`__construct(array $values, int $maxLength = 1)`**

Builds a Huffman dictionary from sample values.

- `$values` — Array of strings to learn character/word frequencies from
- `$maxLength` — Maximum substring length to consider. `1` = single characters (default), `Dictionary::MAX_LENGTH_WHOLE_WORDS` (0) = treat each value as a whole word

Throws `InvalidArgumentException` if `$maxLength` is negative.

**`getBinary(string $key): ?string`**

Returns the binary Huffman code for a given key, or `null` if not found.

**`getValue(string $binary): string|int|false`**

Reverse lookup: returns the original key for a binary code, or `false` if not found.

**`getMaxLength(): int`**

Returns the `maxLength` used during construction.

**`setValues(array $values): void`**

Replaces the dictionary mappings. Useful for serializing/deserializing dictionaries.

### Huffman

[](#huffman)

**`__construct(Dictionary $dictionary, string $compressAlphabet = Huffman::ALPHABET_BASE65)`**

Creates an encoder/decoder instance.

- `$dictionary` — The Huffman dictionary to use
- `$compressAlphabet` — Alphabet for compressed output (default: URL-safe Base65)

**`encode(string $decoded, bool $compress = false): string`**

Encodes a string using the Huffman dictionary.

- `$compress = false` — Returns raw binary string
- `$compress = true` — Returns base-converted string using the configured alphabet

Throws `RuntimeException` if:

- The input contains characters not in the dictionary
- Compression is enabled but neither GMP nor BCMath is available

**`decode(string $encoded, bool $compressed = false): string`**

Decodes a previously encoded string. The `$compressed` flag must match the `$compress` flag used during encoding.

Throws `RuntimeException` if the binary code is not recognized in the dictionary.

Alphabet Constants
------------------

[](#alphabet-constants)

Alphabets are used to convert the binary Huffman codes into text. Larger alphabets produce shorter output for the same binary data.

ConstantCharactersSize`ALPHABET_BASE10``0-9`10`ALPHABET_BASE16``0-9A-F`16`ALPHABET_BASE16_LOWER``0-9a-f`16`ALPHABET_BASE26``A-Z`26`ALPHABET_BASE26_LOWER``a-z`26`ALPHABET_BASE36``0-9A-Z`36`ALPHABET_BASE36_LOWER``0-9a-z`36`ALPHABET_BASE62``0-9A-Za-z`62`ALPHABET_BASE65``0-9A-Za-z-_~`65**Note:** Larger alphabets produce shorter output. Base65 is the default and uses only URL-safe characters (digits, letters, hyphen, underscore, tilde).

Error Handling
--------------

[](#error-handling)

- `InvalidArgumentException` — Thrown by `Dictionary` when `$maxLength` is negative
- `RuntimeException` — Thrown by `Huffman::encode()` when the input contains characters not in the dictionary
- `RuntimeException` — Thrown by `Huffman::encode()/decode()` with `$compress = true` when neither GMP nor BCMath is available

Testing
-------

[](#testing)

```
composer install
vendor/bin/phpunit
vendor/bin/psalm
```

License
-------

[](#license)

MIT — see [LICENSE](LICENSE) for details.

###  Health Score

53

—

FairBetter than 96% of packages

Maintenance81

Actively maintained with recent releases

Popularity31

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~131 days

Recently: every ~360 days

Total

16

Last Release

100d ago

Major Versions

v1.1.5 → v2.0.02022-02-17

v2.0.6 → v3.0.02026-03-25

PHP version history (3 changes)v1.0.0PHP ^7.3

v1.1.5PHP >=7.1 || >=8.0

v3.0.0PHP >=8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/548671?v=4)[Henning Huncke](/maintainers/mordilion)[@mordilion](https://github.com/mordilion)

---

Top Contributors

[![mordilion](https://avatars.githubusercontent.com/u/548671?v=4)](https://github.com/mordilion "mordilion (32 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mordilion-huffman-php/health.svg)

```
[![Health](https://phpackages.com/badges/mordilion-huffman-php/health.svg)](https://phpackages.com/packages/mordilion-huffman-php)
```

###  Alternatives

[tenancy/tenancy

Creating multi tenant saas from your Laravel app with ease

1.3k46.2k](/packages/tenancy-tenancy)[citation-style-language/locales

Citation Style Language (CSL) Locales

169836.8k24](/packages/citation-style-language-locales)[wpbp/widgets-helper

A class to ease creating powered Widgets on WordPress

1215.1k](/packages/wpbp-widgets-helper)[safran-cassiopee/php-taf-decoder

TAF weather forecast decoder

1212.1k](/packages/safran-cassiopee-php-taf-decoder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)