Core Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require shopperlabs/core
   

   Ensure your composer.json specifies Laravel version constraints (e.g., ^10.0).

2. Publish Assets:

   php artisan vendor:publish --provider="Shopper\Core\ShopperServiceProvider"
   

   This generates config (config/shopper.php) and migrations.

3. Run Migrations:

   php artisan migrate
   

   Creates tables for products, carts, orders, etc.

4. Basic Setup:

   • Configure config/shopper.php (e.g., default currency, tax settings).
   • Bind the package’s service container interfaces in AppServiceProvider:

     $this->app->bind(
         \Shopper\Core\Contracts\OrderRepository::class,
         \Shopper\Core\Repositories\EloquentOrderRepository::class
     );
     

5. First Use Case: Create a product via Tinker or a controller:

   use Shopper\Core\Models\Product;
   
   $product = Product::create([
       'name' => 'Test Product',
       'price' => 9.99,
       'sku' => 'SKU123',
   ]);
   

Where to Look First

• Documentation: Check vendor/shopperlabs/core/src/Shopper/Core/README.md for basic usage (likely minimal).
• Models: Inspect src/Shopper/Core/Models/ for Product, Cart, Order, etc., to understand relationships.
• Service Providers: Review ShopperServiceProvider for bootstrapped services and bindings.
• Migrations: Examine database/migrations/ for schema expectations (e.g., shopper_products table structure).

Implementation Patterns

Core Workflows

1. Product Management

• CRUD Operations: Use Eloquent for products (inherits from Shopper\Core\Models\Product):

  // Create
  $product = Product::create([...]);
  
  // Query
  $products = Product::with('category')->where('price', '>', 10)->get();
  

• Inventory: Extend the Product model to add custom inventory logic:

  class Product extends \Shopper\Core\Models\Product
  {
      public function updateInventory(int $quantityChange)
      {
          $this->stock -= $quantityChange;
          $this->save();
      }
  }
  

2. Cart Operations

• Add to Cart: Use the Cart facade or service:

  use Shopper\Core\Facades\Cart;
  
  Cart::add($productId, $quantity = 1, $options = []);
  

• Cart Persistence: Bind a custom cart repository to handle user-specific carts:

  $this->app->bind(
      \Shopper\Core\Contracts\CartRepository::class,
      \App\Repositories\SessionCartRepository::class
  );
  

3. Checkout Flow

• Order Creation: Use the Order service to create orders from carts:

  use Shopper\Core\Services\OrderService;
  
  $order = app(OrderService::class)->createFromCart($cartId, $user);
  

• Order Events: Listen for order events to trigger actions (e.g., notifications):

  event(new \Shopper\Core\Events\OrderCreated($order));
  

4. Payments

• Gateway Integration: Configure payment gateways in config/shopper.php:

  'payments' => [
      'gateways' => [
          'stripe' => [
              'enabled' => true,
              'key' => env('STRIPE_KEY'),
          ],
      ],
  ],
  

  Use the Payment facade:

  use Shopper\Core\Facades\Payment;
  
  $paymentIntent = Payment::createIntent($order, 'stripe');
  

Integration Tips

Laravel Ecosystem

• Service Container: Override default implementations:

  $this->app->singleton(\Shopper\Core\Contracts\TaxCalculator::class, function ($app) {
      return new \App\Services\CustomTaxCalculator();
  });
  

• Events: Extend core events (e.g., OrderPaid) in your EventServiceProvider:

  protected $listen = [
      \Shopper\Core\Events\OrderPaid::class => [
          \App\Listeners\SendOrderConfirmation::class,
      ],
  ];
  

• Middleware: Protect admin routes:

  Route::middleware(['auth', 'can:manage-orders'])->group(function () {
      Route::resource('orders', \App\Http\Controllers\OrderController::class);
  });
  

Custom Extensions

• Model Traits: Add custom behavior to core models:

  use Shopper\Core\Models\Product;
  
  class Product extends Product
  {
      use \App\Traits\ProductAnalytics;
  }
  

• View Composers: Override package views by publishing and extending:

  // config/view.php
  'composers' => [
      'shopper::products.index' => \App\View\Composers\ProductComposer::class,
  ];
  

API-First Approach

• API Resources: Use Laravel’s API resources to shape responses:

  namespace App\Http\Resources;
  
  use Shopper\Core\Models\Order;
  use Illuminate\Http\Resources\Json\JsonResource;
  
  class OrderResource extends JsonResource
  {
      public function toArray($request)
      {
          return [
              'id' => $this->id,
              'items' => OrderItemResource::collection($this->items),
              'status' => $this->status,
          ];
      }
  }
  

• GraphQL: If using Laravel GraphQL, create resolvers for Shopper models:

  type Order {
      id: ID!
      items: [OrderItem!]!
      status: String!
  }
  

Gotchas and Tips

Pitfalls

1. Undocumented Assumptions:

   • The package may assume specific database collations (e.g., utf8mb4) or table engines (e.g., InnoDB). Verify in migrations.
   • Fix: Run migrations in a staging environment first and inspect generated SQL.

2. Naming Conflicts:

   • Core models like Product or Order may conflict with existing models.
   • Fix: Use table prefixes (e.g., shopper_products) or namespace models:

     class Product extends \Shopper\Core\Models\Product {}
     

3. Transaction Handling:

   • The package might not handle transactions for complex operations (e.g., cart → order conversion).
   • Fix: Wrap critical operations in Laravel transactions:

     DB::transaction(function () {
         $order = app(OrderService::class)->createFromCart($cartId, $user);
     });
     

4. Caching Quirks:

   • Aggressive caching (e.g., Cache::remember) could cause stale data.
   • Fix: Use tags or event-based cache invalidation:

     event(new \Shopper\Core\Events\ProductUpdated($product));
     

5. Payment Gateway Lock-in:

   • The package may tightly couple payment logic to specific gateways (e.g., Stripe).
   • Fix: Abstract gateways via interfaces:

     $this->app->bind(
         \Shopper\Core\Contracts\PaymentGateway::class,
         \App\Services\CustomPaymentGateway::class
     );
     

Debugging Tips

1. Log Configuration: Enable debug logging in config/shopper.php:

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

   Check logs at storage/logs/laravel.log for package-specific entries.

2. Query Logging: Use Laravel Debugbar to inspect queries:

   if (app()->environment('local')) {
       $bar = app(\Barryvdh\Debugbar\Debugbar::class);
   }
   

3. Event Debugging: Listen for all events in AppServiceProvider:

   public function boot()
   {
       if (app()->environment('local')) {
           \Shopper\Core\Events\Event::listen(function ($event) {
               \Log::info("Event fired: {$event::class}", $event->toArray());
           });
       }
   }
   

4. Service Container Inspection: Dump bindings to verify overrides:

   dd(app()->bindings());
   

Configuration Quirks

1. Environment Variables: The package may not use Laravel’s .env conventions (e.g., SHOPPER_* prefixes).

   • Fix: Override in config/shopper.php:

     'currency' => env('CURRENCY', 'USD'),
     

2. Default Values: Some settings may lack defaults, causing runtime errors.

   • **