Laravel Cart

https://github.com/binafy/laravel-cart
Admin
Laravel Cart is a highly customizable and flexible package that integrates shopping cart...
Tokens:62,165
Snippets:539
Trust Score:8.5
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Install the package via Composer.

```bash
composer require binafy/laravel-cart
```

--------------------------------

### Basic Cartable Implementation Example

Source: https://github.com/binafy/laravel-cart

Example of a Product model implementing Cartable, returning the price as a float.

```php
<?php

use Binafy\LaravelCart\Cartable;
use Illuminate\Database\Eloquent\Model;

class Product extends Model implements Cartable
{
    public function getPrice(): float
    {
        return (float) $this->price;
    }
}
```

--------------------------------

### calculatedPriceByQuantity() example

Source: https://github.com/binafy/laravel-cart

Example usage of calculatedPriceByQuantity() to get the total price as a float.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->storeItems([
    ['itemable' => $product1, 'quantity' => 2],
    ['itemable' => $product2, 'quantity' => 1],
]);

$total = $cart->calculatedPriceByQuantity(); // float
```

--------------------------------

### storeItems() example

Source: https://github.com/binafy/laravel-cart

Example usage of storeItems() to add multiple items to a cart.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);

$cart->storeItems([
    ['itemable' => $product1, 'quantity' => 2],
    ['itemable' => $product2, 'quantity' => 1],
    ['itemable' => $product3, 'quantity' => 5],
]);
```

--------------------------------

### creating() example: saving a new CartItem

Source: https://github.com/binafy/laravel-cart

Example showing how to create and save a CartItem, triggering the creating() observer. The itemable_type must implement Cartable, otherwise a RuntimeException is thrown.

```php
<?php

use Binafy\LaravelCart\Models\Cart;
use Binafy\LaravelCart\Models\CartItem;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);

$cartItem = new CartItem([
    'itemable_id' => $product->id,
    'itemable_type' => $product::class, // Product implements Cartable
    'quantity' => 1,
]);

$cart->items()->save($cartItem); // creating() passes
```

--------------------------------

### decreaseQuantity usage example

Source: https://github.com/binafy/laravel-cart

Example of decreasing quantity by 5, clamping at zero.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

// Quantity 1 decreased by 5 becomes 0, not -4.
LaravelCart::driver('session')->decreaseQuantity($product, 5, (string) $user->id);
```

--------------------------------

### increaseQuantity usage example

Source: https://github.com/binafy/laravel-cart

Example of using increaseQuantity to add 2 to a product's quantity in a cart. Throws RuntimeException if the item is not found.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->increaseQuantity($product, 2);
```

--------------------------------

### emptyCart usage example

Source: https://github.com/binafy/laravel-cart

Example of emptying the session cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('session')->emptyCart((string) $user->id);
```

--------------------------------

### storeItem() example

Source: https://github.com/binafy/laravel-cart

Example usage of storeItem() with both model and array forms.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);

// Model form
$cart->storeItem($product);

// Array form
$cart->storeItem([
    'itemable' => $product,
    'quantity' => 3,
]);
```

--------------------------------

### emptyCart() example

Source: https://github.com/binafy/laravel-cart

Example usage of emptyCart() to clear all items from the cart.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->emptyCart();
```

--------------------------------

### getOptions Example: Retrieving All Options

Source: https://github.com/binafy/laravel-cart

Demonstrates retrieving the entire options payload as an array. Returns null when options is null.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->storeItem($product);

$cartItem = $cart->items()->first();
$cartItem->setOption('size', 34);

$options = $cartItem->getOptions(); // ['size' => 34]
```

--------------------------------

### Non-trivial Cartable Implementation with Discount

Source: https://github.com/binafy/laravel-cart

Example of a Product model implementing Cartable with a per-product discount applied before the cart total is calculated.

```php
<?php

use Binafy\LaravelCart\Cartable;
use Illuminate\Database\Eloquent\Model;

class Product extends Model implements Cartable
{
    public function getPrice(): float
    {
        // Apply a per-product discount before the cart total is calculated.
        $discount = (float) ($this->discount_percentage ?? 0);

        return (float) $this->price * (1 - ($discount / 100));
    }
}
```

--------------------------------

### getOption usage example

Source: https://github.com/binafy/laravel-cart

Example of using the database driver's getOption method to retrieve the 'size' option from the first cart item.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$size = LaravelCart::driver('database')->getOption('size', null, (string) $user->id);
```

--------------------------------

### saving() example: failing Cartable check

Source: https://github.com/binafy/laravel-cart

Example showing a CartItem with an itemable_type that does not implement Cartable, causing a RuntimeException when saved.

```php
<?php

use Binafy\LaravelCart\Models\CartItem;

$cartItem = new CartItem([
    'itemable_id' => $user->id,
    'itemable_type' => $user::class, // User does not implement Cartable
    'quantity' => 1,
]);

