Drop PHP 8.2, Deprecate floats, Add enums

Release Notes - v2.1.0

Added

• New enum-backed API:
  • BinaryEnumFlags
  • Traits\InteractsWithEnumFlags
  • Flag enum and Mask value object
• Enum-backed flags now return a Mask object from getMask().
• New getMaskValue(): int method for enum-backed flags to persist/interoperate with integer masks.
• Deprecation warnings for passing float values as masks/flags.
• README migration notice for the upcoming v3.0.0 integer-only API.
• UPGRADE-v3.md with migration instructions.
• New primary numeric trait: Traits\InteractsWithNumericFlags.
• Traits\BinaryFlags is now deprecated and kept for backward compatibility.

Deprecated

• Passing float to BinaryFlags mask/flag methods is deprecated in v2.1.0.
• Float support will be removed in v3.0.0.
• Bits::BIT_64 will be removed in v3.0.0.

BIT_64 Notice

Bits::BIT_64 is being removed because PHP numbers for bitwise flags are signed. The 64th bit is the sign bit, so it cannot be used reliably as a normal flag.

Using integer-compatible bits avoids these issues.

Migration Recommendation

Cast external/legacy mask and flag values to int before calling BinaryFlags methods.

$flags->setMask((int) $mask);
$flags->addFlag((int) $flag);

Enum Migration Example

// Before: numeric PermissionFlags
class PermissionFlags extends BinaryFlags
{
    public const CAN_VIEW = Bits::BIT_1;
    public const CAN_BOOK = Bits::BIT_2;
}

$flags = new PermissionFlags($storedMask);
$flags->addFlag(PermissionFlags::CAN_VIEW | PermissionFlags::CAN_BOOK);
$storedMask = $flags->getMask();

// After: enum-backed PermissionFlags
enum Permission: int
{
    case CanView = Bits::BIT_1;
    case CanBook = Bits::BIT_2;
}

class PermissionFlags extends BinaryEnumFlags
{
    protected static function getFlagEnumClass(): string
    {
        return Permission::class;
    }
}

$flags = new PermissionFlags(Mask::fromInt($storedMask, Permission::class));
$flags->addFlag(Permission::CanView);
$flags->addFlag(Permission::CanBook);
$storedMask = $flags->getMaskValue();