Ecommerce Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jmrashed/ecommerce
   php artisan vendor:publish --provider="Jmrashed\Ecommerce\EcommerceServiceProvider" --tag="migrations"
   php artisan migrate
   php artisan ecommerce:install
   

   • Run php artisan ecommerce:install to generate config, seeders, and default assets.

2. First Use Case: Adding a Product

   use Jmrashed\Ecommerce\Models\Product;
   
   // Create a simple product
   $product = Product::create([
       'name' => 'Premium T-Shirt',
       'slug' => 'premium-tshirt',
       'price' => 29.99,
       'description' => 'High-quality cotton t-shirt',
       'sku' => 'TSHIRT-001',
       'stock' => 50,
   ]);
   
   // Add a variant (e.g., size/color)
   $product->variants()->create([
       'name' => 'Black - Medium',
       'price' => 29.99,
       'sku' => 'TSHIRT-001-BK-M',
       'stock' => 30,
   ]);
   

   • Access the Admin Panel at /admin/ecommerce (configured in config/ecommerce.php).

Where to Look First

• Config File: config/ecommerce.php (payment gateways, currencies, tax settings).
• Artisan Commands:
  • php artisan ecommerce:seed (populate demo data).
  • php artisan ecommerce:clear-cache (clear compiled views/cache).
• Blade Views: resources/views/vendor/ecommerce/ (customize templates).
• API Routes: routes/api.php (predefined endpoints for products, cart, orders).

Implementation Patterns

Core Workflows

1. Product Management

• CRUD with Variants/Attributes:

  // Create a product with attributes (e.g., color, size)
  $product = Product::create([
      'name' => 'Wireless Earbuds',
      'price' => 99.99,
  ]);
  
  $product->attributes()->createMany([
      ['name' => 'Color', 'value' => 'Black'],
      ['name' => 'Color', 'value' => 'White'],
  ]);
  
  // Assign variants dynamically
  $product->variants()->create([
      'name' => 'Black',
      'price' => 99.99,
      'sku' => 'EBUD-001-BK',
      'stock' => 100,
      'attribute_values' => ['Black'],
  ]);
  

• Bulk Import: Use php artisan ecommerce:import with a CSV file (configured in config/ecommerce.php).

2. Cart & Checkout

• Add to Cart (API/Controller):

  use Jmrashed\Ecommerce\Facades\Cart;
  
  // Add product to cart (with variant)
  Cart::add([
      'product_id' => $product->id,
      'variant_id' => $variant->id,
      'quantity' => 2,
  ]);
  
  // Get cart total
  $total = Cart::getTotal();
  

• Checkout Flow:
  • Use CheckoutService to validate cart, apply coupons, and process payments.
  • Example:

    $checkout = app(\Jmrashed\Ecommerce\Services\CheckoutService::class);
    $order = $checkout->process([
        'payment_method' => 'stripe',
        'coupon_code' => 'SAVE10',
    ]);
    

3. Payments

• Stripe/PayPal Integration: Configure gateways in config/ecommerce.php:

  'payment_gateways' => [
      'stripe' => [
          'enabled' => true,
          'key' => env('STRIPE_KEY'),
          'secret' => env('STRIPE_SECRET'),
      ],
      'paypal' => [
          'enabled' => true,
          'client_id' => env('PAYPAL_CLIENT_ID'),
          'secret' => env('PAYPAL_SECRET'),
      ],
  ],
  

  • Process payment:

    $payment = app(\Jmrashed\Ecommerce\Services\PaymentService::class);
    $result = $payment->charge($order->id, 'stripe');
    

4. Inventory & Orders

• Track Inventory:

  $variant->decrement('stock', 2); // Deduct stock on order
  

• Order Status Workflow: Use OrderService to update statuses:

  $order->updateStatus('shipped');
  

5. API Endpoints

• Predefined routes for:
  • GET /api/products (with filters: ?category=electronics&price[min]=50).
  • POST /api/cart (add/remove items).
  • POST /api/checkout (process order).
• Customize in routes/api.php:

  Route::prefix('api/ecommerce')->group(function () {
      Route::resource('products', \Jmrashed\Ecommerce\Http\Controllers\Api\ProductController::class);
      // Add more routes as needed
  });
  

Integration Tips

1. Modular Services:

   • Inject services into controllers:

     public function __construct(
         private CartService $cartService,
         private OrderService $orderService
     ) {}
     

   • Override services in AppServiceProvider:

     public function register()
     {
         $this->app->bind(
             \Jmrashed\Ecommerce\Services\CartService::class,
             \App\Services\CustomCartService::class
         );
     }
     

2. Event Listeners:

   • Extend functionality via events (e.g., OrderCreated, PaymentSucceeded):

     // Listen to order creation
     event(new OrderCreated($order));
     

   • Publish events:

     php artisan vendor:publish --tag="ecommerce-events"
     

3. Frontend Integration:

   • Use Blade directives for cart/wishlist:

     @ecommerceCart
     @ecommerceWishlist
     

   • Customize views in resources/views/vendor/ecommerce/.

4. Testing:

   • Use factories and seeders:

     $product = Product::factory()->create();
     $variant = Variant::factory()->for($product)->create();
     

   • Test API endpoints with php artisan test.

Gotchas and Tips

Pitfalls

1. Payment Gateway Configuration:

   • Issue: Payments fail silently if API keys are missing.
   • Fix: Verify config/ecommerce.php and environment variables:

     STRIPE_KEY=your_key
     STRIPE_SECRET=your_secret
     

   • Debug: Check logs/ecommerce.log for payment errors.

2. Stock Management:

   • Issue: Race conditions when multiple users purchase the same item.
   • Fix: Use database transactions:

     DB::transaction(function () use ($variant, $quantity) {
         $variant->decrement('stock', $quantity);
         // Create order
     });
     

3. Variant Attribute Sync:

   • Issue: Variants may lose attribute associations if not saved correctly.
   • Fix: Always attach attribute_values as an array when creating variants:

     $variant->attribute_values()->attach(['Black', 'Medium']);
     

4. Caching:

   • Issue: Product listings or cart data may not update immediately.
   • Fix: Clear cache after critical updates:

     php artisan ecommerce:clear-cache
     

     Or manually:

     \Jmrashed\Ecommerce\Facades\Cache::clear();
     

5. Admin Panel Permissions:

   • Issue: Unauthorized access to /admin/ecommerce.
   • Fix: Configure middleware in app/Http/Kernel.php:

     'admin' => [
         \App\Http\Middleware\AdminMiddleware::class,
         \Jmrashed\Ecommerce\Http\Middleware\EcommerceAdmin::class,
     ],
     

Debugging Tips

1. Log Everything:

   • Enable debug mode in config/ecommerce.php:

     'debug' => env('APP_DEBUG', false),
     

   • Check logs at storage/logs/ecommerce.log.

2. Database Seeds:

   • Reset and reseed data:

     php artisan migrate:fresh --seed
     php artisan ecommerce:seed
     

3. API Debugging:

   • Use Postman or Laravel Debugbar to inspect requests/responses:

     // Enable debugbar in AppServiceProvider
     $this->app->register(\Barryvdh\Debugbar\ServiceProvider::class);