From 8d6e1bcc2662d44fcbdb201e8205fc5c1d585ff5 Mon Sep 17 00:00:00 2001
From: Joel Male <joel@joelmale.com>
Date: Tue, 25 Feb 2025 13:49:09 +1000
Subject: [PATCH] wip: readme updates

---
 README.md             | 162 +++++++++++++++++++++++-------------------
 docs/laravel-cart.png | Bin 0 -> 10195 bytes
 2 files changed, 89 insertions(+), 73 deletions(-)
 create mode 100644 docs/laravel-cart.png

diff --git a/README.md b/README.md
index 743fddc..222964e 100644
--- a/README.md
+++ b/README.md
@@ -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.
\ No newline at end of file
+## 📓 License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
\ No newline at end of file
diff --git a/docs/laravel-cart.png b/docs/laravel-cart.png
new file mode 100644
index 0000000000000000000000000000000000000000..f8cac1fb394bda26720a800941129bfc9b5b826d
GIT binary patch
literal 10195
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

literal 0
HcmV?d00001