mirror of
https://github.com/wearepixel/laravel-cart.git
synced 2026-11-14 13:51:44 +00:00
wip: readme updates
This commit is contained in:
Joel Male
@@ -1,7 +1,11 @@
|
||||
<a name="top"></a>
|
||||
[](https://joelmale.com)
|
||||
[](https://packagist.org/packages/joelwmale/laravel-cart)
|
||||
[](https://github.com/joelwmale/laravel-cart/actions?query=workflow%3ATests+branch%3Amaster)
|
||||
[](https://packagist.org/packages/joelwmale/laravel-cart)
|
||||
[](#)
|
||||
[](https://packagist.org/packages/joelwmale/laravel-cart)
|
||||
[](#-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.
|
||||
Reference in New Issue
Block a user