README

A simple library for shopping cart management.

Install

composer

composer require mmdm/sim-cart

Or you can simply download zip file from github and extract it, then put file to your project library and use it like other libraries.

Just add line below to autoload files:

require_once 'path_to_library/autoloader.php';

and you are good to go.

Features

Multiple cart management
Simple cart management
This is not just a simple cart, it has some structures to create a simple yet nice online shops.

Architecture

This library use database to have its best performance

Collation:

It should be utf8mb4_unicode_ci because it is a very nice collation. For more information about differences between utf8 and utf8mb4 in general and unicode please see this link from stackoverflow

Table:

users

This table contains all users.

Least columns of this table should be:
- id (INT(11) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT)
products

This table contains all products.

Least columns of this table should be:
- id (INT(11) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT)
product_property

This table contains all product's properties.

Least columns of this table should be:
- id (INT(11) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT)
- code (VARCHAR(20) NOT NULL)
- product_id (INT(11) UNSIGNED NOT NULL)
- stock_count (INT(11) UNSIGNED NOT NULL)
- max_cart_count (INT(11) UNSIGNED NOT NULL)
- price (BIGINT(20) UNSIGNED NOT NULL)
- discounted_price (BIGINT(20) UNSIGNED NOT NULL)
- tax_rate (DECIMAL (5, 2) UNSIGNED NOT NULL DEFAULT 0)
- is_available (TINYINT(1) UNSIGNED NOT NULL DEFAULT 1)
Constraints:
- ADD CONSTRAINT UC_Code UNIQUE (code)
- ADD CONSTRAINT fk_pp_p FOREIGN KEY(product_id) REFERENCES products(id) ON DELETE CASCADE ON UPDATE CASCADE
carts

This table contains all carts.

Least columns of this table should be:
- id (INT(11) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT)
- user_id (INT(11) UNSIGNED NOT NULL)
- name (VARCHAR(255) NOT NULL)
- created_at (INT(11) UNSIGNED NOT NULL)
- expire_at (INT(11) UNSIGNED NOT NULL)
Constraints:
- ADD CONSTRAINT UC_UserID UNIQUE (user_id,name)
cart_item

This table contains all cart's items.

Least columns of this table should be:
- id (INT(11) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT)
- cart_id (INT(11) UNSIGNED NOT NULL)
- product_property_id (INT(11) UNSIGNED NOT NULL)
- qnt (INT(11) UNSIGNED NOT NULL)
Constraints:
- ADD CONSTRAINT fk_ci_c FOREIGN KEY(cart_id) REFERENCES carts(id) ON DELETE CASCADE ON UPDATE CASCADE
- ADD CONSTRAINT fk_ci_pp FOREIGN KEY(product_property_id) REFERENCES product_property(id) ON DELETE CASCADE ON UPDATE CASCADE

How to use

First of all you need a PDO connection like below:

$host = '127.0.0.1';
$db = 'database name';
$user = 'username';
$pass = 'password';
// this is very nice collation to use
$charset = 'utf8mb4';

$dsn = "mysql:host={$host};dbname={$db};charset={$charset}";
$options = [
    // add this option to show exception on any bad condition
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
];
try {
    $pdo = new PDO($dsn, $user, $pass, $options);
} catch (\PDOException $e) {
    throw new \PDOException($e->getMessage(), (int)$e->getCode());
}

Second you need a cookie class like below:

$cookieStorage = new \Sim\Cookie\Cookie();

[Optionally But Highly Recommended] You need two keys to protect stored data in cookie. These two keys should be two base64 coded strings. Just generate two passwords and encode them to base64 strings. For more info about these two keys see this link

// this is what you have for protecting your data
$cookieStorage = new \Sim\Cookie\Cookie(
    new \Sim\Crypt\Crypt(
        $mainCryptKey,
        $assuredCryptKey
    )
);

Instantiate cart library

$cookieStorage = new \Sim\Cookie\Cookie(new \Sim\Crypt\Crypt($mainCryptKey, $assuredCryptKey));

