{"id":26044305,"url":"https://github.com/brann-meius/laravel-flag-forge","last_synced_at":"2026-02-21T03:31:03.734Z","repository":{"id":281025693,"uuid":"942518666","full_name":"brann-meius/laravel-flag-forge","owner":"brann-meius","description":"Lightweight wrapper for the meius/flag-forge library, seamlessly integrating bitwise enumeration and flag management into your Laravel applications.","archived":false,"fork":false,"pushed_at":"2025-04-22T15:47:11.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-01T21:24:37.282Z","etag":null,"topics":["bitwise","bitwise-operations","configuration","efficiency","enumeration","enums","flags","laravel","performance","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brann-meius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"buy_me_a_coffee":"bohdanmeiuv"}},"created_at":"2025-03-04T08:24:47.000Z","updated_at":"2025-07-08T10:24:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"4504ccf2-2a9f-4f8d-82ac-7d20a6886343","html_url":"https://github.com/brann-meius/laravel-flag-forge","commit_stats":null,"previous_names":["brann-meius/laravel-flag-forge"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/brann-meius/laravel-flag-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Flaravel-flag-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Flaravel-flag-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Flaravel-flag-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Flaravel-flag-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brann-meius","download_url":"https://codeload.github.com/brann-meius/laravel-flag-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Flaravel-flag-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29672704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T03:11:15.450Z","status":"ssl_error","status_checked_at":"2026-02-21T03:10:34.920Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bitwise","bitwise-operations","configuration","efficiency","enumeration","enums","flags","laravel","performance","php"],"created_at":"2025-03-07T18:17:39.541Z","updated_at":"2026-02-21T03:31:03.716Z","avatar_url":"https://github.com/brann-meius.png","language":"PHP","funding_links":["https://buymeacoffee.com/bohdanmeiuv"],"categories":[],"sub_categories":[],"readme":"# Laravel Flag Forge Package\n\n[![License](https://img.shields.io/github/license/brann-meius/laravel-flag-forge)](LICENSE)\n[![codecov](https://codecov.io/gh/brann-meius/laravel-flag-forge/graph/badge.svg?token=Y5NC43U6ZE)](https://codecov.io/gh/brann-meius/laravel-flag-forge)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/1a96ee301b6943969d5da4b0ed8e99d4)](https://app.codacy.com/gh/brann-meius/laravel-flag-forge/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![PHP Version](https://img.shields.io/badge/php-\u003e=8.2-blue)](https://www.php.net/)\n[![Laravel Version](https://img.shields.io/badge/laravel-\u003e=11.0-red)](https://laravel.com/)\n\n\u003e **Recommendation:** Prior to integrating this wrapper into your application, please review the documentation for the\n\u003e underlying library [\u003cins\u003e`meius/flag-forge`\u003c/ins\u003e](https://github.com/brann-meius/flag-forge) to fully grasp its\n\u003e foundational concepts and operations.\n\nLaravel Flag Forge is a refined and sophisticated extension that effortlessly bridges the gap between the powerful\nbitwise flag management capabilities of the core library and the expressive nature of Laravel applications. This package\nenhances your project with:\n\n- Seamless Eloquent attribute casting,\n- A fluent API for bitwise operations,\n- Additional expressive query methods,\n- An Artisan command to generate bitwise enum classes,\n- And a convenient facade for rapid access to flag operations.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [1. Creating Bitwise Enums](#1-creating-bitwise-enums)\n  - [2. Working with Eloquent (Attribute Casting)](#2-working-with-eloquent-attribute-casting)\n  - [3. Mastering Bitwise Operations](#3-mastering-bitwise-operations)\n  - [4. Using the Facade](#4-using-the-facade)\n  - [5. Leveraging Database Query Methods](#5-leveraging-database-query-methods)\n  - [6. Integrating with Authorization Policies](#6-integrating-with-authorization-policies)\n- [Support](#support)\n- [License](#license)\n\n---\n\n## Features\n\n- **Expressive Bitwise Operations:**  \n  Enjoy a comprehensive suite of methods such as `add`, `remove`, `combine`, and `toggle` for\n  managing flags in a clear and fluent manner.\n\n- **Elegant Flag Verification:**  \n  Utilize the `has` and `doesntHave` methods to effortlessly determine whether a specific flag is active.\n\n- **Database Integration:**  \n  Store flags in numeric fields and retrieve them with automatic conversion to a fully featured `FlagManager`\n  instance.\n\n- **Eloquent Attribute Casting:**  \n  With the `AsMask` cast, numeric bitmask values in your models are instantly transformed into elegant\n  `FlagManager` objects.\n\n- **Enhanced Query Methods:**  \n  Filter records using expressive methods such as `whereHasFlag`, `whereDoesntHaveFlag`,\n  `whereAllFlagsSet`, and `whereAnyFlagSet` for sophisticated query building.\n\n- **Artisan Command:**  \n  Generate new bitwise enum classes effortlessly with `php artisan make:bit-enum`.\n\n- **Convenient Facade:**  \n  Access and chain flag operations using the provided `Flag` facade for rapid prototyping and production-ready\n  code.\n\n---\n\n## Requirements\n\n- **PHP:** \u003e= 8.2\n- **Laravel:** \u003e= 11.0\n\n---\n\n## Getting Started\n\nTo get started with the `meius/laravel-flag-forge` package, follow the installation instructions below and check out the\nusage examples.\n\n---\n\n## Installation\n\n1. **Composer Installation:**  \n   Install the package using Composer:\n\n   ```bash\n   composer require meius/laravel-flag-forge\n   ```\n\n2. **Register the Service Provider:**  \n   Manually register the service provider by adding it to your `bootstrap/providers.php` file:\n\n   ```php\n   return [\n       // Other service providers...\n       Meius\\LaravelFlagForge\\Providers\\FlagForgeServiceProvider::class,\n   ];\n   ```\n\n---\n\n## Usage\n\n### 1. Creating Bitwise Enums\n\nGenerate a new bitwise enum class using Laravel's Artisan command. For instance, to create an enum for user permissions:\n\n```bash\n  php artisan make:bit-enum {name}\n```\n\nThis command scaffolds a template class where you can define a series of bitwise flags such as `SendMessages`,\n`DeleteMessages`, `AddUsers`, etc. Customize this file to reflect the specific needs of your application.\n\n---\n\n### 2. Working with Eloquent (Attribute Casting)\n\nHarness the power of Laravel's Eloquent by converting numeric bitmask fields into expressive `FlagManager`\ninstances. Consider the following pivot model example:\n\n```php\nnamespace App\\Models;\n\nuse App\\Enums\\Permission; // Your bitwise enum must implement Bitwiseable\nuse Illuminate\\Database\\Eloquent\\Concerns\\HasUuids;\nuse Illuminate\\Database\\Eloquent\\Relations\\Pivot;\nuse Meius\\LaravelFlagForge\\Casts\\AsMask;\n\n/**\n * ChatUser Model\n *\n * This eloquent model demonstrates seamless integration of bitwise flag management.\n * The `permissions` attribute is automatically cast to a `FlagManager` instance,\n * allowing for sophisticated flag operations within your domain logic.\n *\n * @property string $id\n * @property string $chat_id\n * @property string $user_id\n * @property int $permissions\n */\nclass ChatUser extends Pivot\n{\n    use HasUuids;\n        \n    protected $fillable = ['permissions'];\n    \n    protected function casts(): array\n    {\n        return [\n            // `AsMask` converts numeric bitmask values into a `FlagManager` instance.\n            // Append the fully qualified bitwise enum class after the colon.\n            'permissions' =\u003e AsMask::class . ':' . Permission::class,\n        ];\n    }\n}\n```\n\n**Example of Eloquent Operations:**\n\n```php\n// Retrieve a ChatUser instance\n$chatUser = ChatUser::query()-\u003efirst();\n\n// Verify if the user has the permission to send messages\nif ($chatUser-\u003epermissions-\u003ehas(Permission::SendMessages)) {\n    echo \"User is allowed to send messages.\";\n}\n\n// Add the DeleteMessages flag to the user's permissions\n$chatUser-\u003epermissions-\u003eadd(Permission::DeleteMessages);\n\n// Remove a flag if necessary\n$chatUser-\u003epermissions-\u003eremove(Permission::SendMessages);\n```\n\n---\n\n### 3. Mastering Bitwise Operations\n\nThe `FlagManager` object provides a robust API to manage bitwise flags with ease. Below are detailed examples of\nkey methods:\n\n- **Adding Flags:**  \n  Append new flags to your configuration:\n  ```php\n  $flags = Flag::add(Permission::SendMessages);\n  $flags-\u003eadd(Permission::AddUsers);\n  ```\n\n- **Removing Flags:**  \n  Exclude specific flags:\n  ```php\n  $flags-\u003eremove(Permission::DeleteMessages);\n  ```\n\n- **Combining Flags:**  \n  Merge multiple flags simultaneously:\n  ```php\n  $flags = Flag::add(Permission::SendMessages)\n      -\u003ecombine(Permission::DeleteMessages, Permission::AddUsers);\n  ```\n\n- **Toggling Flags:**  \n  Switch a flag’s state between active and inactive:\n  ```php\n  $flags-\u003etoggle(Permission::PinMessages);\n  ```\n\n- **Flag Verification:**  \n  Check if a flag is set or unset:\n  ```php\n  if ($flags-\u003ehas(Permission::SendMessages)) {\n      // Execute logic when the flag is active\n  }\n  if ($flags-\u003edoesntHave(Permission::RemoveUsers)) {\n      // Execute alternative logic when the flag is not active\n  }\n  ```\n\nEach of these operations is designed to be chainable, promoting a fluent and natural coding style that enhances\nreadability and maintainability.\n\n---\n\n### 4. Using the Facade\n\nThe `Flag` facade grants immediate access to flag management operations. It supports chaining methods for building\ncomplex configurations:\n\n```php\nuse App\\Enums\\Permission;\nuse Meius\\LaravelFlagForge\\Facades\\Flag;\n\n// Create a comprehensive flag manager instance with multiple permissions\n$flagManager = Flag::add(Permission::SendMessages)\n    -\u003ecombine(Permission::DeleteMessages, Permission::AddUsers)\n    -\u003etoggle(Permission::PinMessages);\n\n// Alternatively, initialize a flag manager with a single permission for a quick check\n$singleFlag = Flag::add(Permission::DeleteMessages);\n```\n\nThis elegant facade simplifies the process of flag manipulation, allowing you to write succinct, expressive code.\n\n---\n\n### 5. Leveraging Database Query Methods\n\nLaravel Flag Forge enriches your querying capabilities by providing additional methods that allow filtering based on\nbitwise flags.\n\n- **Filtering Records with Specific Flags:**\n\n  ```php\n  use App\\Enums\\Permission;\n  use App\\Models\\ChatUser;\n\n  // Retrieve all users who have the SendMessages permission set\n  $users = ChatUser::query()\n    -\u003ewhereHasFlag('permissions', Permission::SendMessages)\n    -\u003eget();\n  ```\n\n- **Excluding Records Missing Certain Flags:**\n\n  ```php\n  // Retrieve users who do not have the RemoveUsers flag\n  $users = ChatUser::query()\n      -\u003ewhereDoesntHaveFlag('permissions', Permission::RemoveUsers)\n      -\u003eget();\n  ```\n\n- **Combining Conditions with Expressive Methods:**\n\n  ```php\n  use Meius\\LaravelFlagForge\\Facades\\Flag;\n\n  // Retrieve users who have either the combination of SendMessages and AddUsers or the composite flag built dynamically\n  $users = ChatUser::query()\n    -\u003ewhereAllFlagsSet('permissions', [Permission::SendMessages, Permission::AddUsers])\n    -\u003eorWhereAllFlagsSet('permissions', Flag::add(Permission::DeleteMessages)\n    -\u003ecombine(Permission::PinMessages))\n    -\u003eget();\n  ```\n\n- **Retrieving Records with Any of Multiple Flags Set:**\n\n  ```php\n  // Retrieve users who have at least one flag among RemoveUsers or PinMessages set\n  $users = ChatUser::query()\n    -\u003ewhereAnyFlagSet('permissions', Flag::add(Permission::RemoveUsers)-\u003eadd(Permission::PinMessages))\n    -\u003eget();\n  ```\n\nThese query methods empower you to create finely tuned database queries, ensuring that your application logic remains\nboth robust and highly expressive.\n\n---\n\n### 6. Integrating with Authorization Policies\n\nSeamlessly integrate bitwise flag management into Laravel’s authorization system. For example, consider a policy\ngoverning chat interactions. You can employ flag checks directly within policy methods to enforce nuanced permissions:\n\n```php\nnamespace App\\Policies;\n\nuse App\\Models\\User;\nuse App\\Models\\Chat;\nuse App\\Enums\\Permission;\n\nclass ChatPolicy\n{\n    /**\n     * Determine whether the user can send messages.\n     */\n    public function send(User $user, Chat $chat): bool\n    {\n        return $user-\u003echats()\n            -\u003ewhere('id', '=', $chat-\u003eid)\n            -\u003ewhereHasFlag('permissions', Permission::SendMessages)\n            -\u003eexists();\n    }\n\n    /**\n     * Determine whether the user can moderate the chat.\n     */\n    public function update(User $user, Chat $chat): bool\n    {\n        return $user-\u003echats()\n            -\u003ewhere('id', '=', $chat-\u003eid)\n            -\u003ewhereHasFlag('permissions', Permission::ManageChat)\n            -\u003eexists();\n    }\n    \n    /**\n    * Determine whether the auth user can exclude the user from the chat.\n    */\n    public function exclude(User $auth, Chat $chat, User $user): bool\n    {\n        return $auth-\u003eid === $user-\u003eid || $auth-\u003echats()\n            -\u003ewhere('id', '=', $chat-\u003eid)\n            -\u003ewhereHasFlag('permissions', Permission::RemoveUsers)\n            -\u003eexists();\n    }\n}\n```\n\nThis integration ensures that your authorization logic remains expressive and perfectly aligned with the dynamic nature\nof bitwise permissions.\n\n---\n\n## Support\n\nFor support, please open an issue on the [GitHub repository](https://github.com/brann-meius/laravel-flag-forge/issues).\n\n### Contributing\n\nWe welcome contributions to the `meius/laravel-flag-forge` library. To contribute, follow these steps:\n\n1. **Fork the Repository**: Fork the repository on GitHub and clone it to your local machine.\n2. **Create a Branch**: Create a new branch for your feature or bugfix.\n3. **Write Tests**: Write tests to cover your changes.\n4. **Run Tests**: Ensure all tests pass by running `phpunit`.\n5. **Submit a Pull Request**: Submit a pull request with a clear description of your changes.\n\nFor more details, refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n---\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%2Fbrann-meius%2Flaravel-flag-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrann-meius%2Flaravel-flag-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrann-meius%2Flaravel-flag-forge/lists"}