Products Product Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require baks-dev/products-category baks-dev/reference-money baks-dev/reference-currency baks-dev/reference-measurement baks-dev/products-product
   

2. Run Asset and Migration Setup:

   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case: Create a product via Tinker or a controller:

   use BaksDev\Products\Product\Entity\Product;
   
   $product = new Product();
   $product->setName('Test Product');
   $product->setSku('SKU123');
   $product->setPrice(19.99); // Assumes reference-money integration
   $product->setCurrency('USD'); // Assumes reference-currency integration
   $product->save();
   

Where to Look First

• Entities: src/Entity/ for Product, Category, and related models.
• Migrations: src/Migrations/ for schema changes.
• Console Commands: src/Command/ for baks:assets:install.
• Tests: tests/ for usage examples (run with phpunit --group=products-product).

Implementation Patterns

Core Workflows

1. Product CRUD: Use Eloquent or Doctrine repositories (if implemented) for basic operations:

   // Create
   $product = Product::create([
       'name' => 'Premium Widget',
       'sku' => 'WIDGET-PREM',
       'price' => 49.99,
       'currency' => 'EUR',
       'measurement' => 'kg', // Assumes reference-measurement
   ]);
   
   // Read with eager-loaded relationships
   $product = Product::with('categories', 'measurementUnit')->find($id);
   
   // Update
   $product->setPrice(39.99)->save();
   
   // Delete (soft delete if supported)
   $product->delete();
   

2. Category Hierarchies: Leverage products-category for nested categories:

   $category = Category::find($id);
   $products = $category->products()->with('measurementUnit')->get();
   

3. Multi-Currency Pricing: Integrate with reference-money for dynamic pricing:

   $product->setPrice(100, 'USD'); // Stores as 100 USD
   $convertedPrice = $product->getPriceIn('EUR'); // Uses reference-money logic
   

4. Measurements: Attach units via reference-measurement:

   $product->setMeasurement('500', 'ml'); // 500ml
   $measurement = $product->getMeasurementValue(); // Returns 500
   $measurementUnit = $product->getMeasurementUnit(); // Returns 'ml'
   

Integration Tips

• Service Layer: Create a service class to encapsulate business logic (e.g., ProductService):

  class ProductService {
      public function createWithValidation(array $data) {
          $validator = Validator::make($data, [
              'name' => 'required|string|max:255',
              'sku' => 'required|unique:products',
              'price' => 'required|numeric',
          ]);
          if ($validator->fails()) {
              throw new \InvalidArgumentException($validator->errors()->first());
          }
          return Product::create($data);
      }
  }
  

• Events/Observers: Extend functionality with Laravel events (if not natively supported):

  // app/Observers/ProductObserver.php
  class ProductObserver {
      public function saved(Product $product) {
          event(new ProductCreated($product));
      }
  }
  

  Register in AppServiceProvider:

  Product::observe(ProductObserver::class);
  

• API Resources: Expose products via Laravel API Resources:

  // app/Http/Resources/ProductResource.php
  class ProductResource extends JsonResource {
      public function toArray($request) {
          return [
              'id' => $this->id,
              'name' => $this->name,
              'sku' => $this->sku,
              'price' => $this->price->amount, // Assumes reference-money
              'currency' => $this->price->currency->code,
              'measurement' => $this->measurement,
              'unit' => $this->measurementUnit->symbol,
          ];
      }
  }
  

• Bulk Operations: Use Doctrine’s BulkOperations or Eloquent chunking:

  Product::chunk(100, function ($products) {
      foreach ($products as $product) {
          $product->update(['status' => 'active']);
      }
  });
  

• Custom Attributes: Extend the Product entity with dynamic attributes (if needed):

  // Add to Product entity
  protected $attributes = [
      'is_featured' => false,
      'weight' => null,
  ];
  
  // Or use a JSON column for flexible attributes
  protected $casts = [
      'attributes' => 'json',
  ];
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If you’ve customized the products table, migrations may fail. Solution:
     • Run php bin/console doctrine:migrations:diff --dump-sql to preview changes.
     • Manually resolve conflicts by editing migration files or using --complete flag.

2. N+1 Query Risks:

   • Eager-load relationships explicitly to avoid performance issues:

     // Bad: N+1 queries
     $products = Product::all();
     foreach ($products as $product) {
         $product->categories; // Triggers N queries
     }
     
     // Good: Eager-load
     $products = Product::with('categories', 'measurementUnit')->get();
     

3. Currency/Measurement Dependencies:

   • The package relies on reference-money and reference-currency. Ensure these are properly configured:

     composer require baks-dev/reference-money baks-dev/reference-currency
     php bin/console baks:assets:install
     

   • Tip: Test currency conversion logic early:

     $product->setPrice(100, 'USD');
     $product->getPriceIn('EUR'); // Should return converted value
     

4. Undocumented Validation:

   • The package may enforce validation rules not documented in the README. Solution:
     • Inspect the Product entity for validation annotations or traits.
     • Override validation in a service layer if needed.

5. Russian Documentation:

   • The README and comments may be in Russian. Solution:
     • Use tools like DeepL for translations.
     • Focus on code examples and entity structures over text.

6. No Built-in API:

   • The package doesn’t include REST/GraphQL endpoints. Solution:
     • Use Laravel’s API Resources or spatie/laravel-api for endpoints.
     • Example route:

       Route::apiResource('products', ProductController::class);
       

7. Soft Deletes:

   • Check if the Product model uses soft deletes. If so, use:

     $product = Product::withTrashed()->find($id);
     $product->forceDelete(); // Hard delete
     

Debugging Tips

1. Query Logging: Enable Laravel’s query logging to debug N+1 issues:

   DB::enableQueryLog();
   Product::with('categories')->get();
   dd(DB::getQueryLog());
   

2. Doctrine Events: Listen for Doctrine lifecycle events to debug entity changes:

   $em->getEventManager()->addEventListener(
       \Doctrine\ORM\Events::postPersist,
       function ($event) {
           $entity = $event->getObject();
           \Log::info("Entity {$entity::class} persisted", ['data' => $entity]);
       }
   );
   

3. Console Command Debugging: Add debug output to custom console commands:

   public function handle() {
       \Log::info('Starting assets install...');
       // Command logic
   }
   

4. Testing: Run the package’s tests to understand expected behavior:

   php bin/phpunit --group=products-product
   

Extension Points

1. Custom Repositories: Override the default repository for advanced logic:

   // config/products.php
   'repositories' => [
       'product' => \App\Repositories\CustomProductRepository::class,
   ];
   

2. Traits for Reusable Logic: Add traits to extend entities:

   // app/Models/Concerns/HasVariants.php
   trait HasVariants {
       public function variants() {
           return $this->hasMany(Variant