wip: readme updates

2026-11-14 13:51:44 +00:00 · 2025-02-25 13:49:09 +10:00
parent b92dce9ca4
commit 8d6e1bcc26
2 changed files with 89 additions and 73 deletions
@@ -1,7 +1,11 @@
+<a name="top"></a>
+[![Laravel Cart](./docs/laravel-cart.png)](https://joelmale.com)
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/joelwmale/laravel-cart.svg?style=flat-square)](https://packagist.org/packages/joelwmale/laravel-cart)
 [![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/joelwmale/laravel-cart/tests.yml?branch=master&label=Tests)](https://github.com/joelwmale/laravel-cart/actions?query=workflow%3ATests+branch%3Amaster)
 [![Total Downloads](https://img.shields.io/packagist/dt/joelwmale/laravel-cart.svg?style=flat-square)](https://packagist.org/packages/joelwmale/laravel-cart)
+[![GitHub last commit](https://img.shields.io/github/last-commit/joelwmale/laravel-cart)](#)
 [![License](https://poser.pugx.org/joelwmale/laravel-cart/license.svg)](https://packagist.org/packages/joelwmale/laravel-cart)
+[![Free](https://img.shields.io/badge/free_for_non_commercial_use-brightgreen)](#-license)

 A Cart Implementation for Laravel.

@@ -9,35 +13,58 @@

 For Laravel 9.0 and below, please use version [1.0](https://github.com/joelwmale/laravel-cart/releases/tag/1.0.12)

-## Quick Demo
+## Table of Contents
+- [Getting Started](#-getting-started)
+- [Demo](#-deni)
+- [Documentation](#-documentation)
+  - [Configuration](#configuration)
+  - [Basic Usage](#basic-usage)
+  - [Conditions](#conditions)
+  - [Items](#items)
+- [Credits](#-credits)
+- [License](#-license)

-```php
-// Add an item to the cart
-\Cart::add(1, 'Product 1', 19.99, 2, ['size' => 'large']);
-
-// Get the cart contents
-$cartContents = \Cart::getContent();
-
-// Update item quantity by its id
-\Cart::update(1, ['quantity' => 3]);
-
-// Remove an item from the cart by its id
-\Cart::remove(1);
-
-// Get cart total
-\$total = Cart::getTotal();
-
-// Clear the entire cart
-\Cart::clear();
-```
-
-## Installing
+## 🚀 Getting Started
+### 🔥 Installing

 Install the package through [Composer](http://getcomposer.org/).

 `composer require "joelwmale/laravel-cart"`

-## Configuration
+## 🧑‍🍳 Demo
+
+```php
+// Add an item to the cart
+\Cart::add(
+    1, // any unique id
+    'Product 1', // product name
+    19.99, // product price
+    2, // quantity
+    ['size' => 'large'] // an array of extra attributes
+);
+
+// get the entire cart
+$cartContents = \Cart::getContent();
+
+// update an item already in the cart
+\Cart::update(
+    1, // the same unique id that was used to add the item
+    ['quantity' => 3] // the quantity to update
+);
+
+// remove the item by its id
+\Cart::remove(1);
+
+// get the total of the cart
+\$total = Cart::getTotal();
+
+// clear it all when you've finished (like when you've stored the order)
+\Cart::clear();
+```
+
+## 📚 Documentation
+
+### ⚙️ Configuration

 You can publish the configuration file to customize various options.

@@ -45,7 +72,7 @@ ## Configuration
 php artisan vendor:publish --provider="Joelwmale\Cart\CartServiceProvider" --tag="config"
 ```

-### Formatting Numbers
+#### Formatting Numbers

 The package by default does not use round to format numbers, and instead returns the number using floatval().

@@ -58,7 +85,7 @@ ### Formatting Numbers
 'round_mode' => env('LARAVEL_CART_ROUND_MODE', 'down'),
 ```

-### Decimals
+#### Decimals

 You can customize the number of decimals in the configuration file.

@@ -68,7 +95,7 @@ ### Decimals
 'decimals' => env('LARAVEL_CART_DECIMALS', 2),
 ```

-### Round Mode
+#### Round Mode

 The package uses the `round` function to round the prices. You can customize the rounding mode in the configuration file.

@@ -78,21 +105,8 @@ ### Round Mode
 'round_mode' => env('LARAVEL_CART_ROUND_MODE', 'down'),
 ```

-## Usage

-   [Basic Usage](#basic-usage)
-   [Conditions](#conditions)
-   [Items](#items)
-   [Associating Models](#associating-models)
-   [Instances](#instances)
-   [Exceptions](#exceptions)
-   [Events](#events)
-   [Format Response](#format)
-   [Examples](#examples)
-   [Using Different Storage](#storage)
-   [License](#license)
-
-## Usage
+### Basic Usage

 The cart has a default sessionKey that holds the cart data and stores it in the session. 

@@ -111,7 +125,7 @@ ## Usage
 \Cart::session(User::first()->id)->add(1, 'Product 1', 19.99, 2, ['size' => 'large']);
 ```

-### Adding to the cart: **Cart::add()**
+#### Adding to the cart: **Cart::add()**

 There are a few ways to add items to the cart.

@@ -182,7 +196,7 @@ ### Adding to the cart: **Cart::add()**
 );
 ```

-### Updating an item on a cart: **Cart::update()**
+#### Updating an item on a cart: **Cart::update()**

 ```php
 Cart::update(
@@ -221,14 +235,14 @@ ### Updating an item on a cart: **Cart::update()**
 );
 ```

-### Removing an item on a cart: **Cart::remove()**
+#### Removing an item on a cart: **Cart::remove()**

 ```php
 // Remove an item from the cart by its id
 Cart::remove(456);
 ```

-### Getting an item on a cart: **Cart::get()**
+#### Getting an item on a cart: **Cart::get()**

 ```php
 // Get an item from the cart by its id
@@ -238,7 +252,7 @@ ### Getting an item on a cart: **Cart::get()**
 $summedPrice = Cart::get($itemId)->getPriceSum();
 ```

-### Getting the cart content: **Cart::getContent()**
+#### Getting the cart content: **Cart::getContent()**

 ```php
 // Returns a collection of the cart's contents
@@ -258,13 +272,13 @@ ### Getting the cart content: **Cart::getContent()**
 $cartTotalQuantity = Cart::getTotalQuantity();
 ```

-### Cart subtotal: **Cart::getSubTotal()**
+#### Cart subtotal: **Cart::getSubTotal()**

 ```php
 $subTotal = Cart::getSubTotal();
 ```

-### Cart subtotal without conditions: **Cart::getSubTotalWithoutConditions()**
+#### Cart subtotal without conditions: **Cart::getSubTotalWithoutConditions()**

 ```php
 $subTotalWithoutConditions = Cart::getSubTotalWithoutConditions();
@@ -276,19 +290,19 @@ ### Cart subtotal without conditions: **Cart::getSubTotalWithoutConditions()**
 $total = Cart::getTotal();
 ```

-### Check if cart is empty: **Cart::isEmpty()**
+#### Check if cart is empty: **Cart::isEmpty()**

 ```php
 Cart::isEmpty();
 ```

-### Clearing the Cart: **Cart::clear()**
+#### Clearing the Cart: **Cart::clear()**

 ```php
 Cart::clear();
 ```

-## Conditions
+### Conditions

 Conditions are very useful for adding things like discounts, taxes, shipping, etc.

@@ -300,9 +314,9 @@ ## Conditions

 You can also provide an `order` to cart conditions which tells the cart in what order to apply the conditions. Item level conditions do not support the `order` parameter.

-### Conditions on the cart
+#### Conditions on the cart

-#### Adding a condition to the cart: **Cart::condition()**
+##### Adding a condition to the cart: **Cart::condition()**

 ```php
 // Add a single condition to the cart
@@ -353,7 +367,7 @@ #### Adding a condition to the cart: **Cart::condition()**
 Cart::condition($shipping);
 ```

-#### Getting conditions on the cart: **Cart::getConditions()**
+##### Getting conditions on the cart: **Cart::getConditions()**

 ```php
 // To get all applied conditions on a cart, use below:
@@ -372,7 +386,7 @@ #### Getting conditions on the cart: **Cart::getConditions()**
 }
 ```

-#### Getting conditions on the cart as an array: **Cart::getConditions(array: true)**
+##### Getting conditions on the cart as an array: **Cart::getConditions(array: true)**

 You can get all cart conditions in array format by passing "array: true". This is useful if you want to store the carts conditions on a Livewire component since by default we have collections inside collections for conditions which Livewire does not support.

@@ -391,7 +405,7 @@ #### Getting conditions on the cart as an array: **Cart::getConditions(array: tr
 }
 ```

-#### Getting conditions by name: **Cart::getCondition($conditionName)**
+##### Getting conditions by name: **Cart::getCondition($conditionName)**

 ```php
 $condition = Cart::getCondition('GST');
@@ -405,7 +419,7 @@ #### Getting conditions by name: **Cart::getCondition($conditionName)**
 $condition->getAttributes(); // the attributes of the condition, returns an empty [] if no attributes added
 ```

-#### Getting active conditions on the cart: **Cart::getConditions(active: true)**
+##### Getting active conditions on the cart: **Cart::getConditions(active: true)**

 You can get only active conditions by passsing `active: true` to the `getConditions()` method.

@@ -441,14 +455,14 @@ #### Getting active conditions on the cart: **Cart::getConditions(active: true)*
 // will return no conditions if the subtotal is $210
 ```

-### Calculating condition value
+##### Calculating condition value

 There are 2 ways to calculate the value of a condition:

 1. Using the `getCalculatedValue` method on the condition instance
 2. Using the `getCalculatedValueForCondition` method on the cart instance and passing the condition name

-#### Using the `getCalculatedValue` method on the condition instance
+##### Using the `getCalculatedValue` method on the condition instance

 ```php
 $subTotal = Cart::getSubTotal();
@@ -456,7 +470,7 @@ #### Using the `getCalculatedValue` method on the condition instance
 $conditionCalculatedValue = $condition->getCalculatedValue($subTotal);
 ```

-#### Using the `getCalculatedValueForCondition` method on the cart instance
+##### Using the `getCalculatedValueForCondition` method on the cart instance

 This method automatically calculates the value of a condition by it's name based on the order of the conditions.

@@ -489,7 +503,7 @@ #### Using the `getCalculatedValueForCondition` method on the cart instance
 Cart::getCalculatedValueForCondition('Gift Card'); // returns 0 as the coupon discount is applied first and brings the subtotal to 0
 ```

-### Adding conditions that activate once a minimum value is met
+##### Adding conditions that activate once a minimum value is met

 You can add a `minimum` amount required for a condition to activate.

@@ -508,7 +522,7 @@ ### Adding conditions that activate once a minimum value is met
 Cart::condition($tenPercentOff)
 ```

-### Adding conditions that only activate up to a maximum value
+##### Adding conditions that only activate up to a maximum value

 You can add a `maximum` amount required for a condition to activate.

@@ -527,7 +541,7 @@ ### Adding conditions that only activate up to a maximum value
 Cart::condition($shipping)
 ```

-### Condition on items
+#### Conditions on items

 Item conditions are useful if you have discounts to be applied specifically on an item and not on the whole cart value.

@@ -588,7 +602,7 @@ ### Condition on items
 $cartSubTotal = Cart::getSubTotal();
 ```

-#### Add a condition to an existing item on the cart: **Cart::addItemCondition($productId, $itemCondition)**
+##### Add a condition to an existing item on the cart: **Cart::addItemCondition($productId, $itemCondition)**

 Adding Condition to an existing Item on the cart is simple as well.

@@ -602,7 +616,7 @@ #### Add a condition to an existing item on the cart: **Cart::addItemCondition($
 Cart::addItemCondition(456, $condition);
 ```

-### Clearing Cart Conditions: **Cart::clearCartConditions()**
+#### Clearing Cart Conditions: **Cart::clearCartConditions()**

 This clears all cart level conditions, and does not affect item level conditions.

@@ -616,25 +630,25 @@ ### Clearing Cart Conditions: **Cart::clearCartConditions()**
 Cart::clearAllConditions()
 ```

-### Remove a specific cart condtion: **Cart::removeCartCondition($conditionName)**
+##### Remove a specific cart condtion: **Cart::removeCartCondition($conditionName)**

 ```php
 Cart::removeCartCondition('Summer Sale 5%')
 ```

-### Remove a specific item condition: **Cart::removeItemCondition($itemId, $conditionName)**
+##### Remove a specific item condition: **Cart::removeItemCondition($itemId, $conditionName)**

 ```php
 Cart::removeItemCondition(456, 'SALE 5%')
 ```

-### Clear all item conditions: **Cart::clearItemConditions($itemId)**
+##### Clear all item conditions: **Cart::clearItemConditions($itemId)**

 ```php
 Cart::clearItemConditions(456)
 ```

-### Get conditions by type: **Cart::getConditionsByType($type)**
+#### Get conditions by type: **Cart::getConditionsByType($type)**

 This returns all conditions that has been added to the cart by the type specified.

@@ -642,13 +656,13 @@ ### Get conditions by type: **Cart::getConditionsByType($type)**
 $tax = Cart::getConditionsByType('tax');
 ```

-### Remove conditions by type: **Cart::removeConditionsByType($type)**
+##### Remove conditions by type: **Cart::removeConditionsByType($type)**

 ```php
 Cart::removeConditionsByType('tax');
 ```

-## Cart Items
+### Cart Items

 The method **Cart::getContent()** returns a collection of items.

@@ -670,8 +684,10 @@ ## Cart Items
 $item->getPriceSumWithConditions();
 ```

-## Credits
+## 🫡 Credits

-Huge credits to the original maintainer of the package, located at [darryldecode/laravelshoppingcart](https://github.com/darryldecode/laravelshoppingcart)
+This package was orignally created by [darryldecode](https://github.com/darryldecode) but has since seen almost no updates. I have decided to take the old package and transform it into a new package with new features and updates.

-We have forked this package to update it to Laravel 11 and to add some features and support for newer PHP versions.
+## 📓 License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.