Product Bundle Laravel Package

Getting Started

This is a Sulu 1.x era Symfony bundle (last release May 2018), so treat it as legacy integration work rather than greenfield. It requires Symfony 3.x/4.x, PHP 7.x, Doctrine ORM, and a matching sulu/sulu core (^1.6).

Minimal steps:

1. composer require sulu/product-bundle and pin the version that matches your Sulu core.
2. Register the bundle in app/AppKernel.php (or config/bundles.php) after SuluCoreBundle, SuluAdminBundle, and SuluContentBundle — it depends on their services and admin navigation.
3. Import the bundle's routing for the REST API:

   sulu_product_api:
       type: rest
       resource: "@SuluProductBundle/Resources/config/routing_api.xml"
       prefix: /admin/api
   

4. Enable the Doctrine mappings — the bundle ships XML mappings under Resources/config/doctrine/. Either rely on auto-registration or add Sulu\Bundle\ProductBundle\Entity to your doctrine.orm.mappings.
5. Update schema: bin/console doctrine:schema:update --force in dev, or generate a migration for prod.
6. Rebuild the admin: bin/console sulu:build (or assets:install + assetic:dump in older setups) so the product tab appears.

Where to look first:

• Entity/Product.php, Entity/ProductTranslation.php — the data model.
• Product/ProductManager.php + ProductManagerInterface — the public service surface.
• Product/ProductRepository.php — how filtering/pagination actually works.
• Controller/ProductController.php — the REST contract you'll mirror.
• Resources/config/services.xml — service IDs (sulu_product.product_manager, sulu_product.product_repository).

First use case: inject sulu_product.product_manager into your own service and call save() / findById() to create or read products; alternatively hit GET /admin/api/products?flat=true&limit=10 to confirm the admin API is wired up before writing any PHP.

Implementation Patterns

Service-layer reads and writes. Always go through ProductManagerInterface and ProductRepositoryInterface rather than the EntityManager. The manager handles translations, URL generation, and event dispatching that the raw entity will miss.

public function __construct(
    private ProductManagerInterface $productManager,
    private ProductRepositoryInterface $productRepository
) {}

$product = $this->productManager->save([
    'name' => 'Widget',
    'locale' => 'en',
    'status' => Product::STATUS_ACTIVE,
], $existingId);

Filtered listing. ProductRepositoryInterface::findByFilters($filters, $sortBy, $sortOrder, $limit, $offset, $locale) mirrors the admin list behaviour. Pass the same array shape the REST API sends so your custom controller and the admin UI stay in sync.

Custom attributes. Extend ProductAttribute by creating a ProductAttributeValue per product, keyed by the attribute entity. Keep the attribute-type string in sync with what the admin form renders — a typo silently yields a product with no value rather than an exception.

Admin UI extension. Override the product form templates by placing files at app/Resources/SuluProductBundle/views/... (or the bundle's override path in your project). Use the block/sulu_form structure already present rather than inventing new fields, so the REST serializer and the form stay aligned.

Content integration. For editors picking products in pages, use the product_selection content type; for generated product listings (e.g. a shop category page), register a smart-content data provider or reuse the shipped one. This is the highest-value integration for a CMS-driven shop and avoids hand-rolling Twig queries.

Events for cross-cutting concerns. Subscribe to ProductEvents::PRE_PERSIST, POST_PERSIST, PRE_DELETE for cache invalidation, search indexing, or ERP sync. These fire from the manager, so direct ORM writes bypass them — another reason to always use the manager.

Headless usage. The REST controller is a complete CRUD surface (GET/POST/PUT/DELETE /admin/api/products). If you're building a storefront separately, point your consumer at this API rather than importing the entities, and let the bundle own the schema.

Gotchas and Tips

• Version wall. This bundle is Sulu 1.x only. Sulu 2.x rewrote the admin (React), namespaces, and services — you cannot upgrade the bundle in place. If you're on Sulu 2+, product management lives in the monorepo; do not install this package.
• Last release 2018, zero dependents. Assume no security patches. Audit the pinned dependencies before production, and isolate it behind a container if possible.
• Translations need a locale context. Set $product->setLocale($locale) before saving and make sure the fallback locale is configured in sulu_core; otherwise getTranslation() returns null and admin forms render blank.
• Attribute types are stringly-typed. An unknown type on ProductAttribute fails at render time, not at persist time. Validate on your side and keep a constant map in your own code.
• Filtering quirks. findByFilters expects Sulu's RestHelper keys (flat, ids, category), not arbitrary Doctrine criteria. If results are unexpectedly empty, log the composed query with doctrine.dbal.logging enabled.
• No stock/inventory domain. The bundle gives you price, currency, attributes, media, and categories — not warehouses or stock movements. Plan for your own bundle layered on top.
• Rebuild assets after any template override. bin/console sulu:build (or the Assetic pipeline) — otherwise changes are invisible in the admin and you'll chase a phantom bug.
• Smart content cache. After bulk product imports, run bin/console sulu:content:reindex (or your project's equivalent) or listings go stale.
• Debugging hooks. Exceptions to expect: ProductNotFoundException (bad ID), ProductDependencyException (delete blocked by relations), and Doctrine MappingException (bundle mappings not registered). Enable sulu_product channel logging at debug to trace manager calls.
• Extension points: the manager interface, the repository interface, the REST serializer, and the template override tree are the four stable seams. Prefer subscribing to events over editing vendor files — the 2018 codebase will not be patched for you.