PHP Bitmask implementation derived from myclabs/php-enum

Why?

First, and mainly, myclabs/php-enum is restricted and can't be composited (Enum::FOO() | Enum::BAR() doesn't work too well).

Using a Bitmask instead of an integer provides the following advantages:

• You can type-hint: function setAction(Bitmask $action) {;
• You can enrich the Bitmask with methods (e.g. format, parse, …);
• You can extend the Bitmask to add new values (make your enum final to prevent it);
• You can get a list of all the possible values (see below);
• A Bitmask can many enums in a single value.

This Bitmask class is not intended to replace enums, but only to be used when it makes sense.

Installation

composer require cruxinator/php-bitmask

Declaration

use Cruxinator\BitMask\BitMask ;

class UserStatus extends BitMask
{

const Registered = 1; // BIT #1 of $flags has the value 1

const Active = 2; // BIT #2 of $flags has the value 2

const Member = 4; // BIT #3 of $flags has the value 4

const Admin = 8; // BIT #4 of $flags has the value 8

}

Usage

$status = UserStatus::Registered();

// or with a dynamic key:
$status = UserStatus::$key();
// or with a dynamic value:
$status = new UserStatus($value);

// values can then be checked
if ($status->isActive()){
// ...
}

// individuals flags can later toggled ON
$status->setActive(true);
// or off
$status->setActive(false);

As you can see, methods are automatically implemented to provide quick access to a Bitmask value.

One advantage over using class constants is to be able to type-hint Bitmap values:

function setStatus(UserStatus $action) {
    // ...
}

Documentation

• __construct() The constructor checks that the value can be composed from the enum;
• __toString() You can echo $myValue, it will display the bitmask value (in an array style format of Boolean)
• getValue() Returns the current value of the Bitmask
• getKey() Returns a key arrat of the current composite parts of the Bitmask
• equals() Tests whether Bitmask instances are equal (returns true if enum values are equal, false otherwise)

Static methods:

• toArray() Returns all possible values as an array (constant name in key, constant value in value)
• keys() Returns the names (keys) of all constants in the Enum class
• values() Returns instances of the Enum class of all Enum constants (constant name in key, Enum instance in value)
• isValid() Check if tested value is valid on enum set
• isValidKey() Check if tested key is valid on enum set
• search() Return key for searched value

dynamic methods

class UserStatus extends BitMask
{
    private const Registered = 1;
    private const Active = 2;
}

// Static method:
$status = UserStatus::Registered();
$status = UserStatus::Active();

// instance methods
$status->isRegistered();
$status->isActive();
$status->setRegistered($bool);
$status->setActive($bool);

Static method helpers are implemented using __callStatic() and __call().

If you care about IDE autocompletion, you can either implement the static methods yourself:

class UserStatus extends BitMask
{
    private const Registered = 1;

    /**
     * @return UserStatus
     */
    public static function Registered() {
        return new UserStatus(self::Registered);
    }
    /**
     * @return bool
     */
    public function isRegistered(){
        return $this->isFlagSet(self::Registered);
    }
    /**
     * @param bool $flag
     * @return self
     */
    public function setRegistered(bool $flag){
        return $this->setFlag(self::Registered, $flag);
    }
}

Or you can use phpdoc (this is supported in PhpStorm for example):

/**
 * @method static UserStatus Registered()
 * @method bool isRegistered()
 * @method UserStatus setRegistered(bool)
 */
class UserStatus extends Bitmask
{
    private const Registered = 1;
}

Related projects

• [myclabs/php-enum] (https://github.com/myclabs/php-enum)