{"id":29184298,"url":"https://github.com/cmandersen/bitwise","last_synced_at":"2025-07-01T21:30:39.215Z","repository":{"id":299032224,"uuid":"1000341727","full_name":"cmandersen/bitwise","owner":"cmandersen","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-14T08:32:56.000Z","size":75,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-14T09:01:48.234Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmandersen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T16:19:41.000Z","updated_at":"2025-06-14T08:35:39.000Z","dependencies_parsed_at":"2025-06-14T09:01:53.832Z","dependency_job_id":"a3f4e6a5-516e-4928-976d-ff3aa0479602","html_url":"https://github.com/cmandersen/bitwise","commit_stats":null,"previous_names":["cmandersen/bitwise"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cmandersen/bitwise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmandersen%2Fbitwise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmandersen%2Fbitwise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmandersen%2Fbitwise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmandersen%2Fbitwise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmandersen","download_url":"https://codeload.github.com/cmandersen/bitwise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmandersen%2Fbitwise/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263038752,"owners_count":23404054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-01T21:30:37.573Z","updated_at":"2025-07-01T21:30:38.682Z","avatar_url":"https://github.com/cmandersen.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel Bitwise Package\n\nA Laravel package that makes it easy to work with bitwise flags in Eloquent models. Store multiple boolean flags efficiently in a single integer database column with natural query syntax.\n\n## Requirements\n\n- PHP 8.0 or higher\n- Laravel 9.x, 10.x, 11.x, or 12.x\n\n## Installation\n\nInstall the package via Composer:\n\n```bash\ncomposer require cmandersen/bitwise\n```\n\nThe package will automatically register itself via Laravel's package discovery.\n\n## Setup Your Database\n\nCreate your database column as an unsigned integer:\n\n```php\n// In your migration\nSchema::create('users', function (Blueprint $table) {\n    $table-\u003eid();\n    $table-\u003estring('name');\n    $table-\u003eunsignedInteger('permissions')-\u003edefault(0);\n    $table-\u003eunsignedInteger('features')-\u003edefault(0);\n    $table-\u003etimestamps();\n});\n```\n\n## Cast Your Model Attributes\n\nAdd bitwise casting to your Eloquent model attributes:\n\n```php\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Cmandersen\\Bitwise\\AsBitwise;\n\nclass User extends Model\n{\n    protected function casts(): array\n    {\n        return [\n            // Method 1: Auto-generate flags from names\n            'permissions' =\u003e AsBitwise::auto(['read', 'write', 'delete', 'admin']),\n            \n            // Method 2: Define flags with explicit values\n            'features' =\u003e AsBitwise::flags(['notifications' =\u003e 1, 'dark_mode' =\u003e 2, 'beta' =\u003e 4]),\n            \n            // Method 3: Shorthand syntax\n            'roles' =\u003e 'bitwise:user,moderator,admin',\n            'settings' =\u003e 'bitwise:email_notifications,push_notifications,sms_notifications',\n        ];\n    }\n}\n```\n\n## Working with Flags\n\nOnce cast, your attribute becomes a `BitwiseCollection` with many helpful methods:\n\n```php\n$user = User::find(1);\n\n// Check if flags are set\nif ($user-\u003epermissions-\u003ehas('read')) {\n    // User has read permission\n}\n\nif ($user-\u003epermissions-\u003ehas('read', 'write')) {\n    // User has both read AND write permissions\n}\n\nif ($user-\u003epermissions-\u003ehasAny('read', 'admin')) {\n    // User has read OR admin permissions (or both)\n}\n\n// Add flags\n$user-\u003epermissions = $user-\u003epermissions-\u003eadd('write');\n$user-\u003epermissions = $user-\u003epermissions-\u003eadd('delete', 'admin');\n\n// Remove flags\n$user-\u003epermissions = $user-\u003epermissions-\u003eremove('delete');\n\n// Toggle flags\n$user-\u003epermissions = $user-\u003epermissions-\u003etoggle('admin');\n\n// Get only specific flags\n$readWrite = $user-\u003epermissions-\u003eonly('read', 'write');\n\n// Get all except specific flags\n$withoutAdmin = $user-\u003epermissions-\u003eexcept('admin');\n\n// Clear all flags\n$user-\u003epermissions = $user-\u003epermissions-\u003eclear();\n\n// Set all available flags\n$user-\u003epermissions = $user-\u003epermissions-\u003eall();\n\n// Save changes\n$user-\u003esave();\n```\n\n## Querying Models by Flags\n\nThe package automatically adds powerful query methods to all your models. No traits or additional setup required!\n\n### Basic Queries\n\n```php\n// Find users who have 'read' permission\n$readUsers = User::whereBitwise('permissions', 'read')-\u003eget();\n\n// Find users who have both 'read' AND 'write' permissions\n$readWriteUsers = User::whereBitwise('permissions', ['read', 'write'])-\u003eget();\n\n// Find users who have ANY of the specified permissions\n$moderatorUsers = User::whereHasAnyBitwise('permissions', ['write', 'delete'])-\u003eget();\n\n// Find users who DON'T have admin permissions\n$regularUsers = User::whereDoesntHaveBitwise('permissions', 'admin')-\u003eget();\n\n// Find users with EXACTLY the 'read' permission (no other permissions)\n$readOnlyUsers = User::whereBitwiseEquals('permissions', 'read')-\u003eget();\n```\n\n### Combining with Other Conditions\n\n```php\n// Multiple flag combinations\n$multiplePermissions = User::whereInBitwise('permissions', ['read', 'admin'])-\u003eget();\n$mixedValues = User::whereInBitwise('permissions', [\n    'read',              // Single permission\n    ['read', 'write'],   // Multiple permissions (has both)\n])-\u003eget();\n\n// Exclude specific permissions\n$excludePermissions = User::whereNotInBitwise('permissions', ['admin', 'delete'])-\u003eget();\n\n// OR conditions\n$readOrWrite = User::whereBitwise('permissions', 'read')\n    -\u003eorWhereBitwise('permissions', 'write')\n    -\u003eget();\n\n// Complex queries with other conditions\n$complexQuery = User::where('name', 'like', '%admin%')\n    -\u003ewhereHasBitwise('permissions', 'admin')\n    -\u003ewhereDoesntHaveBitwise('features', 'beta')\n    -\u003eorderBy('created_at', 'desc')\n    -\u003eget();\n```\n\n### Complete Query Reference\n\nAll methods support OR variations (prefix with `or`):\n\n- `whereBitwise($column, $flags)` - Has specified flags\n- `whereHasBitwise($column, $flags)` - Alias for whereBitwise\n- `whereHasAnyBitwise($column, $flags)` - Has any of the flags\n- `whereDoesntHaveBitwise($column, $flags)` - Doesn't have flags\n- `whereBitwiseEquals($column, $flags)` - Has exactly these flags\n- `whereInBitwise($column, $values)` - Bitwise equivalent of whereIn\n- `whereNotInBitwise($column, $values)` - Bitwise equivalent of whereNotIn\n\n## Array-like Access\n\n`BitwiseCollection` implements `ArrayAccess`, so you can use array syntax:\n\n```php\n// Check if flag is set (read-only)\nif ($user-\u003epermissions['read']) {\n    // User has read permission\n}\n\n// Note: Direct assignment is not allowed - use add()/remove() methods instead\n// $user-\u003epermissions['read'] = true; // This will throw an exception\n```\n\n## Setting Flags During Creation/Update\n\nYou can set flags in several ways:\n\n```php\n// Using array of flag names\nUser::create([\n    'name' =\u003e 'John Doe',\n    'permissions' =\u003e ['read', 'write'],\n]);\n\n// Using a BitwiseCollection\n$permissions = (new BitwiseCollection(0, ['read' =\u003e 1, 'write' =\u003e 2]))\n    -\u003eadd('read', 'write');\n    \nUser::create([\n    'name' =\u003e 'Jane Doe',\n    'permissions' =\u003e $permissions,\n]);\n\n// Using direct integer value (if you know the bit values)\nUser::create([\n    'name' =\u003e 'Admin User',\n    'permissions' =\u003e 15, // 1 + 2 + 4 + 8 = all flags\n]);\n```\n\n## Advanced Usage\n\nFor more advanced use cases, you can work with individual flags and utilities:\n\n### Manual Flag Generation\n\n```php\nuse Cmandersen\\Bitwise\\Bitwise;\n\n// Auto-generate flags from names\n$flags = Bitwise::generateFlags(['read', 'write', 'delete', 'admin']);\n// Results in: ['read' =\u003e 1, 'write' =\u003e 2, 'delete' =\u003e 4, 'admin' =\u003e 8]\n\n// Generate from associative array with mixed values\n$flags = Bitwise::generateFromAssoc([\n    'read' =\u003e null,      // Auto-assigned: 1\n    'write' =\u003e 16,       // Manual value: 16\n    'delete' =\u003e null,    // Auto-assigned: 32 (next available)\n    'admin' =\u003e true,     // Auto-assigned: 64\n]);\n```\n\n### Working with Individual Flags\n\n```php\nuse Cmandersen\\Bitwise\\BitwiseFlag;\n\n$readFlag = new BitwiseFlag('read', 1);\n$writeFlag = new BitwiseFlag('write', 2);\n\n// Check flag properties\necho $readFlag-\u003ename;    // 'read'\necho $readFlag-\u003evalue;   // 1\necho $readFlag;          // 'read' (string conversion)\n\n// Flag operations\n$readFlag-\u003eisSetIn(5);           // true (5 = 1 + 4, so read flag is set)\n$readFlag-\u003esetBit(4);            // 5 (4 | 1 = 5)\n$readFlag-\u003eunsetBit(5);          // 4 (5 \u0026 ~1 = 4)\n$readFlag-\u003etoggleBit(4);         // 5 (4 ^ 1 = 5)\n\n// Combine flags\n$combined = $readFlag-\u003ecombine($writeFlag); // 3 (1 | 2 = 3)\n```\n\n## Methods Reference\n\n### BitwiseCollection Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `has(...$flags)` | Check if all specified flags are set | `bool` |\n| `hasAny(...$flags)` | Check if any specified flags are set | `bool` |\n| `add(...$flags)` | Add flags (returns new instance) | `BitwiseCollection` |\n| `remove(...$flags)` | Remove flags (returns new instance) | `BitwiseCollection` |\n| `toggle(...$flags)` | Toggle flags (returns new instance) | `BitwiseCollection` |\n| `only(...$flags)` | Keep only specified flags | `BitwiseCollection` |\n| `except(...$flags)` | Remove specified flags (alias for remove) | `BitwiseCollection` |\n| `clear()` | Remove all flags | `BitwiseCollection` |\n| `all()` | Set all available flags | `BitwiseCollection` |\n| `getValue()` | Get integer value | `int` |\n| `getFlags()` | Get array of BitwiseFlag objects | `array` |\n| `getFlagNames()` | Get array of active flag names | `array` |\n| `isEmpty()` | Check if no flags are set | `bool` |\n| `isNotEmpty()` | Check if any flags are set | `bool` |\n| `toArray()` | Get array of active flag names | `array` |\n| `count()` | Count active flags | `int` |\n\n### BitwiseFlag Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `is($flag)` | Check if this flag matches another | `bool` |\n| `hasValue($value)` | Check if flag has specific value | `bool` |\n| `isPowerOfTwo()` | Check if value is power of 2 | `bool` |\n| `combine(...$flags)` | Combine with other flags | `int` |\n| `isSetIn($value)` | Check if flag is set in value | `bool` |\n| `setBit($value)` | Set this flag in value | `int` |\n| `unsetBit($value)` | Unset this flag in value | `int` |\n| `toggleBit($value)` | Toggle this flag in value | `int` |\n\n## License\n\nThis package is open-sourced software licensed under the [MIT license](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmandersen%2Fbitwise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmandersen%2Fbitwise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmandersen%2Fbitwise/lists"}