Cart Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require darryldecode/cart
   

   Add to config/app.php:

   'providers' => [
       Darryldecode\Cart\CartServiceProvider::class,
   ],
   'aliases' => [
       'Cart' => Darryldecode\Cart\Facades\CartFacade::class,
   ]
   

2. Publish Config (Optional):

   php artisan vendor:publish --provider="Darryldecode\Cart\CartServiceProvider" --tag="config"
   

   (Edit config/cart.php for customization like session driver, default conditions, etc.)

3. First Use Case: Add an item to the cart in a controller:

   use Cart;
   
   public function addToCart(Request $request) {
       $product = Product::find($request->product_id);
       Cart::add([
           'id' => $product->id,
           'name' => $product->name,
           'qty' => 1,
           'price' => $product->price,
           'attributes' => ['color' => $request->color],
       ]);
       return redirect()->back()->with('success', 'Added to cart!');
   }
   

4. View Cart Contents:

   $cartItems = Cart::getContent();
   $total = Cart::getTotal();
   

   (Use in Blade templates with @foreach($cartItems as $item))

Implementation Patterns

Core Workflows

1. Adding Items:

   • Basic:

     Cart::add([
         'id' => $id,
         'name' => $name,
         'qty' => $qty,
         'price' => $price,
         'attributes' => ['key' => 'value'], // Optional
     ]);
     

   • From a Model:

     Cart::add($productModel->toCartArray());
     

     (Define toCartArray() in your model for consistency.)

2. Updating Items:

   Cart::update($id, [
       'qty' => 3, // Update quantity
       'price' => $newPrice, // Update price
   ]);
   

3. Removing Items:

   Cart::remove($id); // Remove by ID
   Cart::remove($id, $rowId); // Remove specific row (if duplicates allowed)
   Cart::clear(); // Empty entire cart
   

4. Conditions (Rules):

   • Add Conditions:

     Cart::condition(function($cart) {
         if ($cart->totalQty > 10) {
             return ['max_items' => 'You cannot have more than 10 items!'];
         }
         return true;
     }, 'max_items');
     

   • Apply Conditions:

     Cart::add($item, ['conditions' => ['max_items']]);
     

5. Persistence:

   • Session Driver (Default): Automatic via Laravel’s session.
   • Database Driver: Configure in config/cart.php:

     'driver' => 'database',
     'table_name' => 'cart_items',
     

     (Run migrations after publishing config.)

6. Taxes and Discounts:

   Cart::tax([10 => 10]); // 10% tax on $10 items
   Cart::discount($code); // Apply discount code
   

7. Checkout:

   $order = Cart::getContent(); // Get items for order processing
   Cart::clear(); // Clear cart after purchase
   

Integration Tips

1. Blade Directives: Use @cart directives for reusable cart logic in views:

   @cart
       @foreach($cartItems as $item)
           <tr>
               <td>{{ $item->name }}</td>
               <td>{{ $item->qty }}</td>
           </tr>
       @endforeach
   @endcart
   

2. Middleware for Cart Access:

   public function handle($request, Closure $next) {
       view()->share('cart', Cart::getContent());
       return $next($request);
   }
   

   (Add to HandleCartData middleware.)

3. API Responses:

   return response()->json([
       'cart' => Cart::getContent(),
       'total' => Cart::getTotal(),
   ]);
   

4. Testing:

   • Use Cart::instance('test')->add(...) for isolated test carts.
   • Reset carts in tests:

     Cart::instance('test')->clear();
     

5. Localization:

   • Override labels (e.g., "Cart", "Checkout") in config/cart.php:

     'locale' => [
         'prefix' => 'cart.',
     ],
     

   • Publish language files:

     php artisan vendor:publish --provider="Darryldecode\Cart\CartServiceProvider" --tag="lang"
     

Gotchas and Tips

Pitfalls

1. Session Driver Issues:

   • If cart items disappear, ensure:
     • Session driver is configured (config/session.php).
     • Session is started before cart operations (e.g., in AppServiceProvider boot method).
   • Fix: Explicitly start session:

     session()->start();
     Cart::add(...);
     

2. Duplicate Items:

   • By default, items are merged if they have the same id and attributes. To allow duplicates:

     Cart::add($item, ['associate' => false]);
     

   • Warning: This can bloat your cart data. Use sparingly.

3. Price/Quantity Updates:

   • Updating price or qty after addition may not reflect in the cart until the next request. Use Cart::update() to force changes:

     Cart::update($id, ['qty' => $newQty, 'price' => $newPrice]);
     

4. Database Driver Quirks:

   • If using the database driver, ensure:
     • The cart_items table exists (run migrations).
     • The user_id column is populated if using Cart::setUser().
   • Migration Tip: Publish and customize migrations:

     php artisan vendor:publish --provider="Darryldecode\Cart\CartServiceProvider" --tag="migrations"
     

5. Condition Conflicts:

   • Conditions are evaluated in order. If multiple conditions trigger, the first one’s message will override others. Use unique condition names (e.g., max_items, min_order_value).

6. Caching:

   • Cart data is cached per session. Avoid long-lived sessions in shared environments (e.g., public kiosks).

Debugging Tips

1. Log Cart Contents:

   \Log::debug('Cart Contents:', ['items' => Cart::getContent()]);
   

2. Check Conditions:

   • Temporarily disable conditions to isolate issues:

     Cart::condition(function() { return true; }, 'debug_mode');
     

3. Verify Session Data:

   \Log::debug('Session Cart:', ['cart' => session('cart')]);
   

4. Clear Stale Data:

   • For database driver, manually truncate the cart_items table if corrupted:

     php artisan db:table --truncate cart_items
     

Extension Points

1. Custom Drivers:

   • Implement Darryldecode\Cart\Contracts\CartInterface for custom storage (e.g., Redis, Elasticsearch).
   • Bind your driver in the service provider:

     $this->app->bind(
         'Darryldecode\Cart\Contracts\CartInterface',
         YourCustomCart::class
     );
     

2. Event Listeners:

   • Listen for cart events (e.g., cart.item.added):

     Cart::add($item);
     event(new \Darryldecode\Cart\Events\CartItemAdded($item));
     

   • Register listeners in EventServiceProvider:

     protected $listen = [
         'Darryldecode\Cart\Events\CartItemAdded' => [
             YourListener::class,
         ],
     ];
     

3. Custom Attributes:

   • Extend the CartItem model by binding a custom model:

     $this->app->bind(
         'Darryldecode\Cart\CartItem',
         YourCustomCartItem::class
     );
     

4. API Resources:

   • Transform cart items into API responses:

     return new CartResource(Cart::getContent());
     

5. Webhooks:

   • Trigger external services (e.g., inventory updates) via cart events:

     Cart::add($item);
     \Http::post('https://inventory-api.com/update', ['sku' => $item->id, 'qty' => $item->qty]);