diff --git a/README.md b/README.md index 743fddc..222964e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ + +[![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 0000000..f8cac1f Binary files /dev/null and b/docs/laravel-cart.png differ