$cartItem->save(); // RuntimeException: The item must be an instance of Cartable
```

--------------------------------

### addOption() example

Source: https://github.com/binafy/laravel-cart

Adds two options to item 2 and then retrieves them, showing the combined result.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$driver = LaravelCart::driver('database');
$driver->addOption('size', 34, 2, (string) $user->id);
$driver->addOption('address', 'something', 2, (string) $user->id);

$driver->getOptions(2, (string) $user->id);
// ['size' => 34, 'address' => 'something']
```

--------------------------------

### Cart Model Instantiation Example

Source: https://github.com/binafy/laravel-cart

Creates a new Cart instance with a user_id attribute and saves it to the database.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = new Cart(['user_id' => $user->id]);
$cart->save();
```

--------------------------------

### addOption Example: Merging Options

Source: https://github.com/binafy/laravel-cart

Demonstrates merging a key/value pair into existing options. Multiple addOption calls accumulate, preserving previous keys.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->storeItem($product);

$cartItem = $cart->items()->first();
$cartItem->addOption('size', 34);
$cartItem->addOption('address', 'something');

$cartItem->getOptions(); // ['size' => 34, 'address' => 'something']
```

--------------------------------

### decreaseQuantity usage example

Source: https://github.com/binafy/laravel-cart

Example of using decreaseQuantity to subtract 1 from a product's quantity in a cart. Throws RuntimeException if the item is not found.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->decreaseQuantity($product, 1);
```

--------------------------------

### setOption() example

Source: https://github.com/binafy/laravel-cart

Replaces all existing options with ['size' => 34] for the first item of the current user.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

// Replaces all existing options with ['size' => 34]
LaravelCart::driver('database')->setOption('size', 34, null, (string) $user->id);
```

--------------------------------

### getOptions() example

Source: https://github.com/binafy/laravel-cart

Retrieves options for item 2 of the current user. Returns a decoded array like ['size' => 80, 'address' => 'something'].

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$options = LaravelCart::driver('database')->getOptions(2, (string) $user->id);
// ['size' => 80, 'address' => 'something']
```

--------------------------------

### Constructor Example: Creating a CartItem

Source: https://github.com/binafy/laravel-cart

Instantiates a CartItem with initial attributes. The constructor sets the table name from configuration and calls the parent Eloquent constructor.

```php
<?php

use Binafy\LaravelCart\Models\CartItem;

$cartItem = new CartItem([
    'itemable_id' => $product->id,
    'itemable_type' => $product::class,
    'quantity' => 1,
]);
```

--------------------------------

### decreaseQuantity usage example

Source: https://github.com/binafy/laravel-cart

Example of using the database driver's decreaseQuantity method to reduce the quantity of a product in the cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('database')->decreaseQuantity($product, 1, (string) $user->id);
```

--------------------------------

### removeItem usage example

Source: https://github.com/binafy/laravel-cart

Example of removing an item from the session cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('session')->removeItem($product, (string) $user->id);
```

--------------------------------

### createDatabaseDriver() usage example

Source: https://github.com/binafy/laravel-cart

Shows how to retrieve the database driver instance using the driver() method.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$driver = LaravelCart::driver('database'); // LaravelCartDatabase
```

--------------------------------

### updating() example: modifying an existing CartItem

Source: https://github.com/binafy/laravel-cart

Example showing how to update an existing CartItem, triggering the updating() and saving() observers. The itemable type must be Cartable.

```php
<?php

use Binafy\LaravelCart\Models\CartItem;

$cartItem = CartItem::query()->first();
$cartItem->quantity = 5;
$cartItem->save(); // updating() and saving() both run
```

--------------------------------

### removeItem() example

Source: https://github.com/binafy/laravel-cart

Example usage of removeItem() to delete a cart item.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->removeItem($product);
```

--------------------------------

### items() usage example

Source: https://github.com/binafy/laravel-cart

Fetches a cart and iterates over its items to output each item's quantity.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);

foreach ($cart->items as $cartItem) {
    echo $cartItem->quantity;
}
```

--------------------------------

### createSessionDriver() usage example

Source: https://github.com/binafy/laravel-cart

Shows how to retrieve the session driver instance using the driver() method.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$driver = LaravelCart::driver('session'); // LaravelCartSession
```

--------------------------------

### storeItems usage example

Source: https://github.com/binafy/laravel-cart

Shows how to store multiple items at once using the session driver. Each item is an array with 'itemable' and 'quantity'.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('session')->storeItems([
    ['itemable' => $product1, 'quantity' => 2],
    ['itemable' => $product2, 'quantity' => 1],
], (string) $user->id);
```

--------------------------------

### LaravelCartEmptyEvent example listener

Source: https://github.com/binafy/laravel-cart

Example listener that clears a cache when the cart is emptied.

