axetools/bitflagtrait

A PHP trait to enable bitwise comparison of flags

v2.0.1 2024-10-03 16:27 UTC

Requires

• php: ^7.1 || ^8.0

Requires (Dev)

• phpstan/phpstan: *
• phpunit/phpunit: *

MIT

• Ryan W Howe

• class
• classes
• trait
• flag
• flags
• comparison
• operation
• bitwise
• operations
• comparisons

README

This is a php class trait that will provide methods for performing simple bitwise operations.

This project uses Semantic Versioning.

Bitwise operators allow for manipulation and examination of specific bits within an integer.

The BitFlagTrait gives simple methods for setting, getting and toggling the status of bits withing a reference integer.

This can be used for storage of the state of multiple flags or utilizing flags for class settings

Installation

The preferred method of installation is via Composer. Run the following command to install the package and add it as a requirement to your project's composer.json:

composer require axetools/bitflagtrait

Usage

The BitFlagTrait can be used with any class and will expose several protected methods that can be utilized to perform bitwise checks to a reference integer.

Example:

<?php
class ShippingStatus {
    use AxeTools\Traits\BitFlag\BitFlagTrait;

    const FLAG_RECEIVED = 0b00001; // int value 1
    const FLAG_QUEUED   = 0b00010; // int value 2
    const FLAG_SHIPPED  = 0b00100; // int value 4

    private $status = 0;

    public function __construct($status){
        $this->status = $status;
    }
    
    public function hasShipped(){
        return self::hasFlag($this->status, self::FLAG_SHIPPED);
    }
}

$orderStatus = new ShippingStatus(ShippingStatus::FLAG_RECEIVED | ShippingStatus::FLAG_QUEUED);
var_dump($orderStatus->hasShipped()); // false

$orderStatus = new ShippingStatus(3);
var_dump($orderStatus->hasShipped()); // false

$orderStatus = new ShippingStatus(7);
var_dump($orderStatus->hasShipped()); // true

hasFlag()

The self::hasFlag() static method to determine the current boolean value of a specific flag in the flagSet integer.

Description

self::hasFlag(int $flagSet, int $flag): bool

Parameters

flagSet

The integer that contains the current flag status.

flag

The flag to check the status of.

Return Value

bool : the status of the flag contained in the flag status.

setFlag()

The self::setFlag() static method to set the current boolean value of a specific flag in the flagSet integer.

Description

self::setFlag(int &$flagSet, int $flag, bool $value): void

Parameters

flagSet

The integer that contains the current flag status. Passed by reference and will result in the updated integer

flag

The flag to set the value of.

value

The boolean value to set the flag position in the flag status integer.

Return Value

void

toggleFlag()

The self::toggleFlag() static method to toggle the current boolean value of a specific flag in the flagSet integer to it's opposite.

Description

self::toggleFlag(int &$flagSet, int $flag): void

Parameters

flagSet

The integer that contains the current flag status. Passed by reference and will result in the updated integer

flag

The flag to set the value of.

Return Value

void

Notice:

Be aware of the storage medium and data types available to the class you use the trait with. PHP is still deployed on some 32-bit systems. SQL small and medium integers have limited number of flags available due to the max size. Signed and unsigned SQL integers have different amount of flags available.