Product Laravel Package

Getting Started

Before writing any code, verify compatibility. This subtree split dates to mid-2015 and targets the Symfony 2.x / PHP 5.x era; it will not install cleanly on modern PHP or Symfony. Treat it as a maintenance-only dependency for existing Elcodi applications, not a greenfield choice.

• If you are on a compatible stack, install with composer require elcodi/product. If you're using the full suite, require elcodi/elcodi (or the ProductBundle) instead — the bare component ships interfaces, entities, and factories but no DI wiring or Doctrine mapping.

• Look first at: Entity/ (Product, Variant, ProductTranslation), Factory/, Repository/, and the event-constants class. That is effectively the entire API surface; the README contributes almost nothing.

• First use case: construct a product through its factory, attach a translation, persist via the repository:

  $product = $productFactory->create();
  $product->setName('My product');          // or via translation
  $productRepository->save($product);
  

• The companion bundle is where services, mappings, and event subscribers live. Read its Resources/config/ before assuming behaviour in the component.

Implementation Patterns

• Factory-first construction. Never new Product() directly — always go through ProductFactoryInterface. Custom factories and listeners rely on that seam, and bypassing it silently skips them.
• Translation-aware writes. Create a ProductTranslation per locale (from elcodi/language) and attach it to the product. Don't set translatable fields through the base entity and expect locale-aware reads later.
• Product vs Variant. Keep pricing, stock, and SKU on the Variant; Product is the catalog-level record. Manage variants through the product's collection or a variant factory so events fire.
• Extend by subclassing. Create App\Entity\Product extends Elcodi\...\Product, implement the matching interface, and override the bundle's class parameter + Doctrine mapping. Keep the interface contract so cart/order components resolve it.
• Hook via events. Subscribe to the component's event constants (or Doctrine lifecycle listeners) for slugging, pricing recalculation, and inventory sync. This is the intended integration path — avoid editing vendor code.
• Unit testing. The component is largely plain PHP; mock the factory and repository interfaces and you can test without a container.

Gotchas and Tips

• Read-only repo. Issues and PRs belong to elcodi/elcodi. Any fix must be applied in the monorepo or as a fork/patch; nothing lands here.
• Abandonment risk. No release since 2015, zero dependents, Symfony 2-era constraints. For new builds, choose Sylius or another maintained option. For legacy apps, pin exact versions and commit composer.lock.
• Composer hygiene. The dev-master alias is explicitly unstable. Pin to the last stable tag and keep elcodi/core and elcodi/language in lockstep — mismatched transitive versions cause hard-to-trace mapping errors.
• Mapping overrides bite. When subclassing entities, update both the Doctrine mapping config and the factory/class parameters. Updating only one causes silent instantiation of the wrong class.
• Translation fallback. Reads in a missing locale can return null. Configure a fallback locale and test it explicitly.
• Variant uniqueness. SKU uniqueness is not enforced at the DB layer by default — add a unique constraint in your mapping.
• Debugging. Use debug:container to confirm which concrete class the factory produces, and the Symfony profiler for generated queries. A listener swallowing an exception is the usual cause of silent no-ops.
• Extension points to prefer. Interfaces (ProductInterface, VariantInterface), factories, repositories, and the event dispatcher. Override services in app config rather than patching the package.