```php
<?php

namespace App\Listeners;

use Binafy\LaravelCart\Events\LaravelCartEmptyEvent;

class ClearCartCache
{
    public function handle(LaravelCartEmptyEvent $event): void
    {
        cache()->forget('cart-summary');
    }
}
```

--------------------------------

### getOption Example: Retrieving a Single Option

Source: https://github.com/binafy/laravel-cart

Shows how to retrieve a single option value using getOption after setting it with setOption. Returns null if the key is absent or options is null.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->storeItem($product);

$cartItem = $cart->items()->first();
$cartItem->setOption('size', 34);

$size = $cartItem->getOption('size'); // 34
```

--------------------------------

### increaseQuantity usage example

Source: https://github.com/binafy/laravel-cart

Shows how to increase the quantity of an item in the session cart. The method throws a RuntimeException if the item is not found.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('session')->increaseQuantity($product, 2, (string) $user->id);
```

--------------------------------

### emptyCart usage example

Source: https://github.com/binafy/laravel-cart

Example of using the database driver's emptyCart method to clear the user's cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('database')->emptyCart((string) $user->id);
```

--------------------------------

### LaravelCartStoreItemEvent example listener

Source: https://github.com/binafy/laravel-cart

Example listener that logs when an item is stored in a cart. Handles the LaravelCartStoreItemEvent.

```php
<?php

namespace App\Listeners;

use Binafy\LaravelCart\Events\LaravelCartStoreItemEvent;

class LogCartItemStored
{
    public function handle(LaravelCartStoreItemEvent $event): void
    {
        logger('An item was stored in a cart.');
    }
}
```

--------------------------------

### cart() relation usage example

Source: https://github.com/binafy/laravel-cart

Fetches the first CartItem and retrieves its owning cart instance.

```php
<?php

use Binafy\LaravelCart\Models\CartItem;

$cartItem = CartItem::query()->first();
$cart = $cartItem->cart()->first(); // Cart instance
```

--------------------------------

### LaravelCartIncreaseQuantityEvent example listener

Source: https://github.com/binafy/laravel-cart

Example listener that tracks quantity increases. The event has no properties, so query the cart if details are needed.

```php
<?php

namespace App\Listeners;

use Binafy\LaravelCart\Events\LaravelCartIncreaseQuantityEvent;

class TrackQuantityIncrease
{
    public function handle(LaravelCartIncreaseQuantityEvent $event): void
    {
        // The event has no properties; query the cart if details are needed.
    }
}
```

--------------------------------

### removeItem usage example

Source: https://github.com/binafy/laravel-cart

Example of using the database driver's removeItem method to remove a product from the cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('database')->removeItem($product, (string) $user->id);
```

--------------------------------

### Get Default Driver with TypeError

Source: https://github.com/binafy/laravel-cart

If the config key 'laravel-cart.driver.default' is absent, get() returns null, violating the string return type and causing a TypeError.

```php
public function getDefaultDriver(): string
{
    return $this->config->get('laravel-cart.driver.default');
}
```

--------------------------------

### Example usage of register() binding

Source: https://github.com/binafy/laravel-cart

Shows how the 'laravel-cart' binding is resolved via the facade or directly. The facade resolves automatically; app('laravel-cart') returns a LaravelCartManager instance.

```php
<?php

// The binding is resolved automatically by the facade:
use Binafy\LaravelCart\LaravelCart;

LaravelCart::storeItem($product);

// Or resolve the manager directly:
$manager = app('laravel-cart'); // LaravelCartManager
```

--------------------------------

### LaravelCartRemoveItemEvent example listener

Source: https://github.com/binafy/laravel-cart

Example listener that recalculates cart summary when an item is removed. Handles the LaravelCartRemoveItemEvent.

```php
<?php

namespace App\Listeners;

use Binafy\LaravelCart\Events\LaravelCartRemoveItemEvent;

class RecalculateCartSummary
{
    public function handle(LaravelCartRemoveItemEvent $event): void
    {
        // Recalculate totals, invalidate caches, etc.
    }
}
```

--------------------------------

### Example listener for LaravelCartDecreaseQuantityEvent

Source: https://github.com/binafy/laravel-cart

Example listener class that handles the decrease quantity event. The event has no properties, so the handle method receives an empty event object.

```php
<?php

namespace App\Listeners;

use Binafy\LaravelCart\Events\LaravelCartDecreaseQuantityEvent;

class TrackQuantityDecrease
{
    public function handle(LaravelCartDecreaseQuantityEvent $event): void
    {
        // The event has no properties.
    }
}
```

--------------------------------

### scopeFirstOrCreateWithStoreItems() usage example

Source: https://github.com/binafy/laravel-cart

Creates a cart with a product and quantity, then fetches the cart separately because the method returns the Builder, not the Cart model.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$query = Cart::query()->firstOrCreateWithStoreItems(
    item: $product,
    quantity: 2,
    userId: (string) $user->id
);

