This package helps you use bitwise enums in your Laravel application if you choose to, think before you do. It provides an Enum Container, a trait for your model query scopes and a model attribute cast.
You can think of this as a hasMany relationship but using a single integer column to store the data.
You can install the package into your Laravel project via composer:
composer require matthewpageuk/laravel-bitty-enumsYou can create a new enum using the bitty-enum:make Artisan command. This command will create a new enum class in the app/Enums directory with the cases you supply. It will ensure the values and names are suitable for use with the package.
php artisan bitty-enum:make ColoursTo use your own enums with this package they must :
- Implement the
MatthewPageUK\BittyEnums\Contracts\BittyEnuminterface. - Return type
int - Values be a power of 2 starting from 1 in order
Invalid enums will throw an BittyEnumException when used with the container.
There is a current limit of 16 cases (bits) per enum. This can be overiding in your config files.
use MatthewPageUK\BittyEnums\Contracts\BittyEnum;
enum Colour: int implements BittyEnum
{
case Red = 1;
case Green = 2;
case Blue = 4;
case White = 8;
case Black = 16;
case Pink = 32;
}The container is used to store the selected enum values. It is a wrapper around the integer value and provides methods to manage and check the values. It also performs validation on the values you set to prevent accidental misuse.
You can create a new container using the Contract binding in the Laravel app.
use App\Enums\Colour;
use MatthewPageUK\BittyEnums\Contracts\BittyContainer;
$container = app()->make(BittyContainer::class)->setClass(Colour::class);This will create a container suitable for the Colour enum.
You can also use the MatthewPageUK\BittyEnums\Support\Container directly.
use MatthewPageUK\BittyEnums\Support\Container as BittyContainer;
$favouriteColours = (new BittyContainer(Colour::class))
->set(Colour::Red)
->set(Colour::Green)
->set(Colour::Blue);// Set values
$favouriteColours = app()->make(BittyContainer::class)
->setClass(Colour::class)
->set(Colour::Red)
->set(Colour::Green)
->set(Colour::Blue);
// Passing an array of values
$favouriteColours = app()->make(BittyContainer::class)
->setClass(Colour::class)
->set([Colour::Red, Colour::Green, Colour::Blue]);
// Unset a value
$favouriteColours->unset(Colour::Red);
// Check if the container has a value
if ($favouriteColours->has(Colour::Red)) {
echo 'Red is one of your favourite colours';
}
// Check if the container has any of the values
if ($favouriteColours->hasAny([Colour::Red, Colour::Green])) {
echo 'You like red or green';
}
// Check if the container has all of the values
if ($favouriteColours->hasAll([Colour::Red, Colour::Green])) {
echo 'You like red and green';
}
// Pass another container to check if any of the values exist
if ($product->colours->hasAny($favouriteColours)) {
echo 'This product is available in one of your favourite colours';
}public function __construct(string $class, int $selected = 0);
public function clear(): BittyContainer;
public function getChoices(): array;
public function getValue(): int;
public function has(BittyEnum $choice): bool;
public function hasAll(array|BittyContainer $choices): bool;
public function hasAny(array|BittyContainer $choices): bool;
public function set(array|BittyContainer|BittyEnum $choice): BittyContainer;
public function setAll(): BittyContainer;
public function unset(array|BittyContainer|BittyEnum $choice): BittyContainer;The container also perfoms validation on the values you set, throwing a BittyEnumException if you try to set an invalid value or have a malformed enum.
You can cast the integer column on your models to a BittyEnumContainer using the MatthewPageUK\BittyEnums\Casts\BittyEnumCast cast.
You must pass the enum class you intend to use as the second parameter.
Your database column should be a BIGINT.
@todo see also bit limit on enum, how many can we have?
Schema::create('products', function (Blueprint $table) {
$table->id();
$table->string('name');
$table->unsignedBigInteger('colours');
$table->unsignedInteger('price');
$table->timestamps();
});
use App\Enums\Colour;
use MatthewPageUK\BittyEnums\Casts\BittyEnumCast;
class Product extends Model
{
protected $casts = [
'colours' => BittyEnumCast::class . ':' . Colour:class,
];
}You can now use the container methods to update and retrieve the enum values direct from your model attribute.
$product = Product::find(1);
$product->colours->set(Colour::Blue)->unset(Colours::Red);
$product->save();// Check if value exists
$product = Product::find(1);
if ($product->colours->has(Colour::Blue)) {
echo 'This product is available in blue';
}// Check if any of the values exist
$customerPreferences = app()->make(BittyContainer::class)
->setClass(Colour::class)
->set(Colour::Blue)
->set(Colour::Red)
->set(Colour::Green);
$product = Product::find(1);
if ($product->colours->hasAny($customerPreferences)) {
echo 'This product is available in one of the customers preferred colours';
}To access the scoped queries in your model you need to use the MatthewPageUK\BittyEnums\Traits\WithBittyEnumQueryScope trait.
You should also ensure your model has the BittyEnumCast set on the column you want to query.
use App\Enums\Colours;
use MatthewPageUK\BittyEnums\Traits\WithBittyEnumQueryScope;
class Product extends Model
{
use WithBittyEnumQueryScope;
...
}// Products with the colour blue
Product::whereBittyEnumHas('colours', Colour::Blue)->get();
// Products with the colour blue or red
Product::whereBittyEnumHasAny('colours', [Colour::Blue, Colour::Red])->get();
// Products with the colour blue and red
Product::whereBittyEnumHasAll('colours', [Colour::Blue, Colour::Red])->get();
// Products without the colour blue
Product::whereBittyEnumDoesntHave('colours', Colour::Blue)->get();
// Products without the colour blue or red
$customerPreferences = new BittyEnumContainer(Colour::class)
->set(Colour::Blue)
->set(Colour::Red);
Product::whereBittyEnumDoesntHaveAny('colours', $customerPreferences)->get();Methods accepting multiple choices can be an array of BittyEnum or a BittyEnumContainer.
A BittyEnumException will be thrown if you pass the incorrect type or invalid enum to the query scope.
You can set the maximum number of bits for the container in the config file.
return [
'max_bits' => 16,
];composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.