// we don't need a user, so we don't pass it
$cart = new \Sim\Cart\Cart($pdo, $cookieStorage);

// use cart methods
$cart->add('product_code');

Cart methods

`setCartName(string $name)`

You can name your cart. This will use when you want store a cart in your database. Default name is default.

`getCartName(): string`

Get cart's name.

`setExpiration(int $expire_time)`

Note: You need to send duration of cart to be expired like 86400 that is 1 day in seconds. After call store method, current time will add to this expire time.

Note: you must know this expire time is Different from expire time in database fields.

Set cart expiration time.

`getExpiration(): int`

Get cart expiration time. Default expiration time is 31536000 that is 1 year.

Note: This method just returns the time like 31536000 that is 1 year not how much it has to be expired but if you need to know expiration time until, store cart to database and get expire_at field of carts.

`utils(): ICartsUtil`

Utilities that can do with current cart and current user.

To see information about this utils, see CartUtil section.

Note: This only works if you pass a pdo connection and a user id to work with.

`add(string $item_code, array $item_info = null)`

Add an item to cart with product's code from product_property table. You can add extra information to item with $item_info parameter. At last the stored item has all product_property table's columns fields value and qnt parameter and your extra information.

Note: All item's keys are from keys of config file and as commented in config file too, DO NOT CHANGE keys please.

Note: By default items will not store in cookie and you should do it yourself using store method.

`update(string $item_code, array $item_info = null)`

It is like add method with extra functionality that is checking if item is added or it'll add it internally.

`remove(string $item_code): bool`

Remove an item from cart.

`getItem(string $item_code): array`

Get a specific item from cart.

`getItems(): array`

Get all cart's items.

`clearItems()`

Delete all items from cart.

`hasItemWithCode(string $item_code): bool`

Check if an item has been set in cart or not.

`totalPrice(): float`

Get total price of items.

`totalDiscountedPrice(): float`

Get total discounted price of items.

`totalPriceWithTax(): float`

Get total price of items with considering tax of each item.

`totalDiscountedPriceWithTax(): float`

Get total discounted price of items with considering tax of each item.

`totalAttributeValue(string $key): float`

Get total of a specific key of all items.

`discountedPercentage(string $item_code, int $decimal_numbers = 2, bool $round = false): float`

Get discount percentage of an specific item.

`totalDiscountedPercentage(int $decimal_numbers = 2, bool $round = false): float`

Get discount percentage of all items.

`totalDiscountedPercentageWithTax(int $decimal_numbers = 2, bool $round = false): float`

Get discount percentage of all items with considering items' tax.

`store()`

Store cart items to storage(cookie).

`restore()`

Restore cart items from storage(cookie) to cart items.

`destroy()`

Destroy cart from storage(cookie).

CartUtil methods

Instantiate