// The method returns the Builder, so fetch the cart separately if needed.
$cart = Cart::query()->where('user_id', $user->id)->first();
```

--------------------------------

### storeItems usage example

Source: https://github.com/binafy/laravel-cart

Stores multiple items at once using the database driver. Throws same errors as Cart::storeItems().

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('database')->storeItems([
    ['itemable' => $product1, 'quantity' => 2],
    ['itemable' => $product2, 'quantity' => 1],
], (string) $user->id);
```

--------------------------------

### storeItem usage example

Source: https://github.com/binafy/laravel-cart

Shows how to store a single item using the database driver, either with a model or an array. Throws RuntimeException if the item is not Cartable.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('database')->storeItem($product, (string) $user->id);

LaravelCart::driver('database')->storeItem([
    'itemable' => $product,
    'quantity' => 3,
], (string) $user->id);
```

--------------------------------

### getDefaultDriver() usage example

Source: https://github.com/binafy/laravel-cart

Shows how to call getDefaultDriver() and change the default driver via config. The default is 'database'.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$driver = LaravelCart::getDefaultDriver(); // "database" by default

config(['laravel-cart.driver.default' => 'session']);
$driver = LaravelCart::getDefaultDriver(); // "session"
```

--------------------------------

### Delete All Items From Cart using emptyCart method

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Empties the entire cart using the `emptyCart` method. The example shows creating or retrieving a cart for a user and then removing all items.

```php
$items = [
    [
        'itemable' => $product1,
        'quantity' => 2,
    ],
    [
        'itemable' => $product2,
        'quantity' => 1,
    ],
    [
        'itemable' => $product3,
        'quantity' => 5,
    ],
];

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->emptyCart();
```

--------------------------------

### increaseQuantity usage example

Source: https://github.com/binafy/laravel-cart

Increases the quantity of a product in the user's cart. Catches RuntimeException when the product is not in the cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

try {
    LaravelCart::driver('database')->increaseQuantity($product, 2, (string) $user->id);
} catch (\RuntimeException $e) {
    // The product is not in this user's cart.
}
```

--------------------------------

### storeItem usage example

Source: https://github.com/binafy/laravel-cart

Shows how to store a single item using the session driver. The first call passes a model, the second passes an array with 'itemable' and 'quantity'. Both require a user ID.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('session')->storeItem($product, (string) $user->id);

LaravelCart::driver('session')->storeItem([
    'itemable' => $product,
    'quantity' => 2,
], (string) $user->id);
```

--------------------------------

### setOption Example: Replacing Options Payload

Source: https://github.com/binafy/laravel-cart

Shows that setOption replaces the entire options payload with the given key/value pair. Only the last setOption call's data remains.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->storeItem($product);

$cartItem = $cart->items()->first();
$cartItem->setOption('size', 34);
$cartItem->setOption('color', 'red');

// Only ['color' => 'red'] remains; setOption replaces the payload.
```

--------------------------------

### itemable() relation usage example

Source: https://github.com/binafy/laravel-cart

Fetches the first CartItem and retrieves its owning itemable model (e.g., a Product instance).

```php
<?php

use Binafy\LaravelCart\Models\CartItem;

$cartItem = CartItem::query()->first();
$product = $cartItem->itemable()->first(); // Product instance
```

--------------------------------

### Example laravel-cart.php configuration file

Source: https://github.com/binafy/laravel-cart

Shows the full structure of the 'config/laravel-cart.php' file with sections for users, carts, cart_items, and driver. With 'foreign_key_type' => 'uuid', the carts migration creates a 'foreignUuid('user_id')' column. The Cart model does not cast the user key, so ensure your user model uses UUIDs and the relevant Eloquent traits.

```php
<?php

// config/laravel-cart.php
return [
    'users' => [
        'table' => 'users',
        'foreign_id' => 'user_id',
        'foreign_key_type' => 'uuid',
    ],

    'carts' => [
        'table' => 'carts',
        'foreign_id' => 'cart_id',
    ],

    'cart_items' => [
        'table' => 'cart_items',
    ],

    'driver' => [
        'default' => 'session',
    ],
];
```

--------------------------------

### Publish all files

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Publish config, migration, and other files using the provider.

```shell
php artisan vendor:publish --provider="Binafy\LaravelCart\Providers\LaravelCartServiceProvider"
```

--------------------------------

### boot() method signature

Source: https://github.com/binafy/laravel-cart

Registers publishable assets. Returns void.

```php
public function boot(): void
```

--------------------------------

### Delete Item From Cart using removeItem method

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Removes a specific item from the cart using the `removeItem` method. The example shows creating or retrieving a cart for a user and then removing a product.

```php
$items = [
    [
        'itemable' => $product1,
        'quantity' => 2,
    ],
    [
        'itemable' => $product2,
        'quantity' => 1,
    ],
    [
        'itemable' => $product3,
        'quantity' => 5,
    ],
];

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cart->removeItem($product1);
```

--------------------------------

### Create cart with storing item

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Create a cart and store an item in one call using firstOrCreateWithStoreItems.

```php
Cart::query()->firstOrCreateWithStoreItems(
    item: $product,
    quantity: 1,
    userId: $user->id
);
```

--------------------------------

### Change driver for facade

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Change the driver for storing or removing items. Default driver is 'database'.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('database')->storeItem($item, $userId|null);
LaravelCart::driver('session')->removeItem($item);
```

