README

BitMask

Lightweight PHP library for working with bitmask values with support for PHP enums.

• Zero dependencies
• PHP ≥ 8.1
• Enum-friendly
• Strict validation (single-bit guarantees)

Installation

composer require yaroslavche/bitmask

Why BitMask?

Classic bitmask operations are simple but quickly become error-prone and hard to read:

$mask &= ~EXECUTE;
$mask |= READ | WRITE;

BitMask provides a small, explicit API and optional enum-based safety without hiding how bitmasks actually work.

Basic Usage

use BitMask\BitMask;

define('READ', 1 << 0);
define('WRITE', 1 << 1);
define('EXECUTE', 1 << 2);

$bitmask = new BitMask(READ | WRITE);

$bitmask->set(EXECUTE);
$bitmask->remove(WRITE);

if ($bitmask->has(READ)) {
// ...
}

echo $bitmask->get(); // 5

EnumBitMask (recommended)

Work with bitmasks using PHP enums.

Unit enums (auto-mapped)

use BitMask\EnumBitMask;

enum Permissions
{
    case READ;
    case WRITE;
    case EXECUTE;
}

$mask = new EnumBitMask(Permissions::class);

$mask->set(Permissions::READ);
$mask->set(Permissions::EXECUTE);

$mask->has(Permissions::WRITE); // false
$mask->get(); // 5

Enum cases are mapped automatically based on their position: READ → 1, WRITE → 2, EXECUTE → 4.

Int-backed enums

enum Flags: int
{
    case User  = 1;   // 0b0001
    case Admin = 8;   // 0b1000
}

$mask = new EnumBitMask(Flags::class, Flags::User | Flags::Admin);
$mask->get(); // 9

Each enum value must represent a single bit. Otherwise, an InvalidEnumException will be thrown.

Factory Methods

EnumBitMask::create(Permissions::class, Permissions::READ, Permissions::EXECUTE);
EnumBitMask::all(Permissions::class);
EnumBitMask::none(Permissions::class);
EnumBitMask::without(Permissions::class, Permissions::EXECUTE);

Bits Helper

Low-level static helpers for working with integer bitmasks.

use BitMask\Util\Bits;

Bits::getMostSignificantBit(7); // 2
Bits::getSetBitsIndexes(7);     // [0, 1, 2]
Bits::getSetBits(7);            // [1, 2, 4]
Bits::toString(7);              // "111"
Bits::isSingleBit(8);           // true

Contributing

Development and contribution guidelines are described in CONTRIBUTING.md

License

This project is licensed under the MIT License - see the LICENSE file for details