Getting Started

Minimal Steps to First Use

Install Dependencies Run the core installation command:

composer require tomatophp/filament-ecommerce

Then publish required migrations and configurations:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan filament-settings-hub:install
php artisan vendor:publish --tag="filament-accounts-model"

Initialize the Plugin Run the final setup command:
```
php artisan filament-ecommerce:install
```

Register the Plugin Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \TomatoPHP\FilamentEcommerce\Plugin::make(),
        ]);
}

First Use Case: Product Creation Navigate to the Products section in the Filament admin panel. Use the built-in CRUD interface to:
- Add a product with SKU, name, price, and description.
- Upload product images via the Media Library integration.
- Assign categories or tags using the provided taxonomy system.

Implementation Patterns

Core Workflows

Product Management
- Bulk Actions: Use Filament’s built-in bulk operations to update prices, stock levels, or visibility across multiple products.
- Variants: Leverage the hasMany relationship for product variants (e.g., size/color combinations) with shared inventory logic.
- SEO Optimization: Edit meta titles/descriptions directly in the Filament UI via the Tomato\CMS\Traits\HasMeta trait.
Order Processing
- Workflow Automation: Use Filament’s Actions to trigger order status updates (e.g., "Mark as Shipped") with custom logic.
- Order Notes: Attach internal notes to orders via the notes relationship, accessible in the Filament order detail view.
- Refunds/Returns: Extend the Order model to include refund logic (e.g., handleRefund() method) and expose it as a Filament action.
Customer Management
- Segmentation: Filter customers by order history, lifetime value, or tags using Filament’s Query Builder.
- Communication: Integrate with email services (e.g., Mailgun) via Filament’s Actions to send targeted campaigns.
Inventory Sync
- Real-Time Updates: Use Laravel Events (InventoryUpdated) to sync stock levels across platforms (e.g., ERP systems) via Filament’s Notifications.
- Low-Stock Alerts: Set up Filament Widgets to display low-stock products with direct links to reorder.

Integration Tips

Payment Gateways: Integrate with Stripe/PayPal by extending the Order model’s payment_method field and adding a custom Filament Resource for transaction logs.

// Example: Add a custom action for capturing payments
public static function getActions(Order $record): array
{
    return [
        Action::make('Capture Payment')
            ->action(fn (Order $order) => $order->capturePayment())
            ->requiresConfirmation(),
    ];
}

Shipping Providers: Use Filament’s Forms to configure shipping rules (e.g., weight-based rates) via the ShippingMethod model. Publish a custom settings panel:
```
php artisan make:filament-settings ShippingSettings
```
Taxonomy Management: Extend the built-in Category and Tag models to include custom fields (e.g., SEO slugs) by publishing the resource:
```
php artisan vendor:publish --tag="filament-ecommerce-resources"
```

API Extensions: Expose ecommerce data via Laravel Sanctum or Filament’s API Resources. Example:

// app/Http/Controllers/Filament/Ecommerce/ProductController.php
public function apiIndex()
{
    return ProductResource::collection(Product::query()->paginate());
}

Gotchas and Tips

Pitfalls

Media Library Conflicts
- Issue: If the Spatie\MediaLibrary migrations fail due to existing tables, manually drop the media table before republishing.
- Fix: Use --force flag or reset the database:
```
php artisan migrate:fresh --env=testing
```
Permission Denied Errors
- Issue: Filament’s Policy system may block actions if not properly configured. For example, updateOrderStatus might fail for non-admin users.
- Fix: Extend the default OrderPolicy in app/Policies/OrderPolicy.php:
```
public function updateStatus(User $user, Order $order)
{
    return $user->can('update-order-status') || $user->isAdmin();
}
```

Tax/Inventory Calculation Bugs

Issue: Custom tax rules or inventory formulas may not update in real-time due to Laravel’s query caching.

Fix: Use fresh() or with() clauses in Filament resources:

public static function getRelations(): array
{
    return [
        RelationManager::make('inventory', Inventory::class)
            ->query(function (Builder $query) {
                return $query->with(['warehouse']);
            }),
    ];
}

Plugin Registration Order
- Issue: The filament-ecommerce:install command may fail if run before filament-settings-hub:install.
- Fix: Follow the installation steps exactly in order. Verify the SettingsHub is registered in config/filament.php.

Debugging Tips

Log Filament Events: Enable debug logging for Filament’s plugin system:
```
// config/filament.php
'debug' => env('FILAMENT_DEBUG', true),
```
Check logs at storage/logs/laravel.log for plugin initialization errors.
Resource Overrides: To debug custom resource behavior, override the default Filament resources:
```
php artisan make:filament-resource Product --override
```
Then extend the published resource in app/Filament/Resources/ProductResource.php.
Database Seed Issues: If seeding fails due to missing references (e.g., categories), use Laravel’s seed:run with --class:
```
php artisan db:seed --class=EcommerceSeeder
```

Extension Points

Custom Fields Add fields to models via Filament Forms. Example for Product:

// app/Filament/Resources/ProductResource/Pages/CreateProduct.php
public function form(Form $form): Form
{
    return $form
        ->schema([
            // ... existing fields
            TextInput::make('custom_field')
                ->columnSpanFull(),
        ]);
}

Workflow Hooks Use Laravel Events to intercept actions. Example for order creation:

// app/Providers/EventServiceProvider.php
protected $listen = [
    'order.created' => [
        \App\Listeners\SendOrderConfirmation::class,
    ],
];

API Endpoints Extend the built-in API by creating a custom Filament API Resource:

// routes/api.php
Route::middleware('auth:sanctum')->get('/ecommerce/products', [ProductController::class, 'apiIndex']);

Theme Customization Override Filament’s Blade views for ecommerce-specific styling:
```
php artisan vendor:publish --tag=filament-views
```
Then modify resources/views/vendor/filament/... to match your store’s branding.

Multi-Warehouse Support Extend the Inventory model to support multiple warehouses:

// app/Models/Inventory.php
public function warehouse()
{
    return $this->belongsTo(Warehouse::class);
}

Update the Filament resource to include warehouse selection:

Select::make('warehouse_id')
    ->relationship('warehouse', 'name')
    ->required(),

Filament Ecommerce Laravel Package