--------------------------------

### Add to cart using Driver interface

Source: https://github.com/binafy/laravel-cart

Shows how to type-hint the Driver interface and call storeItem() for both database and session drivers. Requires a concrete-type check to access methods not declared on the interface, such as getOption() and setOption().

```php
<?php

use Binafy\LaravelCart\Drivers\Driver;
use Binafy\LaravelCart\LaravelCart;

function addToCart(Driver $driver, \Illuminate\Database\Eloquent\Model $product, string $userId): void
{
    $driver->storeItem($product, $userId);
}

addToCart(LaravelCart::driver('database'), $product, (string) $user->id);
addToCart(LaravelCart::driver('session'), $product, (string) $user->id);

```

--------------------------------

### Store a new cart using Cart model

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Create or fetch a cart for a user using the Cart model.

```php
use \Binafy\LaravelCart\Models\Cart;

$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
```

--------------------------------

### Implement Cartable interface

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Implement the Cartable interface on a model to enable storing items.

```php
use Binafy\LaravelCart\Cartable;

class Product extends Model implements Cartable
{
    public function getPrice(): int
    {
        //
    }
}
```

--------------------------------

### Catch TypeError for Missing Default Driver Config

Source: https://github.com/binafy/laravel-cart

Catch the TypeError when the config key is missing, then set a default and retry.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

try {
    $driver = LaravelCart::getDefaultDriver();
} catch (\TypeError $e) {
    config(['laravel-cart.driver.default' => 'database']);
    $driver = LaravelCart::getDefaultDriver();
}
```

--------------------------------

### Store item for a cart

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Create a cart, create a CartItem, and save it to the cart's items relation.

```php
$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);
$cartItem = new CartItem([
    'itemable_id' => $itemable->id,
    'itemable_type' => $itemable::class,
    'quantity' => 1,
]);

$cart->items()->save($cartItem);
```

--------------------------------

### Artisan commands to publish config, migrations, or all

Source: https://github.com/binafy/laravel-cart

Commands to publish config, migrations, or everything from this provider. Use the appropriate tag or provider flag.

```bash
# Publish only the config
php artisan vendor:publish --tag="laravel-cart-config"

# Publish only the migrations
php artisan vendor:publish --tag="laravel-cart-migrations"

# Publish everything from this provider
php artisan vendor:publish --provider="Binafy\LaravelCart\Providers\LaravelCartServiceProvider"
```

--------------------------------

### Basic usage of LaravelCart facade

Source: https://github.com/binafy/laravel-cart

Shows how to use the LaravelCart facade with the default driver, explicitly select a driver, and store multiple items. The default driver is database unless changed.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

// Use the configured default driver (database by default)
LaravelCart::storeItem($product);

// Explicitly select a driver
LaravelCart::driver('session')->storeItem($product, $user->id);

// Multiple items
LaravelCart::driver('database')->storeItems([
    ['itemable' => $product1, 'quantity' => 2],
    ['itemable' => $product2, 'quantity' => 1],
]);
```

--------------------------------

### Import Driver Interface

Source: https://github.com/binafy/laravel-cart

Use this import statement to reference the Driver interface in your PHP code.

```php
use Binafy\LaravelCart\Drivers\Driver;
```

--------------------------------

### Publish migrations

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Publish the migration files using the tag 'laravel-cart-migrations'.

```shell
php artisan vendor:publish --tag="laravel-cart-migrations"
```

--------------------------------

### Usage with Cart and LaravelCart

Source: https://github.com/binafy/laravel-cart

Shows how to store a Cartable model in a cart using the Cart model and LaravelCart facade, and calculate the total price.

```php
<?php

use Binafy\LaravelCart\LaravelCart;
use Binafy\LaravelCart\Models\Cart;

$product = Product::query()->findOrFail(1);

// Model-based storage
$cart = Cart::query()->firstOrCreate(['user_id' => auth()->id()]);
$cart->storeItem($product);

// Facade-based storage
LaravelCart::driver('database')->storeItem($product);

// Total price uses getPrice() for every item
$total = $cart->calculatedPriceByQuantity();
```

--------------------------------

### Import Cartable Interface

Source: https://github.com/binafy/laravel-cart

Import the Cartable interface from the Binafy\LaravelCart namespace.

```php
use Binafy\LaravelCart\Cartable;
```

--------------------------------

### Store item using storeItem method

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Store an item using the storeItem method, which accepts a model or an array.

