Download the PHP package meius/laravel-flag-forge without Composer

Laravel Flag Forge Package

Recommendation: Prior to integrating this wrapper into your application, please review the documentation for the underlying library meius/flag-forge to fully grasp its foundational concepts and operations.

Laravel Flag Forge is a refined and sophisticated extension that effortlessly bridges the gap between the powerful bitwise flag management capabilities of the core library and the expressive nature of Laravel applications. This package enhances your project with:

• Seamless Eloquent attribute casting,
• A fluent API for bitwise operations,
• Additional expressive query methods,
• An Artisan command to generate bitwise enum classes,
• And a convenient facade for rapid access to flag operations.

Table of Contents

• Features
• Requirements
• Getting Started
• Installation
• Usage
  • 1. Creating Bitwise Enums
  • 2. Working with Eloquent (Attribute Casting)
  • 3. Mastering Bitwise Operations
  • 4. Using the Facade
  • 5. Leveraging Database Query Methods
  • 6. Integrating with Authorization Policies
• Support
• License

Features

• Expressive Bitwise Operations:
  Enjoy a comprehensive suite of methods such as add, remove, combine, and toggle for managing flags in a clear and fluent manner.

• Elegant Flag Verification:
  Utilize the has and doesntHave methods to effortlessly determine whether a specific flag is active.

• Database Integration:
  Store flags in numeric fields and retrieve them with automatic conversion to a fully featured FlagManager instance.

• Eloquent Attribute Casting:
  With the AsMask cast, numeric bitmask values in your models are instantly transformed into elegant FlagManager objects.

• Enhanced Query Methods:
  Filter records using expressive methods such as whereHasFlag, whereDoesntHaveFlag, whereAllFlagsSet, and whereAnyFlagSet for sophisticated query building.

• Artisan Command:
  Generate new bitwise enum classes effortlessly with php artisan make:bit-enum.

• Convenient Facade:
  Access and chain flag operations using the provided Flag facade for rapid prototyping and production-ready code.

Requirements

• PHP: >= 8.2
• Laravel: >= 11.0

Getting Started

To get started with the meius/laravel-flag-forge package, follow the installation instructions below and check out the usage examples.

Installation

1. Composer Installation:
   Install the package using Composer:

2. Register the Service Provider:
   Manually register the service provider by adding it to your bootstrap/providers.php file:

Usage

1. Creating Bitwise Enums

Generate a new bitwise enum class using Laravel's Artisan command. For instance, to create an enum for user permissions:

This command scaffolds a template class where you can define a series of bitwise flags such as SendMessages, DeleteMessages, AddUsers, etc. Customize this file to reflect the specific needs of your application.

2. Working with Eloquent (Attribute Casting)

Harness the power of Laravel's Eloquent by converting numeric bitmask fields into expressive FlagManager instances. Consider the following pivot model example:

Example of Eloquent Operations:

3. Mastering Bitwise Operations

The FlagManager object provides a robust API to manage bitwise flags with ease. Below are detailed examples of key methods:

• Adding Flags:
  Append new flags to your configuration:

• Removing Flags:
  Exclude specific flags:

• Combining Flags:
  Merge multiple flags simultaneously:

• Toggling Flags:
  Switch a flag’s state between active and inactive:

• Flag Verification:
  Check if a flag is set or unset:

Each of these operations is designed to be chainable, promoting a fluent and natural coding style that enhances readability and maintainability.

4. Using the Facade

The Flag facade grants immediate access to flag management operations. It supports chaining methods for building complex configurations:

This elegant facade simplifies the process of flag manipulation, allowing you to write succinct, expressive code.

5. Leveraging Database Query Methods

Laravel Flag Forge enriches your querying capabilities by providing additional methods that allow filtering based on bitwise flags.

• Filtering Records with Specific Flags:

• Excluding Records Missing Certain Flags:

• Combining Conditions with Expressive Methods:

• Retrieving Records with Any of Multiple Flags Set:

These query methods empower you to create finely tuned database queries, ensuring that your application logic remains both robust and highly expressive.

6. Integrating with Authorization Policies

Seamlessly integrate bitwise flag management into Laravel’s authorization system. For example, consider a policy governing chat interactions. You can employ flag checks directly within policy methods to enforce nuanced permissions:

This integration ensures that your authorization logic remains expressive and perfectly aligned with the dynamic nature of bitwise permissions.

Support

For support, please open an issue on the GitHub repository.

Contributing

We welcome contributions to the meius/laravel-flag-forge library. To contribute, follow these steps:

1. Fork the Repository: Fork the repository on GitHub and clone it to your local machine.
2. Create a Branch: Create a new branch for your feature or bugfix.
3. Write Tests: Write tests to cover your changes.
4. Run Tests: Ensure all tests pass by running phpunit.
5. Submit a Pull Request: Submit a pull request with a clear description of your changes.

For more details, refer to the CONTRIBUTING.md file.

License

This package is open-sourced software licensed under the MIT license.