Bitmask Development with Transistor

When to Use This Skill

Activate when:

• Creating or modifying bitmask flag enums
• Setting up models with bitmask columns
• Writing queries that filter by bitmask flags
• Adding validation for bitmask inputs
• Using bitmask conditionals in Blade templates

Creating Bitmask Flag Enums

Use php artisan make:bitmask-flags to generate enums interactively. The command will prompt for flag names.

Flags use bit-shifted values:

• Flag 1: 1 << 0 (1)
• Flag 2: 1 << 1 (2)
• Flag 3: 1 << 2 (4)
• Flag 4: 1 << 3 (8)

Example enum:

enum Permission: int
{
    case Read = 1 << 0;    // 1
    case Write = 1 << 1;   // 2
    case Delete = 1 << 2;  // 4
    case Admin = 1 << 3;   // 8
}

Model Configuration

Add the trait and cast to your model:

use Gksh\Transistor\Casts\BitmaskCast;
use Gksh\Transistor\Concerns\HasBitmaskScopes;

class User extends Model
{
    use HasBitmaskScopes;

    protected function casts(): array
    {
        return [
            'permissions' => BitmaskCast::class,
            // Or specify size: BitmaskCast::class.':tiny'
        ];
    }
}

Cast size options: tiny, small, medium, or default (32-bit).

Migration Examples

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->bitmask('permissions');        // 32-bit unsigned integer, default 0
    $table->tinyBitmask('settings');       // 8-bit (up to 8 flags)
    $table->smallBitmask('preferences');   // 16-bit (up to 16 flags)
    $table->mediumBitmask('features');     // 24-bit (up to 24 flags)
});

Query Scope Examples

Filter records by bitmask flags:

// Has a specific flag
User::whereHasBitmaskFlag('permissions', Permission::Admin)->get();

// Has ALL specified flags
User::whereHasAllBitmaskFlags('permissions', [Permission::Read, Permission::Write])->get();

// Has ANY of the specified flags
User::whereHasAnyBitmaskFlag('permissions', [Permission::Admin, Permission::Delete])->get();

// Does NOT have a specific flag
User::whereDoesntHaveBitmaskFlag('permissions', Permission::Admin)->get();

// Does NOT have ANY of the specified flags
User::whereDoesntHaveAnyBitmaskFlag('permissions', [Permission::Admin, Permission::Delete])->get();

Validation Examples

In a Form Request:

use Gksh\Transistor\Rules\ValidBitmask;

public function rules(): array
{
    return [
        // Basic validation (any non-negative integer)
        'permissions' => ['required', new ValidBitmask],

        // With enum constraint (validates against max possible value)
        'permissions' => ['required', new ValidBitmask(Permission::class)],

        // Using inline rule syntax
        'permissions' => ['required', 'bitmask:'.Permission::class],
    ];
}

Blade Directive Examples

Check flags in Blade templates:

@hasBitmaskFlag($user->permissions, Permission::Admin)
    <p>User is an admin</p>
@endhasBitmaskFlag

@hasAnyBitmaskFlag($user->permissions, [Permission::Read, Permission::Write])
    <p>User can read or write</p>
@endhasAnyBitmaskFlag

@hasAllBitmaskFlags($user->permissions, [Permission::Read, Permission::Write])
    <p>User can read AND write</p>
@endhasAllBitmaskFlags

Inspecting Bitmask Values

Use the inspect command to visualize flags:

# Show all flags for an enum
php artisan bitmask:inspect Permission

# Analyze a specific value
php artisan bitmask:inspect Permission 7

This displays a table with case names, decimal values, and binary representation with colored bits.

Working with Bitmask Objects

The cast returns a Gksh\Bitmask\Bitmask object:

$user = User::find(1);

// Check if a flag is set
$user->permissions->has(Permission::Admin);

// Get the integer value
$user->permissions->value();