```php
$cart = Cart::query()->firstOrCreate(['user_id' => $user->id]);

// Model
$cart->storeItem($itemable);

// Array
$item['itemable'] = $itemable;
$item['quantity'] = 1;
$cart->storeItem($item);
```

--------------------------------

### scopeFirstOrCreateWithStoreItems() method signature

Source: https://github.com/binafy/laravel-cart

Finds or creates a cart for the user, creates one CartItem, saves it, and dispatches LaravelCartStoreItemEvent. The $item must implement Cartable; otherwise an exception is thrown.

```php
public function scopeFirstOrCreateWithStoreItems(
    Builder $query,
    Model $item,
    int $quantity = 1,
    ?string $userId = null
): Builder
```

--------------------------------

### register() method signature

Source: https://github.com/binafy/laravel-cart

Merges package config and binds the manager. Returns void.

```php
public function register(): void
```

--------------------------------

### User configuration for foreign key type

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Configure the foreign key type in the config file. Options: uuid, ulid, id.

```php
'users' => [
    ...

    /*
     * Specify the type of foreign key being used (e.g., 'id', 'uuid', 'ulid').
     * For non-standard IDs, make sure to add the relevant traits to your models.
     */
    'foreign_key_type' => 'id', // Options: uuid, ulid, id
],
```

--------------------------------

### Change carts table name at runtime for Cart model

Source: https://github.com/binafy/laravel-cart

Sets 'laravel-cart.carts.table' to 'custom_carts' at runtime. Table names are read when a model is constructed, so this affects models created after the change. The example shows that a new Cart instance will use the custom table name.

```php
<?php

config(['laravel-cart.carts.table' => 'custom_carts']);

$cart = new \Binafy\LaravelCart\Models\Cart();
// $cart->getTable() === 'custom_carts'
```

--------------------------------

### Resolving a driver explicitly with LaravelCart::driver()

Source: https://github.com/binafy/laravel-cart

Use this snippet to explicitly resolve the 'database' and 'session' drivers via the LaravelCart facade. The driver method returns a cached driver instance, creating it through create{Name}Driver() when needed. This example shows storing an item with each driver.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

$database = LaravelCart::driver('database');
$session = LaravelCart::driver('session');

$database->storeItem($product, $user->id);
$session->storeItem($product, $user->id);
```

--------------------------------

### Publish and run migrations

Source: https://github.com/binafy/laravel-cart

Publishes the package migrations and runs them. For Laravel 11+, the service provider uses publishesMigrations(); for older versions it uses publishes().

```bash
php artisan vendor:publish --tag="laravel-cart-migrations"
php artisan migrate
```

--------------------------------

### Catching Exception for non-Cartable item in scope

Source: https://github.com/binafy/laravel-cart

Shows how to catch the \Exception thrown when using Cart::query()->firstOrCreateWithStoreItems() with a non-Cartable item. The exact message is 'The item must be an instance of Cartable'. Since it's a plain \Exception, catch it before more specific exception types if needed.

```php
<?php

use Binafy\LaravelCart\Models\Cart;

try {
    Cart::query()->firstOrCreateWithStoreItems($model, 1, (string) $user->id);
} catch (\Exception $e) {
    if ($e->getMessage() === 'The item must be an instance of Cartable') {
        // Handle a non-Cartable item.
    }

    throw $e;
}
```

--------------------------------

### Catching \Error for option methods on session driver

Source: https://github.com/binafy/laravel-cart

Attempts to call setOption() on the session driver, which is not implemented, resulting in a PHP \Error. Options are only supported by the database driver.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

try {
    LaravelCart::driver('session')->setOption('size', 34);
} catch (\Error $e) {
    // Options are only supported by the database driver.
}
```

--------------------------------

### getOptions() signature

Source: https://github.com/binafy/laravel-cart

Returns all options of a cart item as a decoded array. Throws \Error if the cart has no items.

```php
public function getOptions(?int $itemId = null, ?string $userId = null): mixed
```

--------------------------------

### storeItems(array $items, ?string $userId = null): Driver

Source: https://github.com/binafy/laravel-cart

Stores multiple items by delegating to `storeItem()` for each entry. Accepts an array of item arrays, each with 'itemable' and 'quantity'.

```APIDOC
## storeItems(array $items, ?string $userId = null): Driver

### Description
Stores multiple items by delegating to `storeItem()` for each entry. Accepts an array of item arrays, each with 'itemable' and 'quantity'.

### Method
storeItems

### Signature
```php
public function storeItems(array $items, ?string $userId = null): Driver;
```

### Parameters
- `$items` (array) - Required - Array of item arrays, each with `itemable` and `quantity`.
- `$userId` (string|null) - Optional - User identifier; defaults to `auth()->id()`.

### Return Type
- `Driver` - The driver instance.

### Throws / Rejects
Same as `storeItem()` for each element.

### Source
`src/Drivers/Driver.php:11`
```

--------------------------------

