Introduction
A framework agnostic conditions package that allows you to apply conditions on Cartalyst Collections.
The package requires PHP 8.0+ and follows the FIG standard PSR-4 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.
Have a read through the Installation Guide.
Apply a condition
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'Example item',
'subtotal' => 200,
]);
$condition = new Condition([
'name' => 'VAT (17.5%)',
'type' => 'tax',
'target' => 'subtotal',
]);
$condition->setActions([
'value' => '17.5%',
]);
$total = $condition->apply($collection); // 235
$conditionResult = $condition->result(); // 35
Note: You can apply conditions on any Cartalyst Collection.
Installation
The best and easiest way to install the Conditions package is with Composer.
Preparation
Open your composer.json
file and add the following to the require
array:
"cartalyst/conditions": "^5.0"
Add the following lines after the require
array on your composer.json
file:
"repositories": [
{
"type": "composer",
"url": "https://packages.cartalyst.com"
}
]
Note: Make sure that after the required changes your
composer.json
file is valid by runningcomposer validate
.
Install the dependencies
Run Composer to install or update the new requirement.
php composer install
or
php composer update
Now you are able to require the vendor/autoload.php
file to autoload the package.
Usage
In this section we'll show how you can use conditions with your collections. Here are a few quick examples.
Actions
Actions define the behavior the condition will apply on the collection.
Define actions
$condition->setActions([
'value' => '-10%',
]);
The action above will deduct 10 percent of the target property.
Accumulative actions
You can define multiple actions to be applied on one collection, simply pass another array with your desired action.
Defining multiple actions on one condition will accumulate based on the target property.
$condition->setActions([
[
'value' => '17.5%',
],
[
'value' => '5%',
],
]);
The example above will add 17.5% first, then add 5% to the result of the previous action.
Note The example above is not equal to passing 22.5%
Callbacks
When the rules are satisfied:
You can set a Closure
or a SuperClosure\SerializableClosure
on the setActions
method that will run upon successfully validating the rules.
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'An item',
'price' => 100.00,
'quantity' => 5,
]);
$condition = new Condition([
'target' => 'price',
]);
$condition = setRules([
'price < 200'
]);
$condition->setActions([
'value' => '20%',
'multiplier' => 'quantity',
], function()
{
// Code here will run when the condition is applied ( only if successfully validated )
});
You can also set the success callback directly, using a Closure
or a SuperClosure\SerializableClosure
passed into the whenValid()
method.
$condition->whenValid(function() use (&$collection){
$collection->add([
'name' => 'Another item',
'price' => 0.00,
'quantity' => 1,
]);
});
The example above will add an item to the collection when the rules are satisfied.
When the rules are unsatisfied:
Conversely, use the whenInvalid()
method to dicate what happens when the rules are not satisfied
$condition->whenInvalid(function() use (&$collection){
$collection->remove('c14c437bc9ae7d35a7c18ee151c6acc0');
});
The example above will remove an item from the collection when the rules are not satisfied.
Closure
You can also set a Closure
or a SuperClosure\SerializableClosure
as the value of any of the actions on the setActions
method to determine the value of that action.
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'An item',
'price' => 100.00,
'quantity' => 5,
]);
$condition = new Condition([
'target' => 'subtotal',
]);
$condition->setActions([
'value' => function($collection)
{
return '-' . floor($collection->get('subtotal') / 2);
},
]);
The example above will give half off the subtotal, rounded down to the whole value.
Multiplier
Actions can contain a reference to a multiplier field
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'An item',
'price' => 100.00,
'quantity' => 5,
]);
$condition = new Condition([
'target' => 'price',
]);
$condition->setActions([
'value' => '20%',
'multiplier' => 'quantity',
]);
The example above will multiply the condition result by the quantity.
Max
Actions can contain a max property that will prevent the condition from reaching beyond that limit.
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'An item',
'price' => 100.00,
]);
$condition = new Condition([
'target' => 'price',
]);
$condition->setActions([
'value' => '20%',
'max' => 10,
]);
$condition->apply($collection); // 110
$condition->result(); // 10
Inclusive
Actions can contain an inclusive property that will reverse calculate the action value.
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'An item',
'price' => 100.00,
]);
$condition = new Condition([
'target' => 'price',
]);
$condition->setActions([
'value' => '10%',
'inclusive' => true,
]);
$condition->apply($collection);
$condition->result(); // 9.090909091
Rules
Rules validate the collection before applying the condition, it returns false if the rule didn't pass.
Define rules
$condition->setRules([
'price < 200',
]);
The condition above will only apply if the price property is smaller than 200.
Multiple rules
You can define multiple rules to be validated on a collection, condition is only applied if all rules are valid.
$condition->setRules([
'price > 200',
'quantity > 10',
]);
The condition above will only apply if both rules are met.
Closure Rules
You can set a Closure
or a SuperClosure\SerializableClosure
as a validation rule on the condition.
$promotion = true;
$condition->setRules(function($collection) use ($promotion)
{
return $promotion && $collection->get('price') > 100;
});
Comparison Operators
Operator | Example |
---|---|
= | name = item |
!= | name != item1 |
< | price < 20 |
<= | price <= 10 |
> | quantity > 2 |
>= | quantity >= 5 |
Examples
Example 1
Apply a 10% Discount if the subtotal is larger than 200.
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'Item',
'subtotal' => 400,
]);
$condition = new Condition([
'target' => 'subtotal',
]);
$condition->setRules([
'subtotal > 200',
]);
$condition->setActions([
'value' => '-10%',
]);
$condition->apply($collection); // 360
$condition->result() // -40
Example 2
Apply a 12.5% Tax without rules
use Cartalyst\Conditions\Condition;
use Cartalyst\Collections\Collection;
$collection = new Collection([
'name' => 'Item',
'subtotal' => 400,
]);
$condition = new Condition([
'target' => 'subtotal',
]);
$condition->setActions([
'value' => '12.5%',
]);
$condition->apply($collection); // 450
$condition->result() // 50