Getting Started

Minimal Steps

Install the CLI Tool Ensure you have the Shopper CLI installed in your Laravel project:
```
composer require shopperlabs/shopper
```
Install a Starter Kit Use the provided command to scaffold a kit (e.g., Livewire storefront):
```
php artisan shopper:kit:install shopperlabs/livewire-starter-kit
```
- The CLI will:
  - Clone/copy files into your project (e.g., resources/views/storefront/, app/Http/Controllers/Storefront/).
  - Install dependencies (e.g., Livewire, Alpine.js, or custom packages).
  - Run post-install hooks (e.g., publish config files, set up routes).
Verify Installation Check for:
- New routes in routes/web.php (e.g., /storefront, /checkout).
- Updated composer.json with new dependencies.
- Scaffolded views/controllers in your project.
First Use Case: Product Page After installation, test the scaffolded product page (e.g., /products/{slug}). Modify the Livewire component (resources/views/storefront/products/show.blade.php) to customize product display logic.

Implementation Patterns

Core Workflows

Extending Scaffolded Features
- Livewire Components: The Livewire starter kit includes pre-built components (e.g., ProductCard, CartDropdown). Extend them by:
  - Copying the component to your project (e.g., app/Http/Livewire/CustomProductCard.php).
  - Overriding methods like mount(), render(), or updatedProperty().
  - Example:
```
// app/Http/Livewire/CustomProductCard.php
namespace App\Http\Livewire;
use Shopper\Livewire\ProductCard as BaseProductCard;

class CustomProductCard extends BaseProductCard {
    public function updatedQuantity() {
        // Custom logic (e.g., validate stock)
        $this->validate(['quantity' => 'max:'.$this->product->stock]);
    }
}
```
- Blade Templates: Override scaffolded views by placing them in your project’s resources/views (e.g., resources/views/storefront/layouts/app.blade.php will override the kit’s version).

Integration with Shopper Core

Product Models: The kit scaffolds a Product model tied to Shopper’s Eloquent models. Extend it:

// app/Models/Product.php
use Shopper\Models\Product as BaseProduct;

class Product extends BaseProduct {
    protected $appends = ['formattedPrice', 'discountedPrice'];
    public function getFormattedPriceAttribute() {
        return '$'.$this->price->value;
    }
}

Checkout Flow: Use Shopper’s Checkout facade to integrate payment logic:

use Shopper\Facades\Checkout;
Checkout::createOrder($cartId, $paymentMethod);

Customizing Routes
- The kit registers routes in routes/web.php. Extend or override them by:
  - Publishing the kit’s routes:
```
php artisan vendor:publish --tag=shopper-livewire-routes
```
  - Modifying the published file (routes/shopper.php).
Asset Management
- The kit includes Alpine.js/Livewire scripts. Customize by:
  - Overriding the scaffolded resources/js/app.js or resources/css/app.css.
  - Using Laravel Mix/Vite to compile custom assets.

Daily Usage Patterns

Debugging Scaffolded Features: Use php artisan shopper:kit:debug to list installed kits and their files.
Updating Kits: Run composer update shopperlabs/livewire-starter-kit to pull latest changes (merge conflicts may occur).
Partial Adoption: Install only specific parts of a kit (e.g., just the checkout flow) by forking the kit and modifying its shopper-kit.yaml.

Gotchas and Tips

Pitfalls

File Overwrite Risks
- Running shopper:kit:install again on an existing kit will overwrite files. To avoid this:
  - Use --force carefully: php artisan shopper:kit:install --force.
  - Backup critical files (e.g., routes/web.php, app/Http/Controllers/).
- Solution: Fork the kit and modify its shopper-kit.yaml to exclude files you’ve customized.
Dependency Conflicts
- Kits may pull in versions of packages (e.g., Livewire, Laravel UI) that conflict with your project.
- Solution: Use replace in composer.json or pin versions in the kit’s shopper-kit.yaml:
```
dependencies:
  livewire/livewire: "^3.0"
```
Route/Namespace Collisions
- Scaffolded routes may conflict with existing ones (e.g., /admin vs. /storefront/admin).
- Solution: Rename routes in the kit’s shopper-kit.yaml or override them in your routes/web.php.
Livewire Component Isolation
- Custom Livewire components may not inherit kit-specific logic if not extended properly.
- Solution: Use trait composition or inherit from the kit’s base components (as shown in the Implementation Patterns section).
Database Migrations
- Kits may include migrations for Shopper’s tables (e.g., products, orders). Running them twice can cause errors.
- Solution: Check database/migrations/ for duplicate timestamps and rename conflicts.

Debugging Tips

Kit Manifest Issues: If installation fails, inspect the kit’s shopper-kit.yaml for invalid paths or commands. Validate with:
```
php artisan shopper:kit:validate shopperlabs/livewire-starter-kit
```
Livewire Debugging: Use livewire:log to trace component interactions:
```
php artisan livewire:log
```
Configuration Overrides: Kits publish config files (e.g., config/shopper.php). Override them in config/shopper.php:
```
'livewire' => [
    'enabled' => env('SHOPPER_LIVEWIRE_ENABLED', true),
],
```

Extension Points

Custom Kit Development

Create your own kit by:

Adding a shopper-kit.yaml manifest to your package:

name: "my-custom-kit"
description: "My scaffold for Shopper"
files:
  - from: "src/views"
    to: "resources/views/storefront"
dependencies:
  - "spatie/laravel-permission"
commands:
  - "php artisan vendor:publish --tag=permissions"

Publishing it to Packagist or GitHub.
Registering it in the Shopper Starter Kits registry.

Hooks and Events

Kits can trigger events (e.g., Shopper\Events\KitInstalled). Listen to them in EventServiceProvider:

protected $listen = [
    'Shopper\Events\KitInstalled' => [
        'App\Listeners\LogKitInstallation',
    ],
];

Dynamic Kit Installation

Install kits programmatically via the ShopperKit facade:

use Shopper\Facades\ShopperKit;
ShopperKit::install('shopperlabs/livewire-starter-kit');

Starter Kits Laravel Package