feat: Laravel integration for gksh/bitmask

[karkowg]

The package provides:

• A BitmaskCast for Eloquent models to seamlessly cast integer values to and from Bitmask objects.
• Eloquent scopes (HasBitmaskScopes) for querying bitmask columns with various conditions (has flag, has all flags, has any flag, etc.).
• A make:bitmask-flags Artisan command to generate bitmask enum classes.
• A ValidBitmask validation rule to ensure input values conform to bitmask constraints, optionally tied to an enum.
• Blade directives for conditional rendering based on bitmask flags.
• Custom Blueprint macros for defining bitmask columns in migrations.
• Comprehensive unit tests covering all functionalities.

Greptile Summary

This PR introduces a comprehensive Laravel integration for the gksh/bitmask package, providing Eloquent casting, query scopes, validation rules, Blade directives, and migration helpers for working with bitmask flags. The implementation is well-structured with proper type safety, comprehensive test coverage across all features, and good documentation.

Key Changes:

• Eloquent Cast (BitmaskCast): Converts database integers to/from Bitmask objects with configurable sizes (tiny/small/medium/default)
• Query Scopes (HasBitmaskScopes): Five scope methods for filtering models by bitmask flags using bitwise SQL operations
• Validation (ValidBitmask): Rule for validating bitmask values with optional enum-based maximum value checking
• Artisan Commands: make:bitmask-flags for interactive enum generation and bitmask:inspect for debugging bitmask values
• Blueprint Macros: Migration helpers for creating properly sized unsigned integer columns with default values
• Blade Directives: @hasBitmaskFlag, @hasAnyBitmaskFlag, and @hasAllBitmaskFlags for conditional rendering
• CI/CD: GitHub Actions workflow testing PHP 8.2-8.4 with Laravel 11-12, running Pint, PHPStan, and Pest

Previous Issues Addressed:

• laravel/prompts dependency correctly moved from require-dev to require in composer.json

Remaining Concern:

• SQL injection concern in HasBitmaskScopes.php previously flagged but not yet resolved - column names are interpolated directly into raw SQL without sanitization, though this is mitigated by typical usage patterns where column names are hardcoded

Confidence Score: 4/5

• This PR is largely safe to merge with well-tested features and proper Laravel integration patterns.
• Score reflects high code quality, comprehensive test coverage (67 test cases across BitmaskCast, HasBitmaskScopes, ValidBitmask, and InspectBitmask), proper type safety with PHPStan, and good documentation. One point deducted due to the unresolved SQL injection concern in HasBitmaskScopes where column names are interpolated into raw SQL without sanitization, though risk is low given typical usage patterns with hardcoded column names.
• src/Concerns/HasBitmaskScopes.php should be reviewed for the SQL injection concern with column name interpolation in whereRaw() calls.

Important Files Changed

Filename	Overview
src/Concerns/HasBitmaskScopes.php	Eloquent scopes for bitmask queries using bitwise operations. Previous reviews flagged SQL injection concerns with column name interpolation.
src/Casts/BitmaskCast.php	Clean Eloquent cast implementation converting integers to Bitmask objects with proper size handling and null safety.
src/Rules/ValidBitmask.php	Validation rule with proper checks for non-negative integers and optional enum-based max value validation.
src/Commands/MakeBitmaskFlagsCommand.php	Interactive enum generator using Laravel Prompts with proper validation and PascalCase enforcement.
src/TransistorServiceProvider.php	Service provider registering commands, Blade directives, validation rules, and Blueprint macros for bitmask functionality.
composer.json	Package dependencies properly configured with laravel/prompts moved to require section.

Sequence Diagram

sequenceDiagram
    participant User
    participant Model
    participant BitmaskCast
    participant Bitmask
    participant HasBitmaskScopes
    participant Database

    Note over User,Database: Setting Bitmask Flags
    User->>Model: permissions = bitmask.set(Permission::Read)
    Model->>BitmaskCast: set(Bitmask)
    BitmaskCast->>BitmaskCast: Extract integer value
    BitmaskCast-->>Model: Returns int
    Model->>Database: Store integer value

    Note over User,Database: Retrieving Bitmask Flags
    User->>Model: Get user->permissions
    Model->>Database: Fetch integer value
    Database-->>Model: Returns int
    Model->>BitmaskCast: get(int value)
    BitmaskCast->>Bitmask: Create Bitmask instance
    Bitmask-->>BitmaskCast: Returns Bitmask
    BitmaskCast-->>Model: Returns Bitmask
    Model-->>User: Returns Bitmask object

    Note over User,Database: Querying with Scopes
    User->>Model: whereHasBitmaskFlag('permissions', Permission::Admin)
    Model->>HasBitmaskScopes: Apply scope
    HasBitmaskScopes->>Database: WHERE permissions & ? = ?
    Database-->>HasBitmaskScopes: Filtered results
    HasBitmaskScopes-->>Model: Query builder
    Model-->>User: Collection of models

Loading

[karkowg]

@greptile

[greptile-apps]

_{7 files reviewed, 6 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}