Default Theme Configuration Bundle Laravel Package

Getting Started

This is a Symfony bundle for OroCommerce, not a Laravel package — but the mapping is direct: bundles ≈ service providers, Resources/config/oro/*.yml ≈ config/*.php, Twig ≈ Blade, and oro:assets:build ≈ npm run dev with a mandatory cache clear. The bundle's job is to move theme values (logo, palette, fonts, free-form CSS) out of Resources/themes/<theme>/theme.yml and into the Oro admin UI, so a merchant can rebrand without a deploy.

Install and register

composer require ys-tools/default-theme-configuration-bundle

Register it the way your Oro version expects — config/bundles.php on Oro 5+/Symfony 5+, or Resources/config/oro/bundles.yml with an explicit priority if you're on an older kernel layout. Then run the full post-install chain, not just a cache clear:

php bin/console cache:clear
php bin/console oro:platform:update --env=prod --force
php bin/console oro:assets:build

oro:platform:update is the one people forget; it's what applies bundle migrations and rebuilds Oro's own config/asset caches.

Where to look first, in order

1. Resources/config/oro/system_configuration.yml — the admin config tree, field names, and default values. This is the source of truth for what's configurable.
2. DependencyInjection/Configuration.php and the extension class — how defaults are seeded and whether values are scoped per website.
3. Form/Type/ — the actual settings form; this tells you what validation and sanitization exist.
4. Resources/views/ — where the values are read and rendered (a <style> block, a layout override, or a Twig extension).
5. README compatibility matrix — check your Oro minor version before anything else. A 12-star, zero-dependent bundle is unlikely to have broad CI coverage across Oro 5.x/6.x/7.x.

First use case: set a storefront logo and brand color for a single website without touching git. Enable the bundle, clear caches, open System → Configuration → Commerce → Design, find the new section, upload a logo, set a hex color, save, then hard-reload the storefront. If that works end to end, the integration is sound and everything after is scope management.

Implementation Patterns

Lean on CSS custom properties, not compiled SCSS. The whole value of a UI-configurable theme is skipping the asset build. If the bundle emits CSS variables, treat them as the contract and write your own stylesheet as var(--primary-color, #1a73e8) with fallbacks so an unset field never breaks layout.

// your child theme, extends the bundle's output
.btn--primary {
    background: var(--ys-primary-color, #{$fallback-primary});
    font-family: var(--ys-font-body, $fallback-font);
}

Scope-aware reads. Oro system config is scoped by organization and website. If the bundle wires through Oracle's ConfigManager, read it with explicit scope rather than relying on the ambient one:

$config = $this->configManager->get('ys_tools.default_theme.logo', null, false, $website);

Anything you render server-side for a multi-website install should pass a Website explicitly; ambient scope resolution is where "works locally, wrong on the second storefront" bugs live.

Keep the child theme shallow. Don't fork Oro's default theme to use this bundle. Declare a thin child theme whose theme.yml sets parent: default, lists only your overrides, and lets the bundle supply the variable values. Forking the parent means every Oro patch becomes a merge.

Use the free-form CSS field as an escape hatch with a budget. It's the field that inevitably accumulates !important and #storefront > div > div:nth-child(3) selectors. Cap it, review it, and migrate anything durable into the child theme's SCSS. If the bundle lets you store raw CSS, confirm it strips </style> and script-bearing values before rendering — an admin-only field is still an XSS surface if a lower-privileged role can reach it.

Seed defaults in code, not by hand. For new environments, ship a fixture or a small console command that writes your baseline palette via ConfigManager so staging and production start identical. Config lives in the database, which means it is not in git and not covered by your Laravel-style migrations — treat the DB rows as the artifact that needs a reproducible path.

Extend the settings form rather than forking it. If you need one more field, a Symfony form type extension against the bundle's form type survives upgrades; copying the form class does not.

Integration tips:

• Render via a Twig block override in your child theme ({% block stylesheets %}{{ parent() }}<style>…</style>{% endblock %}) instead of replacing whole layout templates — narrower blast radius across Oro upgrades.
• If the bundle ships SCSS instead of inline CSS, its file must be listed in theme.yml under styles, and every value change then requires oro:assets:build. Check which model you're in before promising merchants a no-deploy experience.
• Wire a smoke test into CI that fetches the storefront homepage and asserts the configured CSS variable is present. Cheap, and it catches asset-cache regressions immediately.

Gotchas and Tips

Three cache layers, and you'll only clear two. Oro's config cache, the compiled asset output, and the browser/CDN all cache independently. Save a value → storefront unchanged is almost always layer two or three. Do oro:assets:build (or at minimum cache:clear on the right env) and a hard reload before debugging the bundle itself.

Scope precedence silently wins. A value set at Global is shadowed by any website- or organization-level override, including empty ones. When "the logo won't change," check the effective value at the current website scope first — not the global form. debug:config won't help here; Oro config is DB-backed, so write a throwaway command that dumps ConfigManager::get() for the target website.

Logo uploads go through Oro's file storage. Broken images after upload are usually permissions on var/attachments or a Flysystem/Gaufrette adapter misconfiguration, not the bundle. Verify file storage works in your environment before blaming the theme.

Pin the version and plan to fork. Twelve stars, zero dependents, and no meaningful downstream usage means no one else is finding the bugs for you. Pin an exact version in composer.json, read the full diff before bumping, and keep a local fork path open. Assume no test suite — your homepage smoke test is the regression net.

Bundle registration order matters. If another theme or design bundle also touches the same config tree or layout blocks, Oro's bundles.yml priority decides who wins. Symptom: your settings render but are ignored. Adjust priority, or have the second bundle read the first bundle's variables instead of declaring its own.

Don't trust the config form's validation for CSS. If the field accepts arbitrary CSS, a typo (unclosed brace, missing semicolon) can cascade and blank out sections of the storefront. Consider validating with a lightweight CSS parser, or at minimum render the block behind a try/catch and keep a "reset to defaults" path documented for support.

Rollback is a database operation. Because values live in oro_config, a bad bulk edit has no git revert. Snapshot the relevant config rows before a merchant does a rebrand push, and know the table/keys you'd restore.

Oro version compatibility is the real gate. Before investing in customization, confirm the bundle's declared support against your exact Oro minor. Symfony bundle conventions changed across 4.4→5.x→6.x (bundle registration, DI autoconfiguration), and a small bundle may target one generation only. If it's stale, a forked copy with a compatibility patch is usually cheaper than fighting it.