Framework Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require shopper/framework
   

   Ensure your Laravel project meets the requirements (PHP 8.1+, Laravel 9+).

2. Publish Config & Migrations

   php artisan vendor:publish --provider="Shopper\Admin\AdminServiceProvider"
   php artisan migrate
   

3. Basic Configuration Update .env with:

   SHOPPER_ADMIN_ENABLED=true
   SHOPPER_ADMIN_URL=/admin
   

4. First Use Case Access /admin to see the default dashboard. Use the built-in CLI to scaffold a product:

   php artisan shopper:make:product "My First Product"
   

Implementation Patterns

Core Workflows

1. Product Management

   • Use the Product model (Shopper\Admin\Models\Product) for CRUD operations.
   • Example: Create a product programmatically:

     use Shopper\Admin\Models\Product;
     
     $product = Product::create([
         'name' => 'Premium Widget',
         'price' => 19.99,
         'sku' => 'WIDGET-PRO-001',
     ]);
     

2. Inventory Integration

   • Extend the Inventory trait (Shopper\Admin\Traits\HasInventory) to track stock:

     class Product extends Model {
         use HasInventory;
     }
     

3. API-Driven Admin

   • Leverage the built-in API endpoints (e.g., /admin/api/products) for headless interactions:

     $response = Http::get('/admin/api/products');
     

4. Event-Driven Extensions

   • Listen to Shopper\Admin\Events\ProductCreated for custom logic:

     Event::listen(ProductCreated::class, function ($product) {
         // Send notification, update analytics, etc.
     });
     

Integration Tips

• Authentication: Use Laravel’s built-in auth or integrate with Sanctum/Passport for API access.
• Theming: Override Blade templates in resources/views/vendor/shopper-admin.
• Localization: Extend the Shopper\Admin\Lang\LangManager for multi-language support.
• Testing: Use Shopper\Admin\Testing\CreatesAdminUser trait in PHPUnit tests.

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Ensure SHOPPER_ADMIN_URL doesn’t clash with existing routes. Use php artisan route:list to debug.

2. Middleware Overrides

   • The admin panel uses Shopper\Admin\Http\Middleware\AdminAuth. Avoid overriding it unless necessary.

3. Database Schema Changes

   • Migrations are auto-published but may conflict with existing tables. Review database/migrations/ before running migrate.

4. Caching Quirks

   • Clear the config cache after changing .env:

     php artisan config:clear
     

Debugging Tips

• Log Output: Enable debug mode (APP_DEBUG=true) and check storage/logs/laravel.log.
• API Errors: Use Postman or Laravel’s Http::debug(true) to inspect API responses.
• Blade Debugging: Add @dump($product) to templates to inspect data.

Extension Points

1. Custom Fields

   • Extend the Product model with custom attributes and add them to the admin panel via:

     // In a service provider
     Shopper::extend('product', function ($builder) {
         $builder->addField('custom_field', 'text');
     });
     

2. Custom Actions

   • Add buttons to the admin panel using the Shopper\Admin\Contracts\HasActions trait:

     class Product extends Model implements HasActions {
         public function getActions(): array {
             return [
                 'publish' => function () {
                     // Custom logic
                 },
             ];
         }
     }
     

3. Headless Mode

   • Disable the Blade UI entirely by setting:

     SHOPPER_ADMIN_UI_ENABLED=false
     

   • Use only the API endpoints for fully headless setups.