### Catching RuntimeException for item not found

Source: https://github.com/binafy/laravel-cart

Shows how to catch the RuntimeException with message 'The item not found' when increasing quantity. The catch block checks the message and rethrows if it doesn't match.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

try {
    LaravelCart::driver('database')->increaseQuantity($product, 2);
} catch (\RuntimeException $e) {
    if ($e->getMessage() === 'The item not found') {
        // The product is not in the current user's cart.
    }

    throw $e;
}
```

--------------------------------

### Option Method on Empty Cart

Source: https://github.com/binafy/laravel-cart

Option methods call $items->first()->getOption(...) without null check. When the cart has no items, first() returns null and PHP raises an \Error.

```php
return $items->first()->getOption($option);
```

--------------------------------

### Import CartItem Model

Source: https://github.com/binafy/laravel-cart

Use this import to reference the CartItem model in your code.

```php
use Binafy\LaravelCart\Models\CartItem;
```

--------------------------------

### Cart::scopeFirstOrCreateWithStoreItems() throwing Exception

Source: https://github.com/binafy/laravel-cart

Throws a plain \Exception when the item is not an instance of Cartable. Used in Cart::scopeFirstOrCreateWithStoreItems() before creating the cart.

```php
if (! $item instanceof Cartable) {
    throw new \Exception('The item must be an instance of Cartable');
}
```

--------------------------------

### Catching RuntimeException for non-Cartable item

Source: https://github.com/binafy/laravel-cart

Shows how to catch the RuntimeException thrown when storing a non-Cartable item. The exact message is 'The item must be an instance of Binafy\LaravelCart\Cartable'.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

try {
    LaravelCart::driver('database')->storeItem($model);
} catch (\RuntimeException $e) {
    if ($e->getMessage() === 'The item must be an instance of Binafy\LaravelCart\Cartable') {
        // The model does not implement Cartable.
    }

    throw $e;
}
```

--------------------------------

### getOptions

Source: https://github.com/binafy/laravel-cart

Returns all options of a cart item as a decoded array. If no item ID is provided, the first item is selected.

```APIDOC
## getOptions

### Description
Returns all options of a cart item as a decoded array.

### Signature
```php
public function getOptions(?int $itemId = null, ?string $userId = null): mixed
```

### Parameters
- `$itemId` (int|null) - Optional - Cart item primary key. `null` selects the first item.
- `$userId` (string|null) - Optional - User identifier; defaults to `auth()->id()`.

### Return Type
- `mixed` - Decoded JSON options (`array` or `null`).

### Throws / Rejects
- `\Error` - The cart has no items.

### Request Example
```php
<?php

use Binafy\LaravelCart\LaravelCart;

$options = LaravelCart::driver('database')->getOptions(2, (string) $user->id);
// ['size' => 80, 'address' => 'something']
```
```

--------------------------------

### Increase Quantity using increaseQuantity method

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Increases the quantity of an item in the cart. The default quantity increment is 1 if not specified.

```php
$cart->increaseQuantity(item: $item, quantity: 2); // By default quantity is 1
```

--------------------------------

### getPrice() Method Signature

Source: https://github.com/binafy/laravel-cart

Signature of the getPrice() method that must be implemented by Cartable models.

```php
public function getPrice(): float;
```

--------------------------------

### storeItem(Model|array $item, ?string $userId = null): Driver

Source: https://github.com/binafy/laravel-cart

Stores one item in the user's cart. Accepts a Cartable model or an array with 'itemable' and 'quantity'. Returns the driver instance for fluent chaining.

```APIDOC
## storeItem(Model|array $item, ?string $userId = null): Driver

### Description
Stores one item in the user's cart. Accepts a Cartable model or an array with 'itemable' and 'quantity'. Returns the driver instance for fluent chaining.

### Method
storeItem

### Signature
```php
public function storeItem(Model|array $item, ?string $userId = null): Driver;
```

### Parameters
- `$item` (Model|array) - Required - A `Cartable` model, or an array containing `itemable` (a `Cartable` model) and `quantity` (int).
- `$userId` (string|null) - Optional - User identifier. When `null`, the driver calls `auth()->id()`.

### Return Type
- `Driver` - The driver instance, allowing fluent chaining. Concrete implementations declare `static`.

### Throws / Rejects
- `\RuntimeException` - The item is not an instance of `Cartable` (database driver for both forms; session driver for array form).
- `\TypeError` - `$userId` is `null` and `auth()->id()` returns `null`, because `resolveUserId()` is declared to return `string`.

### Source
`src/Drivers/Driver.php:9`
```

--------------------------------

### creating(CartItem $cartItem): void signature

Source: https://github.com/binafy/laravel-cart

Method signature for the creating observer hook that runs before a new CartItem is inserted.

```php
public function creating(CartItem $cartItem): void
```

--------------------------------

### Laravel Cart Facade usage

Source: https://github.com/binafy/laravel-cart/blob/1.x/README.md

