Storefront Themes Laravel Package

Getting Started

This is not a Laravel package—it's an OroCommerce (Symfony) storefront theme bundle. There's no service provider, no config/*.php to publish, and no Artisan commands. If you're coming from Laravel, think of it as a Composer-delivered set of view/asset files plus YAML manifest files, not a runtime library.

Minimum steps to evaluate whether it's worth pulling in:

1. Confirm your host app. It only makes sense inside a running OroCommerce application (typically 5.x/6.x). It will do nothing in a standalone Laravel or Symfony skeleton.
2. Install in the app, not standalone:

   composer require oro/storefront-themes
   php bin/console cache:clear
   

   In most OroCommerce installs the themes may already arrive transitively via oro/commerce; check vendor/oro/storefront-themes before adding it explicitly.
3. Where to look first: open the package and find Resources/themes/<theme_name>/theme.yml for every bundled theme. That YAML is the real "API"—it declares name, label, and parent, and it tells you the inheritance chain you'll extend.
4. First use case: register a theme on a website. Go to the Oro admin → System → Websites, edit a website, and pick a theme from the storefront theme dropdown. If the bundled themes appear there, the package is wired correctly; if not, you have a discovery/cache problem, not a code problem.

Implementation Patterns

The day-to-day workflow is "child theme, not fork." Don't edit vendor/oro/storefront-themes; treat it as a base layer.

1. Create a child theme in your own bundle.

src/Acme/Bundle/StorefrontBundle/Resources/themes/acme_b2b/theme.yml

name: acme_b2b
label: "Acme B2B"
parent: default   # one of the themes shipped by oro/storefront-themes

Then extend templates from the parent by copying only the files you actually change.

2. Override layouts per block type. Oro layout overrides are scoped by block type, not global. A file like layouts/default/... only affects the default block type; product_view, checkout, search, etc. each resolve independently. Plan your override tree per block type you care about.

3. Use the templates map in theme.yml to remap block templates to your Twig files—this is cleaner than replacing whole layout files and survives parent-theme updates better.

4. Multi-site / multi-brand pattern. Because themes are assigned per website, this package shines in B2B setups with multiple storefronts: one base parent theme, then N thin child themes (acme_retail, acme_wholesale) that differ only in branding, catalog blocks, and checkout copy. Keep the divergence minimal so upgrades from the parent don't cascade.

5. Integration/CI loop.

composer install
php bin/console cache:clear
php bin/console assets:install --symlink     # plus the Oro asset build step for your version

Do this in deploy scripts—not just once locally. Theme resolution and compiled assets are cache-sensitive.

6. Keep customizations in your bundle's theme dir and add the parent theme name to your upgrade notes. When you bump oro/storefront-themes, diff the parent theme's theme.yml and layout tree against what you override.

Gotchas and Tips

• License is NOASSERTION. Treat this as a proprietary/enterprise-adjacent artifact (OroCommerce ships under a mix of OSL-3.0 and commercial terms). Confirm redistribution rights before vendoring into your own repo or a client deliverable.
• 1 star, 0 dependents. This is a vendor artifact, not a community package. Don't expect issues, PRs, or docs outside Oro's official documentation. Pin the version and budget for reading source.
• Parent name typos fail silently-ish. If parent: doesn't exactly match a registered theme name, you get a missing-theme / fallback situation rather than a loud error. Verify the admin dropdown, not just the YAML.
• Aggressive caching. Changes to theme.yml frequently require cache:clear and an asset rebuild before anything changes in the browser. If a template override "isn't working," 90% of the time it's cache or a mis-scoped block type.
• Asset pipeline is not Vite/Mix. You need Oro's asset build (oro:assets:build or the assets:install flow, depending on Oro version). Forgetting this yields an unstyled storefront and people assume the theme is broken.
• Block-type scoping surprises. Overriding default does not propagate to product_view/checkout; audit which block types render on the pages you're touching.
• Version coupling. theme.yml schema and layout structure have changed between OroCommerce majors. Pin to the version matching your platform.
• Extension points that actually work: child theme via theme.yml parent, templates remap, and per-block-type layout overrides in your bundle. Avoid: editing vendor files, swapping whole layout files when a partial override suffices, and copying all parent templates "just in case."
• Debugging: enable Twig debug in dev, use bin/console debug:twig to confirm which template resolves, inspect var/logs/ for layout resolution errors, and confirm the active theme in admin before touching Twig. In a Laravel mindset: pretend there is no php artisan view:clear safety net—clear the Symfony cache explicitly.