Cartalyst LLC.
Conditions by Cartalyst
1
26
8
8
0

This package requires a valid subscription. Subscribe for access.

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 running composer 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\SerializableClosurepassed 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

You wont find fancy lifestyle graphics and marketing bravado here. Just cold... hard... code...

Code Well, Rock On!
Processing Payment...