Marketplace Laravel Package

Getting Started

Minimal Steps

1. Installation Run these commands in your Laravel 10.x project (PHP 8.1+):

   composer require sajadsdi/marketplace
   php artisan marketplace:publish
   php artisan marketplace:install
   

   • marketplace:publish copies config, migrations, and views to your project.
   • marketplace:install runs migrations and sets up default configurations.

2. First Use Case: Basic Product Listing

   • Publish the package views (if using Blade):

     php artisan vendor:publish --tag=marketplace-views
     

   • Define a product model extending Marketplace\Product (if customizing):

     use Sajadsdi\Marketplace\Models\Product;
     
     class MyProduct extends Product {}
     

   • Use the built-in routes (e.g., /products) or define custom routes in routes/web.php:

     use Sajadsdi\Marketplace\Http\Controllers\ProductController;
     
     Route::resource('products', ProductController::class);
     

3. Sanctum Setup (Required) Ensure Sanctum is configured for API auth:

   composer require laravel/sanctum
   php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
   php artisan migrate
   

   Add Sanctum middleware to api.php:

   Route::middleware('auth:sanctum')->group(function () {
       // Your marketplace API routes
   });
   

4. Test the API Use the provided Postman collection (postman/Marketplace.postman_collection.json) to interact with endpoints like:

   • GET /api/products (List products)
   • POST /api/products (Create product, requires auth)

Implementation Patterns

Core Workflows

1. Product Management

   • CRUD Operations: Use the ProductController for basic operations. Extend it for custom logic:

     namespace App\Http\Controllers;
     
     use Sajadsdi\Marketplace\Http\Controllers\ProductController as BaseProductController;
     
     class ProductController extends BaseProductController {
         public function index() {
             return parent::index()->withSearch(['category_id' => request('category')]);
         }
     }
     

   • Validation: Override validation rules in app/Providers/AppServiceProvider:

     use Sajadsdi\Marketplace\Rules\ProductRules;
     
     public function boot() {
         ProductRules::extend('custom_rule', function ($attribute, $value, $fail) {
             // Custom logic
         });
     }
     

2. User Roles and Permissions

   • Assign roles via middleware (e.g., can:create-products). Example in app/Http/Kernel.php:

     'create-product' => \Sajadsdi\Marketplace\Http\Middleware\CanCreateProduct::class,
     

   • Use the Marketplace\Policies\ProductPolicy to define permissions:

     public function create(User $user) {
         return $user->hasRole('seller');
     }
     

3. API Integration

   • Resource Controllers: Leverage the built-in ProductResource for API responses:

     use Sajadsdi\Marketplace\Http\Resources\ProductResource;
     
     return new ProductResource(Product::with('category')->get());
     

   • Webhooks: Extend the Marketplace\Events\ProductCreated event for custom logic:

     event(new ProductCreated($product));
     // Listen in EventServiceProvider
     

4. Frontend Integration

   • Blade Views: Use published views (e.g., resources/views/vendor/marketplace/products/index.blade.php) or extend them:

     @extends('vendor.marketplace.products.index')
     @section('extra_script')
         <script>console.log("Custom JS");</script>
     @endsection
     

   • Livewire Components: Integrate with Livewire for dynamic updates:

     use Sajadsdi\Marketplace\Livewire\ProductList;
     
     <livewire:product-list :categories="$categories" />
     

5. Search and Filtering

   • Use the ProductQueryBuilder for scoped queries:

     use Sajadsdi\Marketplace\Database\Query\ProductQueryBuilder;
     
     $query = Product::query();
     $query->applyFilters(request()->all());
     $products = $query->get();
     

   • Customize filters in config/marketplace.php:

     'filters' => [
         'price' => [
             'operator' => 'between',
             'column' => 'price',
         ],
         'category' => [
             'operator' => '=',
             'column' => 'category_id',
         ],
     ],
     

Gotchas and Tips

Pitfalls

1. Sanctum Misconfiguration

   • Issue: API routes fail with 401 Unauthorized even with valid tokens.
   • Fix: Ensure Sanctum middleware is applied after auth:sanctum in api.php:

     Route::middleware(['auth:sanctum', 'marketplace.auth'])->group(...);
     

   • Debug: Check config/sanctum.php for stateful and expiring settings.

2. Migration Conflicts

   • Issue: Running marketplace:install after custom migrations fail due to column conflicts.
   • Fix: Review database/migrations/ for overlapping columns (e.g., products table). Use:

     php artisan marketplace:migrate --force
     

     Warning: This may overwrite custom columns.

3. Caching Headaches

   • Issue: Product listings or filters don’t update after changes.
   • Fix: Clear Laravel cache and config:

     php artisan cache:clear
     php artisan config:clear
     

   • Tip: Disable caching during development in config/marketplace.php:

     'cache_enabled' => env('APP_ENV') !== 'local',
     

4. Role-Based Access Denied

   • Issue: Users with seller role can’t create products.
   • Fix: Verify the role is assigned via Marketplace\Traits\HasRoles:

     $user->assignRole('seller');
     

   • Debug: Check config/marketplace/roles.php for valid roles.

5. Postman Collection Gaps

   • Issue: Missing endpoints in the Postman collection.
   • Fix: Manually add routes (e.g., /api/products/{id}/reviews) or regenerate the collection using:

     php artisan marketplace:generate-postman
     

Debugging Tips

1. Log Queries Enable query logging in config/marketplace.php:

   'debug' => [
       'queries' => true,
       'events' => true,
   ],
   

   Check logs in storage/logs/laravel.log.

2. Event Listeners Listen for Marketplace\Events\Product* events to debug lifecycle:

   public function boot() {
       event(new ProductCreated($product));
       // Add to EventServiceProvider
   }
   

3. Custom Validation Override validation in app/Providers/AppServiceProvider:

   public function boot() {
       Validator::extend('custom_rule', function ($attribute, $value, $fail) {
           \Log::debug("Validating $attribute: $value");
           return true; // or false with $fail->fail(...);
       });
   }
   

Extension Points

1. Custom Models Extend Sajadsdi\Marketplace\Models\Product to add fields:

   class MyProduct extends Product {
       protected $casts = [
           'is_featured' => 'boolean',
       ];
   }
   

   Update migrations in database/migrations/.

2. Custom Controllers Override methods in app/Http/Controllers/ProductController:

   public function store(Request $request) {
       $request->merge(['custom_field' => 'value']);
       return parent::store($request);
   }
   

3. Custom Views Publish and extend views:

   php artisan vendor:publish --tag=marketplace-views
   

   Override resources/views/vendor/marketplace/products/create.blade.php.

4. Custom API Resources Extend ProductResource:

   namespace App\Http\Resources;
   
   use Sajadsdi\Marketplace\Http\Resources\ProductResource as BaseProductResource;
   
   class ProductResource extends BaseProductResource {
       public function toArray($request) {
           $array = parent::toArray($request);
           $array['custom_field'] = $this->custom_field;
           return $array;
       }
   }
   

5. Custom Middleware Add marketplace-specific middleware in app/Http/Middleware:

   namespace App\Http\Middleware;
   
   use Closure;
   use Sajadsdi\Marketplace\Traits\HasRoles;
   
   class EnsureSeller {