Product Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require awstudio/product-bundle
   

   Ensure your composer.json includes the required dependencies (sylius/attribute-bundle, sylius/product, etc.).

2. Bundle Configuration Add to config/bundles.php:

   return [
       // ...
       Awstudio\ProductBundle\AwstudioProductBundle::class => ['all' => true],
   ];
   

3. Database Migrations Run migrations to create product-related tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. First Use Case: Basic Product CRUD

   • Create a product entity via the admin interface (if using Sylius admin) or manually:

     use Awstudio\ProductBundle\Entity\Product;
     
     $product = new Product();
     $product->setName('Sample Product');
     $product->setSlug('sample-product');
     $product->setPrice(19.99);
     $manager->persist($product);
     $manager->flush();
     

   • Fetch products in a controller:

     $products = $this->getDoctrine()->getRepository(Product::class)->findAll();
     

Implementation Patterns

Core Workflows

1. Product Management

   • Variants: Define variants via ProductVariant entity (e.g., size/color combinations).

     $variant = new ProductVariant();
     $variant->setProduct($product);
     $variant->setSku('PROD-001-BLUE-L');
     $variant->setPrice(24.99);
     

   • Options: Attach options (e.g., dropdowns, checkboxes) using ProductOption and ProductOptionValue.

     $option = new ProductOption();
     $option->setCode('color');
     $option->setName('Color');
     $product->addOption($option);
     

2. Attributes & Properties

   • Use sylius/attribute-bundle for customizable properties (e.g., weight, dimensions):

     $attribute = $attributeRepository->findOneBy(['code' => 'weight']);
     $product->addAttribute($attribute, '1.5 kg');
     

3. API Integration

   • Expose products via Symfony’s serializer:

     # config/packages/serializer.yaml
     framework:
         serializer:
             mapping:
                 paths: ['%kernel.project_dir%/config/serializer']
     

     Create Product.yaml in config/serializer:

     Awstudio\ProductBundle\Entity\Product:
         attributes:
             id: ~
             name: ~
             slug: ~
             price: ~
     

4. Event-Driven Logic

   • Subscribe to product events (e.g., ProductCreateEvent):

     use Awstudio\ProductBundle\Event\ProductEvents;
     
     $dispatcher->addListener(ProductEvents::PRODUCT_CREATE, function ($event) {
         // Log or process new products
     });
     

Gotchas and Tips

Common Pitfalls

1. Deprecation Warnings

   • The package is outdated (last release: 2018). Ensure compatibility with modern Symfony/Laravel by:
     • Overriding deprecated methods (e.g., setPrice() → setBasePrice()).
     • Using sylius/product directly if needed (this bundle is a wrapper).

2. Doctrine Extensions

   • Requires stof/doctrine-extensions-bundle for soft deletes/timestamps. If missing:

     composer require stof/doctrine-extensions-bundle
     

     Configure in config/packages/doctrine.yaml:

     orm:
         dql:
             string_functions:
                 CONCAT: DoctrineExtensions\Query\Mysql\Concat
     

3. Translation Handling

   • Localization relies on sylius/locale-bundle. For multi-language support:

     # config/packages/sylius_locale.yaml
     sylius_locale:
         default_locale: en_US
         available_locales: [en_US, fr_FR]
     

     Translate product fields via ProductTranslation:

     $translation = new ProductTranslation();
     $translation->setLocale('fr_FR');
     $translation->setName('Produit Exemple');
     $product->addTranslation($translation);
     

4. Performance with Large Catalogs

   • Use DQL queries with DISTINCT for variant-heavy products:

     $query = $repository->createQueryBuilder('p')
         ->select('DISTINCT p.id')
         ->addSelect('v')
         ->leftJoin('p.variants', 'v')
         ->getQuery();
     

Debugging Tips

• Entity Validation: Enable Symfony’s validator for product entities:

  $errors = $validator->validate($product);
  if (count($errors) > 0) {
      foreach ($errors as $error) {
          echo $error->getPropertyPath() . ': ' . $error->getMessage() . "\n";
      }
  }
  

• Event Debugging: Log dispatched events:

  $dispatcher->addListener(ProductEvents::PRODUCT_UPDATE, function ($event) {
      \Log::debug('Product updated:', ['product' => $event->getProduct()->getId()]);
  });
  

Extension Points

1. Custom Product Types

   • Extend Product via inheritance or traits:

     class DigitalProduct extends Product
     {
         private $downloadLink;
     
         public function setDownloadLink(string $link): self
         {
             $this->downloadLink = $link;
             return $this;
         }
     }
     

   • Register the new type in ProductTypeRegistry (override service).

2. API Filters

   • Add custom filters to the product repository:

     use Awstudio\ProductBundle\Repository\ProductRepository;
     
     class CustomProductRepository extends ProductRepository
     {
         public function findByCustomFilter(array $criteria)
         {
             return $this->createQueryBuilder('p')
                 ->where('p.price > :minPrice')
                 ->setParameter('minPrice', $criteria['min_price'])
                 ->getQuery()
                 ->getResult();
         }
     }
     

   • Update services.yaml to replace the default repository.

3. Admin Panel Integration

   • Extend Sylius admin grid for products:

     # config/packages/sylius_grid.yaml
     sylius_grid:
         grids:
             sylius_admin_product:
                 driver:
                     options:
                         fields:
                             name: ~
                             price: =price.getBasePrice()
                             variants_count: =variantCount()