Use the Laravel Cart facade to store items with or without specifying a driver.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

LaravelCart::driver('session')->storeItem($item, $userId|null);
LaravelCart::storeItem($item $userId|null);
```

--------------------------------

### setOption() signature

Source: https://github.com/binafy/laravel-cart

Replaces the item's entire options payload with [$key => $value]. Throws \Error if the cart has no items.

```php
public function setOption(string $key, mixed $value, ?int $itemId = null, ?string $userId = null): static
```

--------------------------------

### LaravelCartStoreItemEvent constructor

Source: https://github.com/binafy/laravel-cart

Constructor with no parameters.

```php
public function __construct()
```

--------------------------------

### setOption

Source: https://github.com/binafy/laravel-cart

Replaces the item's entire options payload with a single key-value pair. Returns the same driver instance for chaining.

```APIDOC
## setOption

### Description
Replaces the item's entire options payload with `[$key => $value]`.

### Signature
```php
public function setOption(string $key, mixed $value, ?int $itemId = null, ?string $userId = null): static
```

### Parameters
- `$key` (string) - Required - Option key.
- `$value` (mixed) - Required - Option value.
- `$itemId` (int|null) - Optional - Cart item primary key. `null` selects the first item.
- `$userId` (string|null) - Optional - User identifier; defaults to `auth()->id()`.

### Return Type
- `static` - The same driver instance.

### Throws / Rejects
- `\Error` - The cart has no items.

### Request Example
```php
<?php

use Binafy\LaravelCart\LaravelCart;

// Replaces all existing options with ['size' => 34]
LaravelCart::driver('database')->setOption('size', 34, null, (string) $user->id);
```
```

--------------------------------

### emptyCart(?string $userId = null): Driver

Source: https://github.com/binafy/laravel-cart

Removes every item from the cart. Returns the driver instance.

```APIDOC
## emptyCart(?string $userId = null): Driver

### Description
Removes every item from the cart. Returns the driver instance.

### Method
emptyCart

### Signature
```php
public function emptyCart(?string $userId = null): Driver;
```

### Parameters
- `$userId` (string|null) - Optional - User identifier; defaults to `auth()->id()`.

### Return Type
- `Driver` - The driver instance.

### Throws / Rejects
No explicit exception.

### Source
`src/Drivers/Driver.php:19`
```

--------------------------------

### Error handling and driver selection with LaravelCart

Source: https://github.com/binafy/laravel-cart

Demonstrates catching a RuntimeException when increasing quantity fails, reading the default driver name, and switching the default driver at runtime. The error message is 'The item not found' when the product is not in the cart.

```php
<?php

use Binafy\LaravelCart\LaravelCart;

try {
    LaravelCart::driver('database')->increaseQuantity($product, 3);
} catch (\RuntimeException $e) {
    // "The item not found" when the product is not in the cart
    report($e);
}

// Read the default driver name
$default = LaravelCart::getDefaultDriver(); // "database"

// Switch the default for the rest of the request
LaravelCart::setDefaultDriver('session');
```

--------------------------------

### Cart::__construct(array $attributes = [])

Source: https://github.com/binafy/laravel-cart

Constructor for the Cart model. Initializes Eloquent attributes and sets the table from the configuration.

```APIDOC
## Cart::__construct(array $attributes = [])

### Description
Constructor for the Cart model. Initializes Eloquent attributes and sets the table from the configuration.

### Parameters
- **$attributes** (array) - Optional - Initial Eloquent attributes. The table is set from `laravel-cart.carts.table`.

### Source
`src/Models/Cart.php:33-38`
```

--------------------------------

### CartItemObserve creating() throws RuntimeException for non-Cartable itemable_type

Source: https://github.com/binafy/laravel-cart

Throws 'The item must be an instance of Cartable' when the itemable_type is not an instance of Cartable. The same check appears in updating() and saving() hooks.

```php
public function creating(CartItem $cartItem): void
{
    if (! new $cartItem->itemable_type instanceof Cartable) {
        throw new \RuntimeException('The item must be an instance of Cartable');
    }
}
```

--------------------------------

### Import LaravelCart Facade

Source: https://github.com/binafy/laravel-cart

Import the LaravelCart facade class to use its static methods for accessing the configured cart driver.

```php
use Binafy\LaravelCart\LaravelCart;
```

--------------------------------

### Publish Laravel Cart config

Source: https://github.com/binafy/laravel-cart

Run this artisan command to publish the package configuration file to config/laravel-cart.php. The tag 'laravel-cart-config' is used for publishing.

```bash
php artisan vendor:publish --tag="laravel-cart-config"
```

--------------------------------

### Import CartItemObserve

Source: https://github.com/binafy/laravel-cart

Import the CartItemObserve observer class from the Laravel Cart package.

```php
use Binafy\LaravelCart\Observers\CartItemObserve;
```
Tokens:
Raw