{"id":26432313,"url":"https://github.com/brann-meius/flag-forge","last_synced_at":"2026-03-01T14:32:56.707Z","repository":{"id":279816158,"uuid":"939319815","full_name":"brann-meius/flag-forge","owner":"brann-meius","description":"High-performance PHP library for managing bitwise enumerations and flag operations—ideal for access control, configuration, and fast boolean state management.","archived":false,"fork":false,"pushed_at":"2025-03-12T12:37:53.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-17T06:58:03.214Z","etag":null,"topics":["bitwise","bitwise-operations","configuration","efficiency","enumeration","enums","flags","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-02-26T10:59:06.000Z","updated_at":"2025-03-12T12:36:27.000Z","dependencies_parsed_at":"2025-02-27T22:04:14.062Z","dependency_job_id":"34e9179b-6661-4964-81cd-9f6f203a103d","html_url":"https://github.com/brann-meius/flag-forge","commit_stats":null,"previous_names":["brann-meius/flag-forge"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/brann-meius/flag-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Fflag-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Fflag-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Fflag-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Fflag-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brann-meius","download_url":"https://codeload.github.com/brann-meius/flag-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brann-meius%2Fflag-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29970990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T14:11:48.712Z","status":"ssl_error","status_checked_at":"2026-03-01T14:11:48.352Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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","performance","php"],"created_at":"2025-03-18T06:18:00.353Z","updated_at":"2026-03-01T14:32:56.687Z","avatar_url":"https://github.com/brann-meius.png","language":"PHP","funding_links":["https://buymeacoffee.com/bohdanmeiuv"],"categories":[],"sub_categories":[],"readme":"# Flag Forge Package\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/brann-meius/flag-forge/ci.yml)](https://github.com/brann-meius/flag-forge/actions)\n[![codecov](https://codecov.io/gh/brann-meius/flag-forge/graph/badge.svg?token=0XH7AAKHS2)](https://codecov.io/gh/brann-meius/flag-forge)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/d6238aceb07d402f8742d4b0597a5ba7)](https://app.codacy.com/gh/brann-meius/flag-forge/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![License](https://img.shields.io/github/license/brann-meius/flag-forge)](LICENSE)\n[![PHP Version](https://img.shields.io/badge/php-%3E%3D%208.1-blue)](https://www.php.net/)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Working with FlagManager](#working-with-flagmanager)\n- [Database Integration Example](#database-integration-example)\n  - [Table Schema: chat_user](#table-schema-chat_user)\n  - [Sample Records](#sample-records)\n  - [Example Query: Checking a Specific Permission](#example-query-checking-a-specific-permission)\n  - [Example PHP Code Using PDO](#example-php-code-using-pdo)\n- [API Reference](#api-reference)\n- [Support](#support)\n- [License](#license)\n\n## Overview\n\nThe `meius/flag-forge` package provides an intuitive API for defining and managing bitwise enumerations in PHP. By\nassigning power-of-two values to each flag, the package allows you to combine multiple flags using bitwise operators and\nefficiently check individual flags using simple methods.\n\n## Requirements\n\n- PHP \u003e= 8.1\n\n## Getting Started\n\nTo get started with the `meius/flag-forge` package, follow the installation instructions below and check out the usage\nexamples.\n\n## Installation\n\n1. Install the package via Composer:\n    ```bash\n    composer require meius/flag-forge\n    ```\n\n## Usage\n\nBelow is an example enum and how to work with the FlagManager.\n\n```php\n enum Permission: int implements Bitwiseable \n {\n     case SendMessages = 1 \u003c\u003c 0; // 1\n     case DeleteMessages = 1 \u003c\u003c 1; // 2\n     case AddUsers = 1 \u003c\u003c 2; // 4\n     case RemoveUsers = 1 \u003c\u003c 3; // 8\n     case PinMessages = 1 \u003c\u003c 4; // 16\n     case ManageChat = 1 \u003c\u003c 5; // 32\n     case ManageModerators = 1 \u003c\u003c 6; // 64\n }\n ```\n\n### Working with FlagManager\n\n```php\n use Meius\\FlagForge\\FlagManager;\n\n $manager = new FlagManager();\n $manager-\u003egetMask(); // Initial mask: 0\n \n // ----------------------------------------------------------------------\n // ADD FLAGS\n // ----------------------------------------------------------------------\n $manager-\u003eadd(Permission::SendMessages) // - The bit corresponding to SendMessages is not set, so it gets added.\n     -\u003eadd(Permission::AddUsers) // - The bit for AddUsers is not set, so it is added.\n     -\u003eadd(Permission::AddUsers) // - Already set.\n     -\u003eadd(Permission::PinMessages) // - The bit for PinMessages is not set, so it is added.\n     -\u003egetMask(); // Expected mask: 21 (SendMessages=1, AddUsers=4, PinMessages=16: 1+4+16=21)\n \n \n // ----------------------------------------------------------------------\n // COMBINE FLAGS\n // ----------------------------------------------------------------------\n $manager-\u003ecombine(\n     Permission::SendMessages, // Already set.\n     Permission::DeleteMessages, // Not set; will be added.\n     Permission::AddUsers // Already set.\n )-\u003egetMask(); // Expected mask: 23 (SendMessages=1, DeleteMessages=2, AddUsers=4, PinMessages=16: 21+2=23)\n \n // ----------------------------------------------------------------------\n // REMOVE FLAGS\n // ----------------------------------------------------------------------\n $manager-\u003eremove(Permission::AddUsers) // - Remove AddUsers: bit is set, so it will be removed.\n     -\u003eremove(Permission::ManageModerators) // - Remove ManageModerators: bit is not set, so nothing changes.\n     -\u003egetMask(); // Expected mask: 19\n \n // ----------------------------------------------------------------------\n // TOGGLE FLAGS\n // ----------------------------------------------------------------------\n $manager-\u003etoggle(\n     Permission::SendMessages, // Bit is set; toggled off.\n     Permission::DeleteMessages, // Bit is set; toggled off.\n     Permission::AddUsers, // Bit is not set; toggled on.\n     Permission::RemoveUsers // Bit is not set; toggled on.\n )-\u003egetMask(); // Expected mask: 28\n\n // ----------------------------------------------------------------------\n // CHECK FLAGS\n // ----------------------------------------------------------------------\n $manager-\u003ehas(Permission::SendMessages); // false\n $manager-\u003ehas(Permission::AddUsers); // true\n $manager-\u003edoesntHave(Permission::SendMessages); // true\n $manager-\u003edoesntHave(Permission::AddUsers); // false\n \n // ----------------------------------------------------------------------\n // ITERATE OVER ACTIVE FLAGS\n // ----------------------------------------------------------------------\n foreach ($manager as $flag) {\n     /**\n      * Example output:\n      * Active flag: AddUsers (4)\n      * Active flag: RemoveUsers (8)\n      * Active flag: PinMessages (16)\n      */\n     echo \"Active flag: \" . $flag-\u003ename . \" (\" . $flag-\u003evalue . \")\" . PHP_EOL;\n }\n \n // ----------------------------------------------------------------------\n // CLEAR FLAGS\n // ----------------------------------------------------------------------\n $manager-\u003eclear(); // Expected mask: 0\n ```\n\n## Database Integration Example\n\nFlagForge can be easily integrated with a database. The following example demonstrates how to store and retrieve a flag\nmask using PDO.\n\n### Database Schema and Usage Example\n\nThe following section describes the `chat_user` table schema used to store user permissions as a bitmask,\nprovides a few sample records, and shows an example of how to query the database to check a specific permission.\n\n### Table Schema: chat_user\n\n| Column      | Data Type        | Constraints            | Description                            |\n|-------------|------------------|------------------------|----------------------------------------|\n| id          | UUID             | PRIMARY KEY            | Unique identifier for the record.      |\n| chat_id     | UUID             | FOREIGN KEY, NOT NULL  | Identifier of the chat.                |\n| user_id     | UUID             | FOREIGN KEY, NOT NULL  | Identifier of the user.                |\n| permissions | UNSIGNED TINYINT | NOT NULL, DEFAULT (17) | Bitmask representing user permissions. |\n\n### Sample Records\n\nBelow are a few example rows inserted into the `chat_user` table:\n\n| id                                   | chat_id   | user_id   | permissions |\n|--------------------------------------|-----------|-----------|-------------|\n| 11111111-1111-1111-1111-111111111111 | chat-1234 | user-1234 | 21          |\n| 22222222-2222-2222-2222-222222222222 | chat-1234 | user-5678 | 23          |\n| 33333333-3333-3333-3333-333333333333 | chat-4321 | user-9876 | 5           |\n\n### Example Query: Checking a Specific Permission\n\nSuppose you want to check if a specific user in a chat has the \"SendMessages\" permission.\nAssume that the `SendMessages` permission corresponds to the bit value `1` (i.e. `1 \u003c\u003c 0`).\n\nThe following SQL query uses the bitwise AND operator to verify that the permission bit is set:\n\n```sql\n SELECT *\n FROM chat_user\n WHERE chat_id = :chat_id\n   AND user_id = :user_id\n   AND (permissions \u0026 :flag) = :flag;\n ```\n\n### Example PHP Code Using PDO\n\nBelow is an example of how you might execute the above query using a PDO instance (assumed to be available as `$pdo`):\n\n```php\n use Meius\\FlagForge\\FlagManager;\n \n /**\n * @var PDO $pdo\n * @var FlagManager $manager\n * @var string $chatId Chat ID to query.\n * @var string $userId User ID to query.\n */\n \n $manager-\u003eadd(Permission::SendMessages);\n\n // Prepare the SQL statement\n $stmt = $pdo-\u003eprepare('\n     SELECT *\n     FROM chat_user\n     WHERE chat_id = :chat_id\n       AND user_id = :user_id\n       AND (permissions \u0026 :flag) = :flag\n ');\n\n // Execute the query with the parameters\n $stmt-\u003eexecute([\n     ':chat_id' =\u003e $chatId,\n     ':user_id' =\u003e $userId,\n     ':flag' =\u003e $manager,\n ]);\n\n // Fetch the result\n $result = $stmt-\u003efetch(PDO::FETCH_ASSOC);\n\n if ($result) {\n     echo \"User has the SendMessages permission.\";\n } else {\n     echo \"User does NOT have the SendMessages permission.\";\n }\n ```\n\n## API Reference\n\n### FlagManager\n\n- `add(Bitwiseable $flag): self` — Adds a flag to the current mask.\n- `remove(Bitwiseable $flag): self` — Removes a flag from the current mask.\n- `combine(Bitwiseable ...$flags): self` — Combines multiple flags into the current mask.\n- `toggle(Bitwiseable ...$flags): self` — Toggles specified flags.\n- `clear(): self` — Clears all flags in the current mask.\n- `has(Bitwiseable $flag): bool` — Checks if the specified flag is present.\n- `doesntHave(Bitwiseable $flag): bool` — Checks if the specified flag is not present.\n- `getMask(): int` — Returns the current mask value.\n- `toArray(): array` — Returns an array representation of the current mask.\n\n## Support\n\nFor support, please open an issue on the [GitHub repository](https://github.com/brann-meius/flag-forge/issues).\n\n### Contributing\n\nWe welcome contributions to the `meius/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## 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%2Fflag-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrann-meius%2Fflag-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrann-meius%2Fflag-forge/lists"}