Common Product Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require antimattr/common-product
   

   Publish the package config (if needed):

   php artisan vendor:publish --provider="Antimattr\CommonProduct\CommonProductServiceProvider" --tag="config"
   

2. Basic Model Usage Extend the provided Product model in your app/Models directory:

   namespace App\Models;
   
   use Antimattr\CommonProduct\Models\Product as CommonProduct;
   
   class Product extends CommonProduct
   {
       // Customize as needed
   }
   

3. First Use Case: CRUD Operations

   use App\Models\Product;
   
   // Create
   $product = Product::create([
       'name' => 'Premium Widget',
       'sku' => 'WIDGET-PREM-001',
       'price' => 19.99,
       'description' => 'High-quality widget',
       'stock' => 100
   ]);
   
   // Retrieve
   $product = Product::find(1);
   
   // Update
   $product->update(['price' => 17.99]);
   
   // Delete
   $product->delete();
   

4. Key Features to Explore

   • Validation Rules: Check app/Providers/AppServiceProvider for default validation rules.
   • Scopes: Built-in scopes like active(), inStock(), or byPriceRange().
   • Observers: Default observers for soft deletes, stock management, etc.

Implementation Patterns

Core Workflows

1. Product Catalog Management

• Bulk Operations:

  // Update stock for multiple products
  Product::whereIn('id', [1, 2, 3])->update(['stock' => function($query) {
      return $query->decrement('stock', 5);
  }]);
  

• Inventory Sync:

  // Trigger stock validation before order processing
  $product = Product::find($id);
  if (!$product->validateStock($requiredQuantity)) {
      throw new \Exception('Insufficient stock');
  }
  

2. E-Commerce Integration

• Price Adjustments:

  // Apply a discount to a product
  $product->applyDiscount(10); // 10% discount
  $product->save();
  

• Tax Handling:

  $priceWithTax = $product->calculatePriceWithTax($taxRate);
  

3. API Resource

• Extend the provided ProductResource:

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

4. Event-Driven Workflows

• Listen to product events (e.g., ProductCreated, StockUpdated):

  // In EventServiceProvider
  protected $listen = [
      'Antimattr\CommonProduct\Events\ProductCreated' => [
          'App\Listeners\SendProductCreatedNotification',
      ],
  ];
  

Integration Tips

• Database Migrations: The package includes migrations for the core products table. Run:

  php artisan migrate
  

  If extending, create a new migration for custom fields and add them to the model.

• API Routes: Use the provided route macros (if any) or leverage the ProductController as a base:

  Route::apiResource('products', \Antimattr\CommonProduct\Http\Controllers\ProductController::class);
  

• Testing: Use the ProductFactory for seeding test data:

  use Antimattr\CommonProduct\Database\Factories\ProductFactory;
  
  ProductFactory::new()->create();
  

Gotchas and Tips

Pitfalls

1. Overriding Default Behavior:

   • If you override methods like boot(), ensure you call parent::boot() to retain default observers/scopes.
   • Example:

     protected static function boot()
     {
         parent::boot();
         // Custom boot logic
     }
     

2. Validation Rules:

   • Default validation rules are loaded via the AppServiceProvider. If you customize them, ensure the validate() method in your model still uses $this->rules().
   • Example override:

     public function rules()
     {
         return array_merge(parent::rules(), [
             'custom_field' => 'required|string',
         ]);
     }
     

3. Stock Management:

   • The package includes a StockObserver that may throw exceptions on negative stock. Disable or customize it if needed:

     // In your Product model
     protected static function boot()
     {
         static::observe(\Antimattr\CommonProduct\Observers\StockObserver::class);
         // Or replace with your own observer
     }
     

4. Soft Deletes:

   • The model uses SoftDeletes. Ensure your queries account for this:

     // With soft deletes
     $product = Product::withTrashed()->find($id);
     
     // Without soft deletes (if needed)
     $product = Product::withoutGlobalScopes()->find($id);
     

5. Caching:

   • The package may cache product data (e.g., for performance). Clear caches after bulk updates:

     php artisan cache:clear
     

Debugging Tips

1. Log Observers: Temporarily add logging to observers to trace events:

   // In StockObserver
   public function saving(Product $product)
   {
       \Log::debug('Product saving:', ['id' => $product->id, 'stock' => $product->stock]);
       // ...
   }
   

2. Validation Errors: Check the validation_errors log channel for detailed validation failures:

   // In your model
   protected function validateArray(array $data)
   {
       $validator = Validator::make($data, $this->rules());
       if ($validator->fails()) {
           \Log::channel('validation_errors')->error($validator->errors());
           throw new \Exception('Validation failed');
       }
       return true;
   }
   

3. Database Queries: Use Laravel Debugbar or DB::enableQueryLog() to inspect queries:

   DB::enableQueryLog();
   $product = Product::all();
   \Log::info(DB::getQueryLog());
   

Extension Points

1. Custom Fields: Add custom attributes to the model and serialize them:

   // In Product model
   protected $casts = [
       'custom_attributes' => 'array',
   ];
   
   // In migrations
   Schema::table('products', function (Blueprint $table) {
       $table->json('custom_attributes')->nullable();
   });
   

2. Additional Scopes: Extend the query builder with custom scopes:

   public function scopeFeatured($query)
   {
       return $query->where('is_featured', true);
   }
   

3. Event Customization: Publish and override event classes:

   php artisan vendor:publish --tag="common-product-events"
   

   Then extend the published events in app/Events.

4. API Extensions: Add custom endpoints by extending the ProductController:

   namespace App\Http\Controllers;
   
   use Antimattr\CommonProduct\Http\Controllers\ProductController as CommonProductController;
   
   class ProductController extends CommonProductController
   {
       public function customEndpoint()
       {
           // Your logic
       }
   }
   

5. Testing Utilities: Extend the ProductFactory for your test needs:

   namespace Database\Factories;
   
   use Antimattr\CommonProduct\Database\Factories\ProductFactory as CommonProductFactory;
   
   class ProductFactory extends CommonProductFactory
   {
       public function withCustomAttributes()
       {
           return $this->afterCreating(function (Product $product) {
               $product->custom_attributes = ['key' => 'value'];
               $product->save();
           });
       }
   }