#Boolean Condition

Refine is a paid package. To purchase, head to hammerstone.dev.

The boolean condition is for columns that are either true or false. In its basic form, it looks like this:

BooleanCondition::make('is_onboarded', 'Onboarded');

This condition has an id of is_onboarded, is applied against a column of is_onboarded, and has a display value to the end user of "Onboarded".

Remember that condition IDs should be unique and should not change. If you want to disassociate the condition's ID from its attribute, you can explicitly call ->attribute($value) to set the attribute.

#Nullable Columns

If you have defined your boolean columns as nullable in your schema, the BooleanCondition can handle those nulls in a few different ways.

In the following example the has_allergies column was created as a nullable boolean. In contrast to the is_onboarded column, which is definitely going to always be true or false, the has_allergies column could reasonably be null if we don't yet know if an employee has any food allergies.

// A migration that creates nullable boolean.
$table->boolean('has_allergies')->nullable();

When it comes to nullable columns and the BooleanCondition, you have three options:

1. Treat them as nulls.
2. Treat them as true.
3. Treat them as false.

#The Default

By default, the BooleanCondition treats nulls as actual nulls, but does not allow the user to choose them. We find this is the most conservative default configuration that avoids misrepresenting the data.

As an illustration, the following two conditions are exactly the same:

BooleanCondition::make('has_allergies');
 
BooleanCondition::make('has_allergies')
    ->nullsAreUnknown()
    ->hideUnknowns();

#Nulls as Unknown

If you decide that when the column is null the user should be able to filter down to just those records, you can turn on showUnknowns:

BooleanCondition::make('has_allergies')
    ->showUnknowns();

This will give the user an "Is Set" and "Is Not Set" clauses so that they can filter down to employees that have has_allergies set to null.

#Nulls as True or False

There are times where you want to treat a null value as either true or false.

If you wanted to assume that any employees that haven't filled out their allergy status aren't allergic to anything, you can do that by calling nullsAreFalse.

// Nulls are treated as false, i.e.: they do not have allergies.
BooleanCondition::make('has_allergies')
    ->nullsAreFalse();

On the other hand, if you're worried about accidentally causing an allergic reaction, you can treat all employees with unknown allergy statuses as allergic:

// Nulls are treated as true, i.e.: they have allergies.
BooleanCondition::make('has_allergies')
    ->nullsAreTrue();

There's no "right" way to represent nulls, every app and every attribute are different. So choose whatever suits your needs the best!

#Clauses

#CLAUSE_TRUE

The attribute is true. Includes null if you have called nullsAreTrue(),

#CLAUSE_FALSE

The attribute is false. Includes null if you have called nullsAreFalse(),

#CLAUSE_SET

The attribute is not null.

#CLAUSE_NOT_SET

The attribute is null.