If you need to instantiate utils externally(YOU DON'T NEED)

$utils = new CartsUtil(
    PDO $pdo_instance,
    ICart &$cart,
    ?int $user_id,
    ?array $config = null
);

`runConfig()`

Create tables structure.

`getCart(): ICart`

Get used cart in class.

`setUserId(int $user_id)`

Set user id to work with for database.

`getUserId(): int`

Get used user id.

`save(int $max_stored_cart = PHP_INT_MAX, array $extra_parameters = [], string $extra_where = null, array $bind_values = []): bool`

Save cart to database.

You can specify how many cart can store in database for a specific user. Also you can pass extra parameters and parameterized where clause for customize storing (table is carts here).

Note: You should use actual cart table columns name.

Note: Columns below will unset and use cart information instead:

user_id
name
created_at

// simple usage (unnecessary)
$cartUtil->save(
    2, // max stored cart count
    [
        'extra_column' => extra value,
        ...
    ],
    "some_extra_where=:extra_where_param1",
    [
        'extra_where_param1' => actual value
    ]
);

// if you want use from cart
$cart->utils()->save(
    2, // max stored cart count
    [
        'extra_column' => extra value,
        ...
    ],
    "some_extra_where=:extra_where_param1",
    [
        'extra_where_param1' => actual value
    ]
)

To get exception of max stored cart count, and database errors, put your codes in try {...} catch() {...} block like:

try {
    // try to save or other thing
    // ...
    
    $cart->utils()->save(1);
} catch (\Sim\Cart\Exceptions\CartMaxCountException $e) {
    // if cart count is at maximum count of it
    // ...
} catch (\Sim\Cart\Interfaces\IDBException $e) {
    // database error
    // ...
} catch (\Sim\Crypt\Exceptions\CryptException $e) {
    // encryption or decryption has error
    // ...
}

`fetch(bool $append_to_previous_items = false)`

Fetch cart items from database and store them to provided cart class.

Note: It'll delete all items first, if you want to prevent this default behavior, send true as second parameter.

`delete(string $cart_name): bool`

Delete specific cart for specific user.

`deleteExpiredCarts(string $cart_name): bool`

Delete expired cart for specific user.

`changeName(string $old_cart_name, string $new_cart_name): bool`

Change cart name from old name to new name for a specific user.

`getItem(string $item_code, $columns = '*'): array`

Get specific item with specific columns.

`getStockCount(string $item_code): int`

Get stock count for a specific item.

`getMaxCartCount(string $item_code): int`

Get max cart count for a specific item.

Examples

Create all tables

// after instantiate cart class or even cart util class,
// you can use util's methods. For convenient in examples,
// we will use cart class utils
$cart->utils()->runConfig();

Add item to cart

$cart->add('item_id_from_product_property');

// with extra information
$cart->add('item_id_from_product_property', [
    'type' => 'service',
    ...
]);

Update item in cart

Very Important Note: You can't change an item value that has value in database. Just quantity and your extra information.

// keys are from product_property in 
// config NOT actual column of table
$cart->update('item_id_from_product_property', [
    'qnt' => 4
]);

Cart and storage

// store cart items in cookie
$cart->store();

// restore cart items
$cart->restore();

// delete and destroy cookie for cart
$cart->destroy();

Report

echo 'total price: ' . $cart->totalPrice() . PHP_EOL;
echo 'total price with tax: ' . $cart->totalPriceWithTax() . PHP_EOL;
echo 'total discount price: ' . $cart->totalDiscountedPrice() . PHP_EOL;
echo 'total discount price with tax: ' . $cart->totalDiscountedPriceWithTax() . PHP_EOL;
echo 'discount percentage specific item: ' . $cart->discountedPercentage('item_id_from_product_property') . PHP_EOL;
echo 'total discount percentage: ' . $cart->totalDiscountedPercentage() . PHP_EOL;
echo 'total discount percentage with tax: ' . $cart->totalDiscountedPercentageWithTax() . PHP_EOL;
echo 'total rounded discount percentage: ' . $cart->totalDiscountedPercentage(2, true) . PHP_EOL;
echo 'total rounded discount percentage with tax: ' . $cart->totalDiscountedPercentageWithTax(2, true) . PHP_EOL;

Dependencies

There is some dependencies here including:

Crypt library. With this feature, if any session/cookie hijacking happens, they can't see actual data because it is encrypted.

Cookie library to manipulate cookies.

License

Under MIT license

mmdm / sim-cart

Maintainers

Details

README

Install

Features

Architecture

How to use

Instantiate cart library

Cart methods

setCartName(string $name)

getCartName(): string

setExpiration(int $expire_time)

getExpiration(): int

utils(): ICartsUtil

add(string $item_code, array $item_info = null)

update(string $item_code, array $item_info = null)

remove(string $item_code): bool

getItem(string $item_code): array

getItems(): array

clearItems()

hasItemWithCode(string $item_code): bool

totalPrice(): float

totalDiscountedPrice(): float

totalPriceWithTax(): float

totalDiscountedPriceWithTax(): float

totalAttributeValue(string $key): float

discountedPercentage(string $item_code, int $decimal_numbers = 2, bool $round = false): float

totalDiscountedPercentage(int $decimal_numbers = 2, bool $round = false): float

totalDiscountedPercentageWithTax(int $decimal_numbers = 2, bool $round = false): float

store()

restore()

destroy()